VirtualBox

source: vbox/trunk/include/iprt/heap.h@ 91688

Last change on this file since 91688 was 85121, checked in by vboxsync, 4 years ago

iprt/cdefs.h: Refactored the typedef use of DECLCALLBACK as well as DECLCALLBACKMEMBER to wrap the whole expression, similar to the DECLR?CALLBACKMEMBER macros. This allows adding a throw() at the end when compiling with the VC++ compiler to indicate that the callbacks won't throw anything, so we can stop supressing the C5039 warning about passing functions that can potential throw C++ exceptions to extern C code that can't necessarily cope with such (unwind,++). Introduced a few _EX variations that allows specifying different/no calling convention too, as that's handy when dynamically resolving host APIs. Fixed numerous places missing DECLCALLBACK and such. Left two angry @todos regarding use of CreateThread. bugref:9794

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 13.2 KB
Line 
1/** @file
2 * IPRT - Heap Implementations
3 */
4
5/*
6 * Copyright (C) 2006-2020 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_INCLUDED_heap_h
27#define IPRT_INCLUDED_heap_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <iprt/cdefs.h>
33#include <iprt/types.h>
34
35RT_C_DECLS_BEGIN
36
37/** @defgroup grp_rt_heap RTHeap - Heap Implementations
38 * @ingroup grp_rt
39 * @{
40 */
41
42
43/** @defgroup grp_rt_heap_simple RTHeapSimple - Simple Heap
44 * @{
45 */
46
47/**
48 * Initializes the heap.
49 *
50 * @returns IPRT status code.
51 * @param pHeap Where to store the heap anchor block on success.
52 * @param pvMemory Pointer to the heap memory.
53 * @param cbMemory The size of the heap memory.
54 */
55RTDECL(int) RTHeapSimpleInit(PRTHEAPSIMPLE pHeap, void *pvMemory, size_t cbMemory);
56
57/**
58 * Merge two simple heaps into one.
59 *
60 * The requirement is of course that they next two each other memory wise.
61 *
62 * @returns IPRT status code.
63 * @param pHeap Where to store the handle to the merged heap on success.
64 * @param Heap1 Handle to the first heap.
65 * @param Heap2 Handle to the second heap.
66 * @remark This API isn't implemented yet.
67 */
68RTDECL(int) RTHeapSimpleMerge(PRTHEAPSIMPLE pHeap, RTHEAPSIMPLE Heap1, RTHEAPSIMPLE Heap2);
69
70/**
71 * Relocater the heap internal structures after copying it to a new location.
72 *
73 * This can be used when loading a saved heap.
74 *
75 * @returns IPRT status code.
76 * @param hHeap Heap handle that has already been adjusted by to the new
77 * location. That is to say, when calling
78 * RTHeapSimpleInit, the caller must note the offset of the
79 * returned heap handle into the heap memory. This offset
80 * must be used when calcuating the handle value for the
81 * new location. The offset may in some cases not be zero!
82 * @param offDelta The delta between the new and old location, i.e. what
83 * should be added to the internal pointers.
84 */
85RTDECL(int) RTHeapSimpleRelocate(RTHEAPSIMPLE hHeap, uintptr_t offDelta);
86
87/**
88 * Allocates memory from the specified simple heap.
89 *
90 * @returns Pointer to the allocated memory block on success.
91 * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
92 *
93 * @param Heap The heap to allocate the memory on.
94 * @param cb The requested heap block size.
95 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
96 * Must be a power of 2.
97 */
98RTDECL(void *) RTHeapSimpleAlloc(RTHEAPSIMPLE Heap, size_t cb, size_t cbAlignment);
99
100/**
101 * Allocates zeroed memory from the specified simple heap.
102 *
103 * @returns Pointer to the allocated memory block on success.
104 * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
105 *
106 * @param Heap The heap to allocate the memory on.
107 * @param cb The requested heap block size.
108 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
109 * Must be a power of 2.
110 */
111RTDECL(void *) RTHeapSimpleAllocZ(RTHEAPSIMPLE Heap, size_t cb, size_t cbAlignment);
112
113/**
114 * Reallocates / Allocates / Frees a heap block.
115 *
116 * @param Heap The heap. This is optional and will only be used for strict assertions.
117 * @param pv The heap block returned by RTHeapSimple. If NULL it behaves like RTHeapSimpleAlloc().
118 * @param cbNew The new size of the heap block. If NULL it behaves like RTHeapSimpleFree().
119 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
120 * Must be a power of 2.
121 * @remark This API isn't implemented yet.
122 */
123RTDECL(void *) RTHeapSimpleRealloc(RTHEAPSIMPLE Heap, void *pv, size_t cbNew, size_t cbAlignment);
124
125/**
126 * Reallocates / Allocates / Frees a heap block, zeroing any new bits.
127 *
128 * @param Heap The heap. This is optional and will only be used for strict assertions.
129 * @param pv The heap block returned by RTHeapSimple. If NULL it behaves like RTHeapSimpleAllocZ().
130 * @param cbNew The new size of the heap block. If NULL it behaves like RTHeapSimpleFree().
131 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
132 * Must be a power of 2.
133 * @remark This API isn't implemented yet.
134 */
135RTDECL(void *) RTHeapSimpleReallocZ(RTHEAPSIMPLE Heap, void *pv, size_t cbNew, size_t cbAlignment);
136
137/**
138 * Frees memory allocated from a simple heap.
139 *
140 * @param Heap The heap. This is optional and will only be used for strict assertions.
141 * @param pv The heap block returned by RTHeapSimple
142 */
143RTDECL(void) RTHeapSimpleFree(RTHEAPSIMPLE Heap, void *pv);
144
145/**
146 * Gets the size of the specified heap block.
147 *
148 * @returns The actual size of the heap block.
149 * @returns 0 if \a pv is NULL or it doesn't point to a valid heap block. An invalid \a pv
150 * can also cause traps or trigger assertions.
151 * @param Heap The heap. This is optional and will only be used for strict assertions.
152 * @param pv The heap block returned by RTHeapSimple
153 */
154RTDECL(size_t) RTHeapSimpleSize(RTHEAPSIMPLE Heap, void *pv);
155
156/**
157 * Gets the size of the heap.
158 *
159 * This size includes all the internal heap structures. So, even if the heap is
160 * empty the RTHeapSimpleGetFreeSize() will never reach the heap size returned
161 * by this function.
162 *
163 * @returns The heap size.
164 * @returns 0 if heap was safely detected as being bad.
165 * @param Heap The heap.
166 */
167RTDECL(size_t) RTHeapSimpleGetHeapSize(RTHEAPSIMPLE Heap);
168
169/**
170 * Returns the sum of all free heap blocks.
171 *
172 * This is the amount of memory you can theoretically allocate
173 * if you do allocations exactly matching the free blocks.
174 *
175 * @returns The size of the free blocks.
176 * @returns 0 if heap was safely detected as being bad.
177 * @param Heap The heap.
178 */
179RTDECL(size_t) RTHeapSimpleGetFreeSize(RTHEAPSIMPLE Heap);
180
181/**
182 * Printf like callbaclk function for RTHeapSimpleDump.
183 * @param pszFormat IPRT format string.
184 * @param ... Format arguments.
185 */
186typedef DECLCALLBACKTYPE(void, FNRTHEAPSIMPLEPRINTF,(const char *pszFormat, ...)) RT_IPRT_FORMAT_ATTR(1, 2);
187/** Pointer to a FNRTHEAPSIMPLEPRINTF function. */
188typedef FNRTHEAPSIMPLEPRINTF *PFNRTHEAPSIMPLEPRINTF;
189
190/**
191 * Dumps the hypervisor heap.
192 *
193 * @param Heap The heap handle.
194 * @param pfnPrintf Printf like function that groks IPRT formatting.
195 */
196RTDECL(void) RTHeapSimpleDump(RTHEAPSIMPLE Heap, PFNRTHEAPSIMPLEPRINTF pfnPrintf);
197
198/** @} */
199
200
201
202/** @defgroup grp_rt_heap_offset RTHeapOffset - Offset Based Heap
203 *
204 * This is a variation on the simple heap that doesn't use pointers internally
205 * and therefore can be saved and restored without any extra effort.
206 *
207 * @{
208 */
209
210/**
211 * Initializes the heap.
212 *
213 * @returns IPRT status code.
214 * @param phHeap Where to store the heap anchor block on success.
215 * @param pvMemory Pointer to the heap memory.
216 * @param cbMemory The size of the heap memory.
217 */
218RTDECL(int) RTHeapOffsetInit(PRTHEAPOFFSET phHeap, void *pvMemory, size_t cbMemory);
219
220/**
221 * Merge two simple heaps into one.
222 *
223 * The requirement is of course that they next two each other memory wise.
224 *
225 * @returns IPRT status code.
226 * @param phHeap Where to store the handle to the merged heap on success.
227 * @param hHeap1 Handle to the first heap.
228 * @param hHeap2 Handle to the second heap.
229 * @remark This API isn't implemented yet.
230 */
231RTDECL(int) RTHeapOffsetMerge(PRTHEAPOFFSET phHeap, RTHEAPOFFSET hHeap1, RTHEAPOFFSET hHeap2);
232
233/**
234 * Allocates memory from the specified simple heap.
235 *
236 * @returns Pointer to the allocated memory block on success.
237 * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
238 *
239 * @param hHeap The heap to allocate the memory on.
240 * @param cb The requested heap block size.
241 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
242 * Must be a power of 2.
243 */
244RTDECL(void *) RTHeapOffsetAlloc(RTHEAPOFFSET hHeap, size_t cb, size_t cbAlignment);
245
246/**
247 * Allocates zeroed memory from the specified simple heap.
248 *
249 * @returns Pointer to the allocated memory block on success.
250 * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
251 *
252 * @param hHeap The heap to allocate the memory on.
253 * @param cb The requested heap block size.
254 * @param cbAlignment The requested heap block alignment. Pass 0 for default
255 * alignment. Must be a power of 2.
256 */
257RTDECL(void *) RTHeapOffsetAllocZ(RTHEAPOFFSET hHeap, size_t cb, size_t cbAlignment);
258
259/**
260 * Reallocates / Allocates / Frees a heap block.
261 *
262 * @param hHeap The heap handle. This is optional and will only be used
263 * for strict assertions.
264 * @param pv The heap block returned by RTHeapOffset. If NULL it
265 * behaves like RTHeapOffsetAlloc().
266 * @param cbNew The new size of the heap block. If NULL it behaves like
267 * RTHeapOffsetFree().
268 * @param cbAlignment The requested heap block alignment. Pass 0 for default
269 * alignment. Must be a power of 2.
270 * @remark This API isn't implemented yet.
271 */
272RTDECL(void *) RTHeapOffsetRealloc(RTHEAPOFFSET hHeap, void *pv, size_t cbNew, size_t cbAlignment);
273
274/**
275 * Reallocates / Allocates / Frees a heap block, zeroing any new bits.
276 *
277 * @param hHeap The heap handle. This is optional and will only be used
278 * for strict assertions.
279 * @param pv The heap block returned by RTHeapOffset. If NULL it
280 * behaves like RTHeapOffsetAllocZ().
281 * @param cbNew The new size of the heap block. If NULL it behaves like
282 * RTHeapOffsetFree().
283 * @param cbAlignment The requested heap block alignment. Pass 0 for default
284 * alignment. Must be a power of 2.
285 * @remark This API isn't implemented yet.
286 */
287RTDECL(void *) RTHeapOffsetReallocZ(RTHEAPOFFSET hHeap, void *pv, size_t cbNew, size_t cbAlignment);
288
289/**
290 * Frees memory allocated from a simple heap.
291 *
292 * @param hHeap The heap handle. This is optional and will only be used
293 * for strict assertions.
294 * @param pv The heap block returned by RTHeapOffset
295 */
296RTDECL(void) RTHeapOffsetFree(RTHEAPOFFSET hHeap, void *pv);
297
298/**
299 * Gets the size of the specified heap block.
300 *
301 * @returns The actual size of the heap block.
302 * @returns 0 if \a pv is NULL or it doesn't point to a valid heap block. An
303 * invalid \a pv can also cause traps or trigger assertions.
304 *
305 * @param hHeap The heap handle. This is optional and will only be used
306 * for strict assertions.
307 * @param pv The heap block returned by RTHeapOffset
308 */
309RTDECL(size_t) RTHeapOffsetSize(RTHEAPOFFSET hHeap, void *pv);
310
311/**
312 * Gets the size of the heap.
313 *
314 * This size includes all the internal heap structures. So, even if the heap is
315 * empty the RTHeapOffsetGetFreeSize() will never reach the heap size returned
316 * by this function.
317 *
318 * @returns The heap size.
319 * @returns 0 if heap was safely detected as being bad.
320 * @param hHeap The heap handle.
321 */
322RTDECL(size_t) RTHeapOffsetGetHeapSize(RTHEAPOFFSET hHeap);
323
324/**
325 * Returns the sum of all free heap blocks.
326 *
327 * This is the amount of memory you can theoretically allocate
328 * if you do allocations exactly matching the free blocks.
329 *
330 * @returns The size of the free blocks.
331 * @returns 0 if heap was safely detected as being bad.
332 * @param hHeap The heap handle.
333 */
334RTDECL(size_t) RTHeapOffsetGetFreeSize(RTHEAPOFFSET hHeap);
335
336/**
337 * Printf like callbaclk function for RTHeapOffsetDump.
338 * @param pszFormat IPRT format string.
339 * @param ... Format arguments.
340 */
341typedef DECLCALLBACKTYPE(void, FNRTHEAPOFFSETPRINTF,(const char *pszFormat, ...)) RT_IPRT_FORMAT_ATTR(1, 2);
342/** Pointer to a FNRTHEAPOFFSETPRINTF function. */
343typedef FNRTHEAPOFFSETPRINTF *PFNRTHEAPOFFSETPRINTF;
344
345/**
346 * Dumps the hypervisor heap.
347 *
348 * @param hHeap The heap handle.
349 * @param pfnPrintf Printf like function that groks IPRT formatting.
350 */
351RTDECL(void) RTHeapOffsetDump(RTHEAPOFFSET hHeap, PFNRTHEAPOFFSETPRINTF pfnPrintf);
352
353/** @} */
354
355/** @} */
356RT_C_DECLS_END
357
358#endif /* !IPRT_INCLUDED_heap_h */
359
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