VirtualBox

source: vbox/trunk/include/iprt/mem.h@ 33540

Last change on this file since 33540 was 33540, checked in by vboxsync, 14 years ago

*: spelling fixes, thanks Timeless!

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 34.3 KB
Line 
1/** @file
2 * IPRT - Memory Management and Manipulation.
3 */
4
5/*
6 * Copyright (C) 2006-2010 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_mem_h
27#define ___iprt_mem_h
28
29
30#include <iprt/cdefs.h>
31#include <iprt/types.h>
32#ifdef __cplusplus /** @todo remove when spitting. */
33# include <iprt/cpp/autores.h>
34#endif
35
36
37#ifdef IN_RC
38# error "There are no RTMem APIs available Guest Context!"
39#endif
40
41
42/** @defgroup grp_rt_mem RTMem - Memory Management and Manipulation
43 * @ingroup grp_rt
44 * @{
45 */
46
47RT_C_DECLS_BEGIN
48
49/** @def RTMEM_ALIGNMENT
50 * The alignment of the memory blocks returned by RTMemAlloc(), RTMemAllocZ(),
51 * RTMemRealloc(), RTMemTmpAlloc() and RTMemTmpAllocZ() for allocations greater
52 * than RTMEM_ALIGNMENT.
53 *
54 * @note This alignment is not forced if the electric fence is active!
55 */
56#define RTMEM_ALIGNMENT 8
57
58/** @def RTMEM_TAG
59 * The default allocation tag used by the RTMem allocation APIs.
60 *
61 * When not defined before the inclusion of iprt/mem.h or iprt/memobj.h, this
62 * will default to the pointer to the current file name. The memory API will
63 * make of use of this as pointer to a volatile but read-only string.
64 */
65#ifndef RTMEM_TAG
66# define RTMEM_TAG (__FILE__)
67#endif
68
69
70/** @name Allocate temporary memory.
71 * @{ */
72/**
73 * Allocates temporary memory with default tag.
74 *
75 * Temporary memory blocks are used for not too large memory blocks which
76 * are believed not to stick around for too long. Using this API instead
77 * of RTMemAlloc() not only gives the heap manager room for optimization
78 * but makes the code easier to read.
79 *
80 * @returns Pointer to the allocated memory.
81 * @returns NULL on failure, assertion raised in strict builds.
82 * @param cb Size in bytes of the memory block to allocated.
83 */
84#define RTMemTmpAlloc(cb) RTMemTmpAllocTag((cb), RTMEM_TAG)
85
86/**
87 * Allocates temporary memory with custom tag.
88 *
89 * Temporary memory blocks are used for not too large memory blocks which
90 * are believed not to stick around for too long. Using this API instead
91 * of RTMemAlloc() not only gives the heap manager room for optimization
92 * but makes the code easier to read.
93 *
94 * @returns Pointer to the allocated memory.
95 * @returns NULL on failure, assertion raised in strict builds.
96 * @param cb Size in bytes of the memory block to allocated.
97 * @param pszTag Allocation tag used for statistics and such.
98 */
99RTDECL(void *) RTMemTmpAllocTag(size_t cb, const char *pszTag) RT_NO_THROW;
100
101/**
102 * Allocates zero'd temporary memory with default tag.
103 *
104 * Same as RTMemTmpAlloc() but the memory will be zero'd.
105 *
106 * @returns Pointer to the allocated memory.
107 * @returns NULL on failure, assertion raised in strict builds.
108 * @param cb Size in bytes of the memory block to allocated.
109 */
110#define RTMemTmpAllocZ(cb) RTMemTmpAllocZTag((cb), RTMEM_TAG)
111
112/**
113 * Allocates zero'd temporary memory with custom tag.
114 *
115 * Same as RTMemTmpAlloc() but the memory will be zero'd.
116 *
117 * @returns Pointer to the allocated memory.
118 * @returns NULL on failure, assertion raised in strict builds.
119 * @param cb Size in bytes of the memory block to allocated.
120 * @param pszTag Allocation tag used for statistics and such.
121 */
122RTDECL(void *) RTMemTmpAllocZTag(size_t cb, const char *pszTag) RT_NO_THROW;
123
124/**
125 * Free temporary memory.
126 *
127 * @param pv Pointer to memory block.
128 */
129RTDECL(void) RTMemTmpFree(void *pv) RT_NO_THROW;
130
131/** @} */
132
133
134/**
135 * Allocates memory with default tag.
136 *
137 * @returns Pointer to the allocated memory.
138 * @returns NULL on failure, assertion raised in strict builds.
139 * @param cb Size in bytes of the memory block to allocated.
140 * @param pszTag Allocation tag used for statistics and such.
141 */
142#define RTMemAlloc(cb) RTMemAllocTag((cb), RTMEM_TAG)
143
144/**
145 * Allocates memory with custom tag.
146 *
147 * @returns Pointer to the allocated memory.
148 * @returns NULL on failure, assertion raised in strict builds.
149 * @param cb Size in bytes of the memory block to allocated.
150 * @param pszTag Allocation tag used for statistics and such.
151 */
152RTDECL(void *) RTMemAllocTag(size_t cb, const char *pszTag) RT_NO_THROW;
153
154/**
155 * Allocates zero'd memory with default tag.
156 *
157 * Instead of memset(pv, 0, sizeof()) use this when you want zero'd
158 * memory. This keeps the code smaller and the heap can skip the memset
159 * in about 0.42% of calls :-).
160 *
161 * @returns Pointer to the allocated memory.
162 * @returns NULL on failure.
163 * @param cb Size in bytes of the memory block to allocated.
164 */
165#define RTMemAllocZ(cb) RTMemAllocZTag((cb), RTMEM_TAG)
166
167/**
168 * Allocates zero'd memory with custom tag.
169 *
170 * Instead of memset(pv, 0, sizeof()) use this when you want zero'd
171 * memory. This keeps the code smaller and the heap can skip the memset
172 * in about 0.42% of calls :-).
173 *
174 * @returns Pointer to the allocated memory.
175 * @returns NULL on failure.
176 * @param cb Size in bytes of the memory block to allocated.
177 * @param pszTag Allocation tag used for statistics and such.
178 */
179RTDECL(void *) RTMemAllocZTag(size_t cb, const char *pszTag) RT_NO_THROW;
180
181/**
182 * Wrapper around RTMemAlloc for automatically aligning variable sized
183 * allocations so that the various electric fence heaps works correctly.
184 *
185 * @returns See RTMemAlloc.
186 * @param cbUnaligned The unaligned size.
187 */
188#define RTMemAllocVar(cbUnaligned) RTMemAllocVarTag((cbUnaligned), RTMEM_TAG)
189
190/**
191 * Wrapper around RTMemAllocTag for automatically aligning variable sized
192 * allocations so that the various electric fence heaps works correctly.
193 *
194 * @returns See RTMemAlloc.
195 * @param cbUnaligned The unaligned size.
196 * @param pszTag Allocation tag used for statistics and such.
197 */
198RTDECL(void *) RTMemAllocVarTag(size_t cbUnaligned, const char *pszTag) RT_NO_THROW;
199
200/**
201 * Wrapper around RTMemAllocZ for automatically aligning variable sized
202 * allocations so that the various electric fence heaps works correctly.
203 *
204 * @returns See RTMemAllocZ.
205 * @param cbUnaligned The unaligned size.
206 */
207#define RTMemAllocZVar(cbUnaligned) RTMemAllocZVarTag((cbUnaligned), RTMEM_TAG)
208
209/**
210 * Wrapper around RTMemAllocZTag for automatically aligning variable sized
211 * allocations so that the various electric fence heaps works correctly.
212 *
213 * @returns See RTMemAllocZ.
214 * @param cbUnaligned The unaligned size.
215 * @param pszTag Allocation tag used for statistics and such.
216 */
217RTDECL(void *) RTMemAllocZVarTag(size_t cbUnaligned, const char *pszTag) RT_NO_THROW;
218
219/**
220 * Duplicates a chunk of memory into a new heap block (default tag).
221 *
222 * @returns New heap block with the duplicate data.
223 * @returns NULL if we're out of memory.
224 * @param pvSrc The memory to duplicate.
225 * @param cb The amount of memory to duplicate.
226 */
227#define RTMemDup(pvSrc, cb) RTMemDupTag((pvSrc), (cb), RTMEM_TAG)
228
229/**
230 * Duplicates a chunk of memory into a new heap block (custom tag).
231 *
232 * @returns New heap block with the duplicate data.
233 * @returns NULL if we're out of memory.
234 * @param pvSrc The memory to duplicate.
235 * @param cb The amount of memory to duplicate.
236 * @param pszTag Allocation tag used for statistics and such.
237 */
238RTDECL(void *) RTMemDupTag(const void *pvSrc, size_t cb, const char *pszTag) RT_NO_THROW;
239
240/**
241 * Duplicates a chunk of memory into a new heap block with some additional
242 * zeroed memory (default tag).
243 *
244 * @returns New heap block with the duplicate data.
245 * @returns NULL if we're out of memory.
246 * @param pvSrc The memory to duplicate.
247 * @param cbSrc The amount of memory to duplicate.
248 * @param cbExtra The amount of extra memory to allocate and zero.
249 */
250#define RTMemDupEx(pvSrc, cbSrc, cbExtra) RTMemDupExTag((pvSrc), (cbSrc), (cbExtra), RTMEM_TAG)
251
252/**
253 * Duplicates a chunk of memory into a new heap block with some additional
254 * zeroed memory (default tag).
255 *
256 * @returns New heap block with the duplicate data.
257 * @returns NULL if we're out of memory.
258 * @param pvSrc The memory to duplicate.
259 * @param cbSrc The amount of memory to duplicate.
260 * @param cbExtra The amount of extra memory to allocate and zero.
261 * @param pszTag Allocation tag used for statistics and such.
262 */
263RTDECL(void *) RTMemDupExTag(const void *pvSrc, size_t cbSrc, size_t cbExtra, const char *pszTag) RT_NO_THROW;
264
265/**
266 * Reallocates memory with default tag.
267 *
268 * @returns Pointer to the allocated memory.
269 * @returns NULL on failure.
270 * @param pvOld The memory block to reallocate.
271 * @param cbNew The new block size (in bytes).
272 */
273#define RTMemRealloc(pvOld, cbNew) RTMemReallocTag((pvOld), (cbNew), RTMEM_TAG)
274
275/**
276 * Reallocates memory with custom tag.
277 *
278 * @returns Pointer to the allocated memory.
279 * @returns NULL on failure.
280 * @param pvOld The memory block to reallocate.
281 * @param cbNew The new block size (in bytes).
282 * @param pszTag Allocation tag used for statistics and such.
283 */
284RTDECL(void *) RTMemReallocTag(void *pvOld, size_t cbNew, const char *pszTag) RT_NO_THROW;
285
286/**
287 * Frees memory.
288 *
289 * @param pv Pointer to memory block.
290 */
291RTDECL(void) RTMemFree(void *pv) RT_NO_THROW;
292
293
294
295/** @def RTR0MemAllocEx and RTR0MemAllocExTag flags.
296 * @{ */
297/** The returned memory should be zeroed. */
298#define RTMEMALLOCEX_FLAGS_ZEROED RT_BIT(0)
299/** It must be load code into the returned memory block and execute it. */
300#define RTMEMALLOCEX_FLAGS_EXEC RT_BIT(1)
301/** Allocation from any context.
302 * Will return VERR_NOT_SUPPORTED if not supported. */
303#define RTMEMALLOCEX_FLAGS_ANY_CTX_ALLOC RT_BIT(2)
304/** Allocate the memory such that it can be freed from any context.
305 * Will return VERR_NOT_SUPPORTED if not supported. */
306#define RTMEMALLOCEX_FLAGS_ANY_CTX_FREE RT_BIT(3)
307/** Allocate and free from any context.
308 * Will return VERR_NOT_SUPPORTED if not supported. */
309#define RTMEMALLOCEX_FLAGS_ANY_CTX (RTMEMALLOCEX_FLAGS_ANY_CTX_ALLOC | RTMEMALLOCEX_FLAGS_ANY_CTX_FREE)
310/** Mask of valid flags. */
311#define RTMEMALLOCEX_FLAGS_VALID_MASK UINT32_C(0x0000000f)
312/** @} */
313
314/**
315 * Extended heap allocation API, default tag.
316 *
317 * @returns IPRT status code.
318 * @retval VERR_NO_MEMORY if we're out of memory.
319 * @retval VERR_NO_EXEC_MEMORY if we're out of executable memory.
320 * @retval VERR_NOT_SUPPORTED if any of the specified flags are unsupported.
321 *
322 * @param cb The amount of memory to allocate.
323 * @param cbAlignment The alignment requirements. Use 0 to indicate
324 * default alignment.
325 * @param fFlags A combination of the RTMEMALLOCEX_FLAGS_XXX
326 * defines.
327 * @param ppv Where to return the memory.
328 */
329#define RTMemAllocEx(cb, cbAlignment, fFlags, ppv) RTMemAllocExTag((cb), (cbAlignment), (fFlags), RTMEM_TAG, (ppv))
330
331/**
332 * Extended heap allocation API, custom tag.
333 *
334 * @returns IPRT status code.
335 * @retval VERR_NO_MEMORY if we're out of memory.
336 * @retval VERR_NO_EXEC_MEMORY if we're out of executable memory.
337 * @retval VERR_NOT_SUPPORTED if any of the specified flags are unsupported.
338 *
339 * @param cb The amount of memory to allocate.
340 * @param cbAlignment The alignment requirements. Use 0 to indicate
341 * default alignment.
342 * @param fFlags A combination of the RTMEMALLOCEX_FLAGS_XXX
343 * defines.
344 * @param pszTag The tag.
345 * @param ppv Where to return the memory.
346 */
347RTDECL(int) RTMemAllocExTag(size_t cb, size_t cbAlignment, uint32_t fFlags, const char *pszTag, void **ppv) RT_NO_THROW;
348
349/**
350 * For freeing memory allocated by RTMemAllocEx or RTMemAllocExTag.
351 *
352 * @param pv What to free, NULL is fine.
353 * @param cb The amount of allocated memory.
354 */
355RTDECL(void) RTMemFreeEx(void *pv, size_t cb) RT_NO_THROW;
356
357
358
359/**
360 * Allocates memory which may contain code (default tag).
361 *
362 * @returns Pointer to the allocated memory.
363 * @returns NULL on failure.
364 * @param cb Size in bytes of the memory block to allocate.
365 */
366#define RTMemExecAlloc(cb) RTMemExecAllocTag((cb), RTMEM_TAG)
367
368/**
369 * Allocates memory which may contain code (custom tag).
370 *
371 * @returns Pointer to the allocated memory.
372 * @returns NULL on failure.
373 * @param cb Size in bytes of the memory block to allocate.
374 * @param pszTag Allocation tag used for statistics and such.
375 */
376RTDECL(void *) RTMemExecAllocTag(size_t cb, const char *pszTag) RT_NO_THROW;
377
378/**
379 * Free executable/read/write memory allocated by RTMemExecAlloc().
380 *
381 * @param pv Pointer to memory block.
382 * @param cb The allocation size.
383 */
384RTDECL(void) RTMemExecFree(void *pv, size_t cb) RT_NO_THROW;
385
386#if defined(IN_RING0) && defined(RT_ARCH_AMD64) && defined(RT_OS_LINUX)
387/**
388 * Donate read+write+execute memory to the exec heap.
389 *
390 * This API is specific to AMD64 and Linux/GNU. A kernel module that desires to
391 * use RTMemExecAlloc on AMD64 Linux/GNU will have to donate some statically
392 * allocated memory in the module if it wishes for GCC generated code to work.
393 * GCC can only generate modules that work in the address range ~2GB to ~0
394 * currently.
395 *
396 * The API only accept one single donation.
397 *
398 * @returns IPRT status code.
399 * @param pvMemory Pointer to the memory block.
400 * @param cb The size of the memory block.
401 */
402RTR0DECL(int) RTR0MemExecDonate(void *pvMemory, size_t cb) RT_NO_THROW;
403#endif /* R0+AMD64+LINUX */
404
405/**
406 * Allocate page aligned memory with default tag.
407 *
408 * @returns Pointer to the allocated memory.
409 * @returns NULL if we're out of memory.
410 * @param cb Size of the memory block. Will be rounded up to page size.
411 */
412#define RTMemPageAlloc(cb) RTMemPageAllocTag((cb), RTMEM_TAG)
413
414/**
415 * Allocate page aligned memory with custom tag.
416 *
417 * @returns Pointer to the allocated memory.
418 * @returns NULL if we're out of memory.
419 * @param cb Size of the memory block. Will be rounded up to page size.
420 * @param pszTag Allocation tag used for statistics and such.
421 */
422RTDECL(void *) RTMemPageAllocTag(size_t cb, const char *pszTag) RT_NO_THROW;
423
424/**
425 * Allocate zero'd page aligned memory with default tag.
426 *
427 * @returns Pointer to the allocated memory.
428 * @returns NULL if we're out of memory.
429 * @param cb Size of the memory block. Will be rounded up to page size.
430 */
431#define RTMemPageAllocZ(cb) RTMemPageAllocZTag((cb), RTMEM_TAG)
432
433/**
434 * Allocate zero'd page aligned memory with custom tag.
435 *
436 * @returns Pointer to the allocated memory.
437 * @returns NULL if we're out of memory.
438 * @param cb Size of the memory block. Will be rounded up to page size.
439 * @param pszTag Allocation tag used for statistics and such.
440 */
441RTDECL(void *) RTMemPageAllocZTag(size_t cb, const char *pszTag) RT_NO_THROW;
442
443/**
444 * Free a memory block allocated with RTMemPageAlloc() or RTMemPageAllocZ().
445 *
446 * @param pv Pointer to the block as it was returned by the allocation function.
447 * NULL will be ignored.
448 * @param cb The allocation size. Will be rounded up to page size.
449 * Ignored if @a pv is NULL.
450 */
451RTDECL(void) RTMemPageFree(void *pv, size_t cb) RT_NO_THROW;
452
453/** Page level protection flags for RTMemProtect().
454 * @{
455 */
456/** No access at all. */
457#define RTMEM_PROT_NONE 0
458/** Read access. */
459#define RTMEM_PROT_READ 1
460/** Write access. */
461#define RTMEM_PROT_WRITE 2
462/** Execute access. */
463#define RTMEM_PROT_EXEC 4
464/** @} */
465
466/**
467 * Change the page level protection of a memory region.
468 *
469 * @returns iprt status code.
470 * @param pv Start of the region. Will be rounded down to nearest page boundary.
471 * @param cb Size of the region. Will be rounded up to the nearest page boundary.
472 * @param fProtect The new protection, a combination of the RTMEM_PROT_* defines.
473 */
474RTDECL(int) RTMemProtect(void *pv, size_t cb, unsigned fProtect) RT_NO_THROW;
475
476/**
477 * Goes thru some pains to make sure the specified memory block is thoroughly
478 * scrambled.
479 *
480 * @param pv The start of the memory block.
481 * @param cb The size of the memory block.
482 * @param cMinPasses The minimum number of passes to make.
483 */
484RTDECL(void) RTMemWipeThoroughly(void *pv, size_t cb, size_t cMinPasses) RT_NO_THROW;
485
486#ifdef IN_RING0
487
488/**
489 * Allocates physical contiguous memory (below 4GB).
490 * The allocation is page aligned and the content is undefined.
491 *
492 * @returns Pointer to the memory block. This is page aligned.
493 * @param pPhys Where to store the physical address.
494 * @param cb The allocation size in bytes. This is always
495 * rounded up to PAGE_SIZE.
496 */
497RTR0DECL(void *) RTMemContAlloc(PRTCCPHYS pPhys, size_t cb) RT_NO_THROW;
498
499/**
500 * Frees memory allocated ysing RTMemContAlloc().
501 *
502 * @param pv Pointer to return from RTMemContAlloc().
503 * @param cb The cb parameter passed to RTMemContAlloc().
504 */
505RTR0DECL(void) RTMemContFree(void *pv, size_t cb) RT_NO_THROW;
506
507/**
508 * Copy memory from an user mode buffer into a kernel buffer.
509 *
510 * @retval VINF_SUCCESS on success.
511 * @retval VERR_ACCESS_DENIED on error.
512 *
513 * @param pvDst The kernel mode destination address.
514 * @param R3PtrSrc The user mode source address.
515 * @param cb The number of bytes to copy.
516 */
517RTR0DECL(int) RTR0MemUserCopyFrom(void *pvDst, RTR3PTR R3PtrSrc, size_t cb);
518
519/**
520 * Copy memory from a kernel buffer into a user mode one.
521 *
522 * @retval VINF_SUCCESS on success.
523 * @retval VERR_ACCESS_DENIED on error.
524 *
525 * @param R3PtrDst The user mode destination address.
526 * @param pvSrc The kernel mode source address.
527 * @param cb The number of bytes to copy.
528 */
529RTR0DECL(int) RTR0MemUserCopyTo(RTR3PTR R3PtrDst, void const *pvSrc, size_t cb);
530
531/**
532 * Tests if the specified address is in the user addressable range.
533 *
534 * This function does not check whether the memory at that address is accessible
535 * or anything of that sort, only if the address it self is in the user mode
536 * range.
537 *
538 * @returns true if it's in the user addressable range. false if not.
539 * @param R3Ptr The user mode pointer to test.
540 *
541 * @remarks Some systems may have overlapping kernel and user address ranges.
542 * One prominent example of this is the x86 version of Mac OS X. Use
543 * RTR0MemAreKrnlAndUsrDifferent() to check.
544 */
545RTR0DECL(bool) RTR0MemUserIsValidAddr(RTR3PTR R3Ptr);
546
547/**
548 * Tests if the specified address is in the kernel mode range.
549 *
550 * This function does not check whether the memory at that address is accessible
551 * or anything of that sort, only if the address it self is in the kernel mode
552 * range.
553 *
554 * @returns true if it's in the kernel range. false if not.
555 * @param pv The alleged kernel mode pointer.
556 *
557 * @remarks Some systems may have overlapping kernel and user address ranges.
558 * One prominent example of this is the x86 version of Mac OS X. Use
559 * RTR0MemAreKrnlAndUsrDifferent() to check.
560 */
561RTR0DECL(bool) RTR0MemKernelIsValidAddr(void *pv);
562
563/**
564 * Are user mode and kernel mode address ranges distinctly different.
565 *
566 * This determines whether RTR0MemKernelIsValidAddr and RTR0MemUserIsValidAddr
567 * can be used for deciding whether some arbitrary address is a user mode or a
568 * kernel mode one.
569 *
570 * @returns true if they are, false if not.
571 */
572RTR0DECL(bool) RTR0MemAreKrnlAndUsrDifferent(void);
573
574#endif /* IN_RING0 */
575
576
577/** @name Electrical Fence Version of some APIs.
578 * @{
579 */
580
581/**
582 * Same as RTMemTmpAllocTag() except that it's fenced.
583 *
584 * @returns Pointer to the allocated memory.
585 * @returns NULL on failure.
586 * @param cb Size in bytes of the memory block to allocate.
587 * @param pszTag Allocation tag used for statistics and such.
588 */
589RTDECL(void *) RTMemEfTmpAlloc(size_t cb, const char *pszTag, RT_SRC_POS_DECL) RT_NO_THROW;
590
591/**
592 * Same as RTMemTmpAllocZTag() except that it's fenced.
593 *
594 * @returns Pointer to the allocated memory.
595 * @returns NULL on failure.
596 * @param cb Size in bytes of the memory block to allocate.
597 * @param pszTag Allocation tag used for statistics and such.
598 */
599RTDECL(void *) RTMemEfTmpAllocZ(size_t cb, const char *pszTag, RT_SRC_POS_DECL) RT_NO_THROW;
600
601/**
602 * Same as RTMemTmpFree() except that it's for fenced memory.
603 *
604 * @param pv Pointer to memory block.
605 */
606RTDECL(void) RTMemEfTmpFree(void *pv, RT_SRC_POS_DECL) RT_NO_THROW;
607
608/**
609 * Same as RTMemAllocTag() except that it's fenced.
610 *
611 * @returns Pointer to the allocated memory. Free with RTMemEfFree().
612 * @returns NULL on failure.
613 * @param cb Size in bytes of the memory block to allocate.
614 * @param pszTag Allocation tag used for statistics and such.
615 */
616RTDECL(void *) RTMemEfAlloc(size_t cb, const char *pszTag, RT_SRC_POS_DECL) RT_NO_THROW;
617
618/**
619 * Same as RTMemAllocZTag() except that it's fenced.
620 *
621 * @returns Pointer to the allocated memory.
622 * @returns NULL on failure.
623 * @param cb Size in bytes of the memory block to allocate.
624 * @param pszTag Allocation tag used for statistics and such.
625 */
626RTDECL(void *) RTMemEfAllocZ(size_t cb, const char *pszTag, RT_SRC_POS_DECL) RT_NO_THROW;
627
628/**
629 * Same as RTMemAllocVarTag() except that it's fenced.
630 *
631 * @returns Pointer to the allocated memory. Free with RTMemEfFree().
632 * @returns NULL on failure.
633 * @param cbUnaligned Size in bytes of the memory block to allocate.
634 * @param pszTag Allocation tag used for statistics and such.
635 */
636RTDECL(void *) RTMemEfAllocVar(size_t cbUnaligned, const char *pszTag, RT_SRC_POS_DECL) RT_NO_THROW;
637
638/**
639 * Same as RTMemAllocZVarTag() except that it's fenced.
640 *
641 * @returns Pointer to the allocated memory.
642 * @returns NULL on failure.
643 * @param cbUnaligned Size in bytes of the memory block to allocate.
644 * @param pszTag Allocation tag used for statistics and such.
645 */
646RTDECL(void *) RTMemEfAllocZVar(size_t cbUnaligned, const char *pszTag, RT_SRC_POS_DECL) RT_NO_THROW;
647
648/**
649 * Same as RTMemReallocTag() except that it's fenced.
650 *
651 * @returns Pointer to the allocated memory.
652 * @returns NULL on failure.
653 * @param pvOld The memory block to reallocate.
654 * @param cbNew The new block size (in bytes).
655 * @param pszTag Allocation tag used for statistics and such.
656 */
657RTDECL(void *) RTMemEfRealloc(void *pvOld, size_t cbNew, const char *pszTag, RT_SRC_POS_DECL) RT_NO_THROW;
658
659/**
660 * Free memory allocated by any of the RTMemEf* allocators.
661 *
662 * @param pv Pointer to memory block.
663 */
664RTDECL(void) RTMemEfFree(void *pv, RT_SRC_POS_DECL) RT_NO_THROW;
665
666/**
667 * Same as RTMemDupTag() except that it's fenced.
668 *
669 * @returns New heap block with the duplicate data.
670 * @returns NULL if we're out of memory.
671 * @param pvSrc The memory to duplicate.
672 * @param cb The amount of memory to duplicate.
673 * @param pszTag Allocation tag used for statistics and such.
674 */
675RTDECL(void *) RTMemEfDup(const void *pvSrc, size_t cb, const char *pszTag, RT_SRC_POS_DECL) RT_NO_THROW;
676
677/**
678 * Same as RTMemEfDupExTag except that it's fenced.
679 *
680 * @returns New heap block with the duplicate data.
681 * @returns NULL if we're out of memory.
682 * @param pvSrc The memory to duplicate.
683 * @param cbSrc The amount of memory to duplicate.
684 * @param cbExtra The amount of extra memory to allocate and zero.
685 * @param pszTag Allocation tag used for statistics and such.
686 */
687RTDECL(void *) RTMemEfDupEx(const void *pvSrc, size_t cbSrc, size_t cbExtra, const char *pszTag, RT_SRC_POS_DECL) RT_NO_THROW;
688
689/** @def RTMEM_WRAP_TO_EF_APIS
690 * Define RTMEM_WRAP_TO_EF_APIS to wrap RTMem APIs to RTMemEf APIs.
691 */
692#if defined(RTMEM_WRAP_TO_EF_APIS) && defined(IN_RING3) && !defined(RTMEM_NO_WRAP_TO_EF_APIS)
693# define RTMemTmpAllocTag(cb, pszTag) RTMemEfTmpAlloc((cb), (pszTag), RT_SRC_POS)
694# define RTMemTmpAllocZTag(cb, pszTag) RTMemEfTmpAllocZ((cb), (pszTag), RT_SRC_POS)
695# define RTMemTmpFree(pv) RTMemEfTmpFree((pv), RT_SRC_POS)
696# define RTMemAllocTag(cb, pszTag) RTMemEfAlloc((cb), (pszTag), RT_SRC_POS)
697# define RTMemAllocZTag(cb, pszTag) RTMemEfAllocZ((cb), (pszTag), RT_SRC_POS)
698# define RTMemAllocVarTag(cbUnaligned, pszTag) RTMemEfAllocVar((cbUnaligned), (pszTag), RT_SRC_POS)
699# define RTMemAllocZVarTag(cbUnaligned, pszTag) RTMemEfAllocZVar((cbUnaligned), (pszTag), RT_SRC_POS)
700# define RTMemReallocTag(pvOld, cbNew, pszTag) RTMemEfRealloc((pvOld), (cbNew), (pszTag), RT_SRC_POS)
701# define RTMemFree(pv) RTMemEfFree((pv), RT_SRC_POS)
702# define RTMemDupTag(pvSrc, cb, pszTag) RTMemEfDup((pvSrc), (cb), (pszTag), RT_SRC_POS)
703# define RTMemDupExTag(pvSrc, cbSrc, cbExtra, pszTag) RTMemEfDupEx((pvSrc), (cbSrc), (cbExtra), (pszTag), RT_SRC_POS)
704#endif
705#ifdef DOXYGEN_RUNNING
706# define RTMEM_WRAP_TO_EF_APIS
707#endif
708
709/**
710 * Fenced drop-in replacement for RTMemTmpAllocTag.
711 * @copydoc RTMemTmpAllocTag
712 */
713RTDECL(void *) RTMemEfTmpAllocNP(size_t cb, const char *pszTag) RT_NO_THROW;
714
715/**
716 * Fenced drop-in replacement for RTMemTmpAllocZTag.
717 * @copydoc RTMemTmpAllocZTag
718 */
719RTDECL(void *) RTMemEfTmpAllocZNP(size_t cb, const char *pszTag) RT_NO_THROW;
720
721/**
722 * Fenced drop-in replacement for RTMemTmpFreeTag.
723 * @copydoc RTMemTmpFreeTag
724 */
725RTDECL(void) RTMemEfTmpFreeNP(void *pv) RT_NO_THROW;
726
727/**
728 * Fenced drop-in replacement for RTMemAllocTag.
729 * @copydoc RTMemAllocTag
730 */
731RTDECL(void *) RTMemEfAllocNP(size_t cb, const char *pszTag) RT_NO_THROW;
732
733/**
734 * Fenced drop-in replacement for RTMemAllocZTag.
735 * @copydoc RTMemAllocZTag
736 */
737RTDECL(void *) RTMemEfAllocZNP(size_t cb, const char *pszTag) RT_NO_THROW;
738
739/**
740 * Fenced drop-in replacement for RTMemAllocVarTag
741 * @copydoc RTMemAllocVarTag
742 */
743RTDECL(void *) RTMemEfAllocVarNP(size_t cbUnaligned, const char *pszTag) RT_NO_THROW;
744
745/**
746 * Fenced drop-in replacement for RTMemAllocZVarTag.
747 * @copydoc RTMemAllocZVarTag
748 */
749RTDECL(void *) RTMemEfAllocZVarNP(size_t cbUnaligned, const char *pszTag) RT_NO_THROW;
750
751/**
752 * Fenced drop-in replacement for RTMemReallocTag.
753 * @copydoc RTMemReallocTag
754 */
755RTDECL(void *) RTMemEfReallocNP(void *pvOld, size_t cbNew, const char *pszTag) RT_NO_THROW;
756
757/**
758 * Fenced drop-in replacement for RTMemFree.
759 * @copydoc RTMemFree
760 */
761RTDECL(void) RTMemEfFreeNP(void *pv) RT_NO_THROW;
762
763/**
764 * Fenced drop-in replacement for RTMemDupExTag.
765 * @copydoc RTMemDupExTag
766 */
767RTDECL(void *) RTMemEfDupNP(const void *pvSrc, size_t cb, const char *pszTag) RT_NO_THROW;
768
769/**
770 * Fenced drop-in replacement for RTMemDupExTag.
771 * @copydoc RTMemDupExTag
772 */
773RTDECL(void *) RTMemEfDupExNP(const void *pvSrc, size_t cbSrc, size_t cbExtra, const char *pszTag) RT_NO_THROW;
774
775/** @} */
776
777RT_C_DECLS_END
778
779
780#ifdef __cplusplus /** @todo Split this out into iprt/cpp/mem.h! */
781# include <iprt/assert.h>
782
783/**
784 * Template function wrapping RTMemFree to get the correct Destruct
785 * signature for RTAutoRes.
786 *
787 * We can't use a more complex template here, because the g++ on RHEL 3
788 * chokes on it with an internal compiler error.
789 *
790 * @tparam T The data type that's being managed.
791 * @param aMem Pointer to the memory that should be free.
792 */
793template <class T>
794inline void RTMemAutoDestructor(T *aMem) RT_NO_THROW
795{
796 RTMemFree(aMem);
797}
798
799
800/**
801 * RTMemAutoPtr allocator which uses RTMemTmpAlloc().
802 *
803 * @returns Allocated memory on success, NULL on failure.
804 * @param pvOld What to reallocate, shall always be NULL.
805 * @param cbNew The amount of memory to allocate (in bytes).
806 */
807inline void *RTMemTmpAutoAllocator(void *pvOld, size_t cbNew) RT_NO_THROW
808{
809 AssertReturn(!pvOld, NULL);
810 return RTMemTmpAlloc(cbNew);
811}
812
813
814/**
815 * Template function wrapping RTMemTmpFree to get the correct Destruct
816 * signature for RTAutoRes.
817 *
818 * We can't use a more complex template here, because the g++ on RHEL 3
819 * chokes on it with an internal compiler error.
820 *
821 * @tparam T The data type that's being managed.
822 * @param aMem Pointer to the memory that should be free.
823 */
824template <class T>
825inline void RTMemTmpAutoDestructor(T *aMem) RT_NO_THROW
826{
827 RTMemTmpFree(aMem);
828}
829
830
831/**
832 * Template function wrapping RTMemEfFree to get the correct Destruct
833 * signature for RTAutoRes.
834 *
835 * We can't use a more complex template here, because the g++ on RHEL 3
836 * chokes on it with an internal compiler error.
837 *
838 * @tparam T The data type that's being managed.
839 * @param aMem Pointer to the memory that should be free.
840 */
841template <class T>
842inline void RTMemEfAutoFree(T *aMem) RT_NO_THROW
843{
844 RTMemEfFreeNP(aMem);
845}
846
847
848/**
849 * Template function wrapping NULL to get the correct NilRes signature
850 * for RTAutoRes.
851 *
852 * @tparam T The data type that's being managed.
853 * @returns NULL with the right type.
854 */
855template <class T>
856inline T * RTMemAutoNil(void) RT_NO_THROW
857{
858 return (T *)(NULL);
859}
860
861
862/**
863 * An auto pointer-type template class for managing memory allocating
864 * via C APIs like RTMem (the default).
865 *
866 * The main purpose of this class is to automatically free memory that
867 * isn't explicitly used (release()'ed) when the object goes out of scope.
868 *
869 * As an additional service it can also make the allocations and
870 * reallocations for you if you like, but it can also take of memory
871 * you hand it.
872 *
873 * @tparam T The data type to manage allocations for.
874 * @tparam Destruct The function to be used to free the resource.
875 * This will default to RTMemFree.
876 * @tparam Allocator The function to be used to allocate or reallocate
877 * the managed memory.
878 * This is standard realloc() like stuff, so it's possible
879 * to support simple allocation without actually having
880 * to support reallocating memory if that's a problem.
881 * This will default to RTMemRealloc.
882 */
883template <class T,
884 void Destruct(T *) = RTMemAutoDestructor<T>,
885# if defined(RTMEM_WRAP_TO_EF_APIS) && !defined(RTMEM_NO_WRAP_TO_EF_APIS)
886 void *Allocator(void *, size_t, const char *) = RTMemEfReallocNP
887# else
888 void *Allocator(void *, size_t, const char *) = RTMemReallocTag
889# endif
890 >
891class RTMemAutoPtr
892 : public RTAutoRes<T *, Destruct, RTMemAutoNil<T> >
893{
894public:
895 /**
896 * Constructor.
897 *
898 * @param aPtr Memory pointer to manage. Defaults to NULL.
899 */
900 RTMemAutoPtr(T *aPtr = NULL)
901 : RTAutoRes<T *, Destruct, RTMemAutoNil<T> >(aPtr)
902 {
903 }
904
905 /**
906 * Constructor that allocates memory.
907 *
908 * @param a_cElements The number of elements (of the data type) to allocate.
909 * @param a_fZeroed Whether the memory should be memset with zeros after
910 * the allocation. Defaults to false.
911 */
912 RTMemAutoPtr(size_t a_cElements, bool a_fZeroed = false)
913 : RTAutoRes<T *, Destruct, RTMemAutoNil<T> >((T *)Allocator(NULL, a_cElements * sizeof(T), RTMEM_TAG))
914 {
915 if (a_fZeroed && RT_LIKELY(this->get() != NULL))
916 memset(this->get(), '\0', a_cElements * sizeof(T));
917 }
918
919 /**
920 * Free current memory and start managing aPtr.
921 *
922 * @param aPtr Memory pointer to manage.
923 */
924 RTMemAutoPtr &operator=(T *aPtr)
925 {
926 this->RTAutoRes<T *, Destruct, RTMemAutoNil<T> >::operator=(aPtr);
927 return *this;
928 }
929
930 /**
931 * Dereference with * operator.
932 */
933 T &operator*()
934 {
935 return *this->get();
936 }
937
938 /**
939 * Dereference with -> operator.
940 */
941 T *operator->()
942 {
943 return this->get();
944 }
945
946 /**
947 * Accessed with the subscript operator ([]).
948 *
949 * @returns Reference to the element.
950 * @param a_i The element to access.
951 */
952 T &operator[](size_t a_i)
953 {
954 return this->get()[a_i];
955 }
956
957 /**
958 * Allocates memory and start manage it.
959 *
960 * Any previously managed memory will be freed before making
961 * the new allocation.
962 *
963 * @returns Success indicator.
964 * @retval true if the new allocation succeeds.
965 * @retval false on failure, no memory is associated with the object.
966 *
967 * @param a_cElements The number of elements (of the data type) to allocate.
968 * This defaults to 1.
969 * @param a_fZeroed Whether the memory should be memset with zeros after
970 * the allocation. Defaults to false.
971 */
972 bool alloc(size_t a_cElements = 1, bool a_fZeroed = false)
973 {
974 this->reset(NULL);
975 T *pNewMem = (T *)Allocator(NULL, a_cElements * sizeof(T), RTMEM_TAG);
976 if (a_fZeroed && RT_LIKELY(pNewMem != NULL))
977 memset(pNewMem, '\0', a_cElements * sizeof(T));
978 this->reset(pNewMem);
979 return pNewMem != NULL;
980 }
981
982 /**
983 * Reallocate or allocates the memory resource.
984 *
985 * Free the old value if allocation fails.
986 *
987 * The content of any additional memory that was allocated is
988 * undefined when using the default allocator.
989 *
990 * @returns Success indicator.
991 * @retval true if the new allocation succeeds.
992 * @retval false on failure, no memory is associated with the object.
993 *
994 * @param a_cElements The new number of elements (of the data type) to
995 * allocate. The size of the allocation is the number of
996 * elements times the size of the data type - this is
997 * currently what's passed down to the Allocator.
998 * This defaults to 1.
999 */
1000 bool realloc(size_t a_cElements = 1)
1001 {
1002 T *aNewValue = (T *)Allocator(this->get(), a_cElements * sizeof(T), RTMEM_TAG);
1003 if (RT_LIKELY(aNewValue != NULL))
1004 this->release();
1005 /* We want this both if aNewValue is non-NULL and if it is NULL. */
1006 this->reset(aNewValue);
1007 return aNewValue != NULL;
1008 }
1009};
1010
1011
1012#endif /* __cplusplus */
1013
1014
1015/** @} */
1016
1017
1018#endif
1019
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette