VirtualBox

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

Last change on this file since 18910 was 13832, checked in by vboxsync, 16 years ago

IN_GC -> IN_RC.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 17.7 KB
Line 
1/** @file
2 * IPRT - Memory Management and Manipulation.
3 */
4
5/*
6 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___iprt_mem_h
31#define ___iprt_mem_h
32
33
34#include <iprt/cdefs.h>
35#include <iprt/types.h>
36#ifdef __cplusplus
37# include <iprt/autores.h>
38#endif
39
40
41#ifdef IN_RC
42# error "There are no RTMem APIs available Guest Context!"
43#endif
44
45
46/** @defgroup grp_rt_mem RTMem - Memory Management and Manipulation
47 * @ingroup grp_rt
48 * @{
49 */
50
51__BEGIN_DECLS
52
53/** @def RTMEM_ALIGNMENT
54 * The alignment of the memory blocks returned by RTMemAlloc(), RTMemAllocZ(),
55 * RTMemRealloc(), RTMemTmpAlloc() and RTMemTmpAllocZ() for allocations greater
56 * than RTMEM_ALIGNMENT.
57 */
58#define RTMEM_ALIGNMENT 8
59
60/**
61 * Allocates temporary memory.
62 *
63 * Temporary memory blocks are used for not too large memory blocks which
64 * are believed not to stick around for too long. Using this API instead
65 * of RTMemAlloc() not only gives the heap manager room for optimization
66 * but makes the code easier to read.
67 *
68 * @returns Pointer to the allocated memory.
69 * @returns NULL on failure.
70 * @param cb Size in bytes of the memory block to allocated.
71 */
72RTDECL(void *) RTMemTmpAlloc(size_t cb) RT_NO_THROW;
73
74/**
75 * Allocates zero'ed temporary memory.
76 *
77 * Same as RTMemTmpAlloc() but the memory will be zero'ed.
78 *
79 * @returns Pointer to the allocated memory.
80 * @returns NULL on failure.
81 * @param cb Size in bytes of the memory block to allocated.
82 */
83RTDECL(void *) RTMemTmpAllocZ(size_t cb) RT_NO_THROW;
84
85/**
86 * Free temporary memory.
87 *
88 * @param pv Pointer to memory block.
89 */
90RTDECL(void) RTMemTmpFree(void *pv) RT_NO_THROW;
91
92
93/**
94 * Allocates memory.
95 *
96 * @returns Pointer to the allocated memory.
97 * @returns NULL on failure.
98 * @param cb Size in bytes of the memory block to allocated.
99 */
100RTDECL(void *) RTMemAlloc(size_t cb) RT_NO_THROW;
101
102/**
103 * Allocates zero'ed memory.
104 *
105 * Instead of memset(pv, 0, sizeof()) use this when you want zero'ed
106 * memory. This keeps the code smaller and the heap can skip the memset
107 * in about 0.42% of calls :-).
108 *
109 * @returns Pointer to the allocated memory.
110 * @returns NULL on failure.
111 * @param cb Size in bytes of the memory block to allocated.
112 */
113RTDECL(void *) RTMemAllocZ(size_t cb) RT_NO_THROW;
114
115/**
116 * Duplicates a chunk of memory into a new heap block.
117 *
118 * @returns New heap block with the duplicate data.
119 * @returns NULL if we're out of memory.
120 * @param pvSrc The memory to duplicate.
121 * @param cb The amount of memory to duplicate.
122 */
123RTDECL(void *) RTMemDup(const void *pvSrc, size_t cb) RT_NO_THROW;
124
125/**
126 * Duplicates a chunk of memory into a new heap block with some
127 * additional zeroed memory.
128 *
129 * @returns New heap block with the duplicate data.
130 * @returns NULL if we're out of memory.
131 * @param pvSrc The memory to duplicate.
132 * @param cbSrc The amount of memory to duplicate.
133 * @param cbExtra The amount of extra memory to allocate and zero.
134 */
135RTDECL(void *) RTMemDupEx(const void *pvSrc, size_t cbSrc, size_t cbExtra) RT_NO_THROW;
136
137/**
138 * Reallocates memory.
139 *
140 * @returns Pointer to the allocated memory.
141 * @returns NULL on failure.
142 * @param pvOld The memory block to reallocate.
143 * @param cbNew The new block size (in bytes).
144 */
145RTDECL(void *) RTMemRealloc(void *pvOld, size_t cbNew) RT_NO_THROW;
146
147/**
148 * Free memory related to an virtual machine
149 *
150 * @param pv Pointer to memory block.
151 */
152RTDECL(void) RTMemFree(void *pv) RT_NO_THROW;
153
154/**
155 * Allocates memory which may contain code.
156 *
157 * @returns Pointer to the allocated memory.
158 * @returns NULL on failure.
159 * @param cb Size in bytes of the memory block to allocate.
160 */
161RTDECL(void *) RTMemExecAlloc(size_t cb) RT_NO_THROW;
162
163/**
164 * Free executable/read/write memory allocated by RTMemExecAlloc().
165 *
166 * @param pv Pointer to memory block.
167 */
168RTDECL(void) RTMemExecFree(void *pv) RT_NO_THROW;
169
170#if defined(IN_RING0) && defined(RT_ARCH_AMD64) && defined(RT_OS_LINUX)
171/**
172 * Donate read+write+execute memory to the exec heap.
173 *
174 * This API is specific to AMD64 and Linux/GNU. A kernel module that desires to
175 * use RTMemExecAlloc on AMD64 Linux/GNU will have to donate some statically
176 * allocated memory in the module if it wishes for GCC generated code to work.
177 * GCC can only generate modules that work in the address range ~2GB to ~0
178 * currently.
179 *
180 * The API only accept one single donation.
181 *
182 * @returns IPRT status code.
183 * @param pvMemory Pointer to the memory block.
184 * @param cb The size of the memory block.
185 */
186RTR0DECL(int) RTR0MemExecDonate(void *pvMemory, size_t cb) RT_NO_THROW;
187#endif /* R0+AMD64+LINUX */
188
189/**
190 * Allocate page aligned memory.
191 *
192 * @returns Pointer to the allocated memory.
193 * @returns NULL if we're out of memory.
194 * @param cb Size of the memory block. Will be rounded up to page size.
195 */
196RTDECL(void *) RTMemPageAlloc(size_t cb) RT_NO_THROW;
197
198/**
199 * Allocate zero'ed page aligned memory.
200 *
201 * @returns Pointer to the allocated memory.
202 * @returns NULL if we're out of memory.
203 * @param cb Size of the memory block. Will be rounded up to page size.
204 */
205RTDECL(void *) RTMemPageAllocZ(size_t cb) RT_NO_THROW;
206
207/**
208 * Free a memory block allocated with RTMemPageAlloc() or RTMemPageAllocZ().
209 *
210 * @param pv Pointer to the block as it was returned by the allocation function.
211 * NULL will be ignored.
212 */
213RTDECL(void) RTMemPageFree(void *pv) RT_NO_THROW;
214
215/** Page level protection flags for RTMemProtect().
216 * @{
217 */
218/** Read access. */
219#define RTMEM_PROT_NONE 0
220/** Read access. */
221#define RTMEM_PROT_READ 1
222/** Write access. */
223#define RTMEM_PROT_WRITE 2
224/** Execute access. */
225#define RTMEM_PROT_EXEC 4
226/** @} */
227
228/**
229 * Change the page level protection of a memory region.
230 *
231 * @returns iprt status code.
232 * @param pv Start of the region. Will be rounded down to nearest page boundary.
233 * @param cb Size of the region. Will be rounded up to the nearest page boundary.
234 * @param fProtect The new protection, a combination of the RTMEM_PROT_* defines.
235 */
236RTDECL(int) RTMemProtect(void *pv, size_t cb, unsigned fProtect) RT_NO_THROW;
237
238
239#ifdef IN_RING0
240
241/**
242 * Allocates physical contiguous memory (below 4GB).
243 * The allocation is page aligned and the content is undefined.
244 *
245 * @returns Pointer to the memory block. This is page aligned.
246 * @param pPhys Where to store the physical address.
247 * @param cb The allocation size in bytes. This is always
248 * rounded up to PAGE_SIZE.
249 */
250RTR0DECL(void *) RTMemContAlloc(PRTCCPHYS pPhys, size_t cb) RT_NO_THROW;
251
252/**
253 * Frees memory allocated ysing RTMemContAlloc().
254 *
255 * @param pv Pointer to return from RTMemContAlloc().
256 * @param cb The cb parameter passed to RTMemContAlloc().
257 */
258RTR0DECL(void) RTMemContFree(void *pv, size_t cb) RT_NO_THROW;
259
260#endif
261
262
263/** @name Electrical Fence Version of some APIs.
264 * @{
265 */
266
267/**
268 * Same as RTMemTmpAlloc() except that it's fenced.
269 *
270 * @returns Pointer to the allocated memory.
271 * @returns NULL on failure.
272 * @param cb Size in bytes of the memory block to allocate.
273 */
274RTDECL(void *) RTMemEfTmpAlloc(size_t cb) RT_NO_THROW;
275
276/**
277 * Same as RTMemTmpAllocZ() except that it's fenced.
278 *
279 * @returns Pointer to the allocated memory.
280 * @returns NULL on failure.
281 * @param cb Size in bytes of the memory block to allocate.
282 */
283RTDECL(void *) RTMemEfTmpAllocZ(size_t cb) RT_NO_THROW;
284
285/**
286 * Same as RTMemTmpFree() except that it's for fenced memory.
287 *
288 * @param pv Pointer to memory block.
289 */
290RTDECL(void) RTMemEfTmpFree(void *pv) RT_NO_THROW;
291
292/**
293 * Same as RTMemAlloc() except that it's fenced.
294 *
295 * @returns Pointer to the allocated memory. Free with RTMemEfFree().
296 * @returns NULL on failure.
297 * @param cb Size in bytes of the memory block to allocate.
298 */
299RTDECL(void *) RTMemEfAlloc(size_t cb) RT_NO_THROW;
300
301/**
302 * Same as RTMemAllocZ() except that it's fenced.
303 *
304 * @returns Pointer to the allocated memory.
305 * @returns NULL on failure.
306 * @param cb Size in bytes of the memory block to allocate.
307 */
308RTDECL(void *) RTMemEfAllocZ(size_t cb) RT_NO_THROW;
309
310/**
311 * Same as RTMemRealloc() except that it's fenced.
312 *
313 * @returns Pointer to the allocated memory.
314 * @returns NULL on failure.
315 * @param pvOld The memory block to reallocate.
316 * @param cbNew The new block size (in bytes).
317 */
318RTDECL(void *) RTMemEfRealloc(void *pvOld, size_t cbNew) RT_NO_THROW;
319
320/**
321 * Free memory allocated by any of the RTMemEf* allocators.
322 *
323 * @param pv Pointer to memory block.
324 */
325RTDECL(void) RTMemEfFree(void *pv) RT_NO_THROW;
326
327/**
328 * Same as RTMemDup() except that it's fenced.
329 *
330 * @returns New heap block with the duplicate data.
331 * @returns NULL if we're out of memory.
332 * @param pvSrc The memory to duplicate.
333 * @param cb The amount of memory to duplicate.
334 */
335RTDECL(void *) RTMemEfDup(const void *pvSrc, size_t cb) RT_NO_THROW;
336
337/**
338 * Same as RTMemEfDupEx except that it's fenced.
339 *
340 * @returns New heap block with the duplicate data.
341 * @returns NULL if we're out of memory.
342 * @param pvSrc The memory to duplicate.
343 * @param cbSrc The amount of memory to duplicate.
344 * @param cbExtra The amount of extra memory to allocate and zero.
345 */
346RTDECL(void *) RTMemEfDupEx(const void *pvSrc, size_t cbSrc, size_t cbExtra) RT_NO_THROW;
347
348/** @def RTMEM_WRAP_TO_EF_APIS
349 * Define RTMEM_WRAP_TO_EF_APIS to wrap RTMem APIs to RTMemEf APIs.
350 */
351#ifdef RTMEM_WRAP_TO_EF_APIS
352# define RTMemTmpAlloc RTMemEfTmpAlloc
353# define RTMemTmpAllocZ RTMemEfTmpAllocZ
354# define RTMemTmpFree RTMemEfTmpFree
355# define RTMemAlloc RTMemEfAlloc
356# define RTMemAllocZ RTMemEfAllocZ
357# define RTMemRealloc RTMemEfRealloc
358# define RTMemFree RTMemEfFree
359# define RTMemDup RTMemEfDup
360# define RTMemDupEx RTMemEfDupEx
361#endif
362#ifdef DOXYGEN_RUNNING
363# define RTMEM_WRAP_TO_EF_APIS
364#endif
365
366/** @} */
367
368__END_DECLS
369
370
371#ifdef __cplusplus
372# include <iprt/assert.h>
373
374/**
375 * Template function wrapping RTMemFree to get the correct Destruct
376 * signature for RTAutoRes.
377 *
378 * We can't use a more complex template here, because the g++ on RHEL 3
379 * chokes on it with an internal compiler error.
380 *
381 * @param T The data type that's being managed.
382 * @param aMem Pointer to the memory that should be free.
383 */
384template <class T>
385inline void RTMemAutoDestructor(T *aMem) RT_NO_THROW
386{
387 RTMemFree(aMem);
388}
389
390
391/**
392 * RTMemAutoPtr allocator which uses RTMemTmpAlloc().
393 *
394 * @returns Allocated memory on success, NULL on failure.
395 * @param pvOld What to reallocate, shall always be NULL.
396 * @param cbNew The amount of memory to allocate (in bytes).
397 */
398inline void *RTMemTmpAutoAllocator(void *pvOld, size_t cbNew) RT_NO_THROW
399{
400 AssertReturn(!pvOld, NULL);
401 return RTMemTmpAlloc(cbNew);
402}
403
404
405/**
406 * Template function wrapping RTMemTmpFree to get the correct Destruct
407 * signature for RTAutoRes.
408 *
409 * We can't use a more complex template here, because the g++ on RHEL 3
410 * chokes on it with an internal compiler error.
411 *
412 * @param T The data type that's being managed.
413 * @param aMem Pointer to the memory that should be free.
414 */
415template <class T>
416inline void RTMemTmpAutoDestructor(T *aMem) RT_NO_THROW
417{
418 RTMemTmpFree(aMem);
419}
420
421
422/**
423 * Template function wrapping RTMemEfFree to get the correct Destruct
424 * signature for RTAutoRes.
425 *
426 * We can't use a more complex template here, because the g++ on RHEL 3
427 * chokes on it with an internal compiler error.
428 *
429 * @param T The data type that's being managed.
430 * @param aMem Pointer to the memory that should be free.
431 */
432template <class T>
433inline void RTMemEfAutoFree(T *aMem) RT_NO_THROW
434{
435 RTMemEfFree(aMem);
436}
437
438
439/**
440 * Template function wrapping NULL to get the correct NilRes signature
441 * for RTAutoRes.
442 *
443 * @param T The data type that's being managed.
444 * @returns NULL with the right type.
445 */
446template <class T>
447inline T * RTMemAutoNil(void) RT_NO_THROW
448{
449 return (T *)(NULL);
450}
451
452
453/**
454 * An auto pointer-type template class for managing memory allocating
455 * via C APIs like RTMem (the default).
456 *
457 * The main purpose of this class is to automatically free memory that
458 * isn't explicitly used (release()'ed) when the object goes out of scope.
459 *
460 * As an additional service it can also make the allocations and
461 * reallocations for you if you like, but it can also take of memory
462 * you hand it.
463 *
464 * @param T The data type to manage allocations for.
465 * @param Destruct The function to be used to free the resource.
466 * This will default to RTMemFree.
467 * @param Allocator The function to be used to allocate or reallocate
468 * the managed memory.
469 * This is standard realloc() like stuff, so it's possible
470 * to support simple allocation without actually having
471 * to support reallocating memory if that's a problem.
472 * This will default to RTMemRealloc.
473 */
474template <class T, void Destruct(T *) = RTMemAutoDestructor<T>, void *Allocator(void *, size_t) = RTMemRealloc >
475class RTMemAutoPtr
476 : public RTAutoRes<T *, Destruct, RTMemAutoNil<T> >
477{
478public:
479 /**
480 * Constructor.
481 *
482 * @param aPtr Memory pointer to manage. Defaults to NULL.
483 */
484 RTMemAutoPtr(T *aPtr = NULL)
485 : RTAutoRes<T *, Destruct, RTMemAutoNil<T> >(aPtr)
486 {
487 }
488
489 /**
490 * Constructor that allocates memory.
491 *
492 * @param a_cElements The number of elements (of the data type) to allocate.
493 * @param a_fZeroed Whether the memory should be memset with zeros after
494 * the allocation. Defaults to false.
495 */
496 RTMemAutoPtr(size_t a_cElements, bool a_fZeroed = false)
497 : RTAutoRes<T *, Destruct, RTMemAutoNil<T> >((T *)Allocator(NULL, a_cElements * sizeof(T)))
498 {
499 if (a_fZeroed && RT_LIKELY(this->get() != NULL))
500 memset(this->get(), '\0', a_cElements * sizeof(T));
501 }
502
503 /**
504 * Free current memory and start managing aPtr.
505 *
506 * @param aPtr Memory pointer to manage.
507 */
508 RTMemAutoPtr &operator=(T *aPtr)
509 {
510 this->RTAutoRes<T *, Destruct, RTMemAutoNil<T> >::operator=(aPtr);
511 return *this;
512 }
513
514 /**
515 * Dereference with * operator.
516 */
517 T &operator*()
518 {
519 return *this->get();
520 }
521
522 /**
523 * Dereference with -> operator.
524 */
525 T *operator->()
526 {
527 return this->get();
528 }
529
530 /**
531 * Accessed with the subscript operator ([]).
532 *
533 * @returns Reference to the element.
534 * @param a_i The element to access.
535 */
536 T &operator[](size_t a_i)
537 {
538 return this->get()[a_i];
539 }
540
541 /**
542 * Allocates memory and start manage it.
543 *
544 * Any previously managed memory will be freed before making
545 * the new allocation.
546 *
547 * @returns Success indicator.
548 * @retval true if the new allocation succeeds.
549 * @retval false on failure, no memory is associated with the object.
550 *
551 * @param a_cElements The number of elements (of the data type) to allocate.
552 * This defaults to 1.
553 * @param a_fZeroed Whether the memory should be memset with zeros after
554 * the allocation. Defaults to false.
555 */
556 bool alloc(size_t a_cElements = 1, bool a_fZeroed = false)
557 {
558 this->reset(NULL);
559 T *pNewMem = (T *)Allocator(NULL, a_cElements * sizeof(T));
560 if (a_fZeroed && RT_LIKELY(pNewMem != NULL))
561 memset(pNewMem, '\0', a_cElements * sizeof(T));
562 this->reset(pNewMem);
563 return pNewMem != NULL;
564 }
565
566 /**
567 * Reallocate or allocates the memory resource.
568 *
569 * Free the old value if allocation fails.
570 *
571 * The content of any additional memory that was allocated is
572 * undefined when using the default allocator.
573 *
574 * @returns Success indicator.
575 * @retval true if the new allocation succeeds.
576 * @retval false on failure, no memory is associated with the object.
577 *
578 * @param cElements The new number of elements (of the data type) to allocate.
579 * The size of the allocation is the number of elements times
580 * the size of the data type - this is currently what's passed
581 * down to the Allocator.
582 * This defaults to 1.
583 */
584 bool realloc(size_t a_cElements = 1)
585 {
586 T *aNewValue = (T *)Allocator(this->get(), a_cElements * sizeof(T));
587 if (RT_LIKELY(aNewValue != NULL))
588 this->release();
589 /* We want this both if aNewValue is non-NULL and if it is NULL. */
590 this->reset(aNewValue);
591 return aNewValue != NULL;
592 }
593};
594
595
596#endif /* __cplusplus */
597
598
599/** @} */
600
601
602#endif
603
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