2 * IPRT - Heap Implementations
6 * Copyright (C) 2006-2016 Oracle Corporation
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.
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.
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.
26 #ifndef ___iprt_heap_h
27 #define ___iprt_heap_h
29 #include <iprt/cdefs.h>
30 #include <iprt/types.h>
34 /** @defgroup grp_rt_heap RTHeap - Heap Implementations
40 /** @defgroup grp_rt_heap_simple RTHeapSimple - Simple Heap
45 * Initializes the heap.
47 * @returns IPRT status code.
48 * @param pHeap Where to store the heap anchor block on success.
49 * @param pvMemory Pointer to the heap memory.
50 * @param cbMemory The size of the heap memory.
52 RTDECL(int) RTHeapSimpleInit(PRTHEAPSIMPLE pHeap
, void *pvMemory
, size_t cbMemory
);
55 * Merge two simple heaps into one.
57 * The requirement is of course that they next two each other memory wise.
59 * @returns IPRT status code.
60 * @param pHeap Where to store the handle to the merged heap on success.
61 * @param Heap1 Handle to the first heap.
62 * @param Heap2 Handle to the second heap.
63 * @remark This API isn't implemented yet.
65 RTDECL(int) RTHeapSimpleMerge(PRTHEAPSIMPLE pHeap
, RTHEAPSIMPLE Heap1
, RTHEAPSIMPLE Heap2
);
68 * Relocater the heap internal structures after copying it to a new location.
70 * This can be used when loading a saved heap.
72 * @returns IPRT status code.
73 * @param hHeap Heap handle that has already been adjusted by to the new
74 * location. That is to say, when calling
75 * RTHeapSimpleInit, the caller must note the offset of the
76 * returned heap handle into the heap memory. This offset
77 * must be used when calcuating the handle value for the
78 * new location. The offset may in some cases not be zero!
79 * @param offDelta The delta between the new and old location, i.e. what
80 * should be added to the internal pointers.
82 RTDECL(int) RTHeapSimpleRelocate(RTHEAPSIMPLE hHeap
, uintptr_t offDelta
);
85 * Allocates memory from the specified simple heap.
87 * @returns Pointer to the allocated memory block on success.
88 * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
90 * @param Heap The heap to allocate the memory on.
91 * @param cb The requested heap block size.
92 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
93 * Must be a power of 2.
95 RTDECL(void *) RTHeapSimpleAlloc(RTHEAPSIMPLE Heap
, size_t cb
, size_t cbAlignment
);
98 * Allocates zeroed memory from the specified simple heap.
100 * @returns Pointer to the allocated memory block on success.
101 * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
103 * @param Heap The heap to allocate the memory on.
104 * @param cb The requested heap block size.
105 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
106 * Must be a power of 2.
108 RTDECL(void *) RTHeapSimpleAllocZ(RTHEAPSIMPLE Heap
, size_t cb
, size_t cbAlignment
);
111 * Reallocates / Allocates / Frees a heap block.
113 * @param Heap The heap. This is optional and will only be used for strict assertions.
114 * @param pv The heap block returned by RTHeapSimple. If NULL it behaves like RTHeapSimpleAlloc().
115 * @param cbNew The new size of the heap block. If NULL it behaves like RTHeapSimpleFree().
116 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
117 * Must be a power of 2.
118 * @remark This API isn't implemented yet.
120 RTDECL(void *) RTHeapSimpleRealloc(RTHEAPSIMPLE Heap
, void *pv
, size_t cbNew
, size_t cbAlignment
);
123 * Reallocates / Allocates / Frees a heap block, zeroing any new bits.
125 * @param Heap The heap. This is optional and will only be used for strict assertions.
126 * @param pv The heap block returned by RTHeapSimple. If NULL it behaves like RTHeapSimpleAllocZ().
127 * @param cbNew The new size of the heap block. If NULL it behaves like RTHeapSimpleFree().
128 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
129 * Must be a power of 2.
130 * @remark This API isn't implemented yet.
132 RTDECL(void *) RTHeapSimpleReallocZ(RTHEAPSIMPLE Heap
, void *pv
, size_t cbNew
, size_t cbAlignment
);
135 * Frees memory allocated from a simple heap.
137 * @param Heap The heap. This is optional and will only be used for strict assertions.
138 * @param pv The heap block returned by RTHeapSimple
140 RTDECL(void) RTHeapSimpleFree(RTHEAPSIMPLE Heap
, void *pv
);
143 * Gets the size of the specified heap block.
145 * @returns The actual size of the heap block.
146 * @returns 0 if \a pv is NULL or it doesn't point to a valid heap block. An invalid \a pv
147 * can also cause traps or trigger assertions.
148 * @param Heap The heap. This is optional and will only be used for strict assertions.
149 * @param pv The heap block returned by RTHeapSimple
151 RTDECL(size_t) RTHeapSimpleSize(RTHEAPSIMPLE Heap
, void *pv
);
154 * Gets the size of the heap.
156 * This size includes all the internal heap structures. So, even if the heap is
157 * empty the RTHeapSimpleGetFreeSize() will never reach the heap size returned
160 * @returns The heap size.
161 * @returns 0 if heap was safely detected as being bad.
162 * @param Heap The heap.
164 RTDECL(size_t) RTHeapSimpleGetHeapSize(RTHEAPSIMPLE Heap
);
167 * Returns the sum of all free heap blocks.
169 * This is the amount of memory you can theoretically allocate
170 * if you do allocations exactly matching the free blocks.
172 * @returns The size of the free blocks.
173 * @returns 0 if heap was safely detected as being bad.
174 * @param Heap The heap.
176 RTDECL(size_t) RTHeapSimpleGetFreeSize(RTHEAPSIMPLE Heap
);
179 * Printf like callbaclk function for RTHeapSimpleDump.
180 * @param pszFormat IPRT format string.
181 * @param ... Format arguments.
183 typedef DECLCALLBACK(void) FNRTHEAPSIMPLEPRINTF(const char *pszFormat
, ...) RT_IPRT_FORMAT_ATTR(1, 2);
184 /** Pointer to a FNRTHEAPSIMPLEPRINTF function. */
185 typedef FNRTHEAPSIMPLEPRINTF
*PFNRTHEAPSIMPLEPRINTF
;
188 * Dumps the hypervisor heap.
190 * @param Heap The heap handle.
191 * @param pfnPrintf Printf like function that groks IPRT formatting.
193 RTDECL(void) RTHeapSimpleDump(RTHEAPSIMPLE Heap
, PFNRTHEAPSIMPLEPRINTF pfnPrintf
);
199 /** @defgroup grp_rt_heap_offset RTHeapOffset - Offset Based Heap
201 * This is a variation on the simple heap that doesn't use pointers internally
202 * and therefore can be saved and restored without any extra effort.
208 * Initializes the heap.
210 * @returns IPRT status code.
211 * @param phHeap Where to store the heap anchor block on success.
212 * @param pvMemory Pointer to the heap memory.
213 * @param cbMemory The size of the heap memory.
215 RTDECL(int) RTHeapOffsetInit(PRTHEAPOFFSET phHeap
, void *pvMemory
, size_t cbMemory
);
218 * Merge two simple heaps into one.
220 * The requirement is of course that they next two each other memory wise.
222 * @returns IPRT status code.
223 * @param phHeap Where to store the handle to the merged heap on success.
224 * @param hHeap1 Handle to the first heap.
225 * @param hHeap2 Handle to the second heap.
226 * @remark This API isn't implemented yet.
228 RTDECL(int) RTHeapOffsetMerge(PRTHEAPOFFSET phHeap
, RTHEAPOFFSET hHeap1
, RTHEAPOFFSET hHeap2
);
231 * Allocates memory from the specified simple heap.
233 * @returns Pointer to the allocated memory block on success.
234 * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
236 * @param hHeap The heap to allocate the memory on.
237 * @param cb The requested heap block size.
238 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
239 * Must be a power of 2.
241 RTDECL(void *) RTHeapOffsetAlloc(RTHEAPOFFSET hHeap
, size_t cb
, size_t cbAlignment
);
244 * Allocates zeroed memory from the specified simple heap.
246 * @returns Pointer to the allocated memory block on success.
247 * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
249 * @param hHeap The heap to allocate the memory on.
250 * @param cb The requested heap block size.
251 * @param cbAlignment The requested heap block alignment. Pass 0 for default
252 * alignment. Must be a power of 2.
254 RTDECL(void *) RTHeapOffsetAllocZ(RTHEAPOFFSET hHeap
, size_t cb
, size_t cbAlignment
);
257 * Reallocates / Allocates / Frees a heap block.
259 * @param hHeap The heap handle. This is optional and will only be used
260 * for strict assertions.
261 * @param pv The heap block returned by RTHeapOffset. If NULL it
262 * behaves like RTHeapOffsetAlloc().
263 * @param cbNew The new size of the heap block. If NULL it behaves like
264 * RTHeapOffsetFree().
265 * @param cbAlignment The requested heap block alignment. Pass 0 for default
266 * alignment. Must be a power of 2.
267 * @remark This API isn't implemented yet.
269 RTDECL(void *) RTHeapOffsetRealloc(RTHEAPOFFSET hHeap
, void *pv
, size_t cbNew
, size_t cbAlignment
);
272 * Reallocates / Allocates / Frees a heap block, zeroing any new bits.
274 * @param hHeap The heap handle. This is optional and will only be used
275 * for strict assertions.
276 * @param pv The heap block returned by RTHeapOffset. If NULL it
277 * behaves like RTHeapOffsetAllocZ().
278 * @param cbNew The new size of the heap block. If NULL it behaves like
279 * RTHeapOffsetFree().
280 * @param cbAlignment The requested heap block alignment. Pass 0 for default
281 * alignment. Must be a power of 2.
282 * @remark This API isn't implemented yet.
284 RTDECL(void *) RTHeapOffsetReallocZ(RTHEAPOFFSET hHeap
, void *pv
, size_t cbNew
, size_t cbAlignment
);
287 * Frees memory allocated from a simple heap.
289 * @param hHeap The heap handle. This is optional and will only be used
290 * for strict assertions.
291 * @param pv The heap block returned by RTHeapOffset
293 RTDECL(void) RTHeapOffsetFree(RTHEAPOFFSET hHeap
, void *pv
);
296 * Gets the size of the specified heap block.
298 * @returns The actual size of the heap block.
299 * @returns 0 if \a pv is NULL or it doesn't point to a valid heap block. An
300 * invalid \a pv can also cause traps or trigger assertions.
302 * @param hHeap The heap handle. This is optional and will only be used
303 * for strict assertions.
304 * @param pv The heap block returned by RTHeapOffset
306 RTDECL(size_t) RTHeapOffsetSize(RTHEAPOFFSET hHeap
, void *pv
);
309 * Gets the size of the heap.
311 * This size includes all the internal heap structures. So, even if the heap is
312 * empty the RTHeapOffsetGetFreeSize() will never reach the heap size returned
315 * @returns The heap size.
316 * @returns 0 if heap was safely detected as being bad.
317 * @param hHeap The heap handle.
319 RTDECL(size_t) RTHeapOffsetGetHeapSize(RTHEAPOFFSET hHeap
);
322 * Returns the sum of all free heap blocks.
324 * This is the amount of memory you can theoretically allocate
325 * if you do allocations exactly matching the free blocks.
327 * @returns The size of the free blocks.
328 * @returns 0 if heap was safely detected as being bad.
329 * @param hHeap The heap handle.
331 RTDECL(size_t) RTHeapOffsetGetFreeSize(RTHEAPOFFSET hHeap
);
334 * Printf like callbaclk function for RTHeapOffsetDump.
335 * @param pszFormat IPRT format string.
336 * @param ... Format arguments.
338 typedef DECLCALLBACK(void) FNRTHEAPOFFSETPRINTF(const char *pszFormat
, ...) RT_IPRT_FORMAT_ATTR(1, 2);
339 /** Pointer to a FNRTHEAPOFFSETPRINTF function. */
340 typedef FNRTHEAPOFFSETPRINTF
*PFNRTHEAPOFFSETPRINTF
;
343 * Dumps the hypervisor heap.
345 * @param hHeap The heap handle.
346 * @param pfnPrintf Printf like function that groks IPRT formatting.
348 RTDECL(void) RTHeapOffsetDump(RTHEAPOFFSET hHeap
, PFNRTHEAPOFFSETPRINTF pfnPrintf
);