VirtualBox

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

Last change on this file since 19944 was 8245, checked in by vboxsync, 17 years ago

rebranding: IPRT files again.

File size: 6.5 KB
Line 
1/** @file
2 * IPRT - A Simple Heap.
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_heap_h
31#define ___iprt_heap_h
32
33#include <iprt/cdefs.h>
34#include <iprt/types.h>
35
36__BEGIN_DECLS
37
38/**
39 * Initializes the heap.
40 *
41 * @returns IPRT status code on success.
42 * @param pHeap Where to store the heap anchor block on success.
43 * @param pvMemory Pointer to the heap memory.
44 * @param cbMemory The size of the heap memory.
45 */
46RTDECL(int) RTHeapSimpleInit(PRTHEAPSIMPLE pHeap, void *pvMemory, size_t cbMemory);
47
48/**
49 * Merge two simple heaps into one.
50 *
51 * The requiremet is of course that they next two each other memory wise.
52 *
53 * @returns IPRT status code on success.
54 * @param pHeap Where to store the handle to the merged heap on success.
55 * @param Heap1 Handle to the first heap.
56 * @param Heap2 Handle to the second heap.
57 * @remark This API isn't implemented yet.
58 */
59RTDECL(int) RTHeapSimpleMerge(PRTHEAPSIMPLE pHeap, RTHEAPSIMPLE Heap1, RTHEAPSIMPLE Heap2);
60
61/**
62 * Allocates memory from the specified simple heap.
63 *
64 * @returns Pointer to the allocated memory block on success.
65 * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
66 *
67 * @param Heap The heap to allocate the memory on.
68 * @param cb The requested heap block size.
69 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
70 * Must be a power of 2.
71 */
72RTDECL(void *) RTHeapSimpleAlloc(RTHEAPSIMPLE Heap, size_t cb, size_t cbAlignment);
73
74/**
75 * Allocates zeroed memory from the specified simple heap.
76 *
77 * @returns Pointer to the allocated memory block on success.
78 * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
79 *
80 * @param Heap The heap to allocate the memory on.
81 * @param cb The requested heap block size.
82 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
83 * Must be a power of 2.
84 */
85RTDECL(void *) RTHeapSimpleAllocZ(RTHEAPSIMPLE Heap, size_t cb, size_t cbAlignment);
86
87/**
88 * Reallocates / Allocates / Frees a heap block.
89 *
90 * @param Heap The heap. This is optional and will only be used for strict assertions.
91 * @param pv The heap block returned by RTHeapSimple. If NULL it behaves like RTHeapSimpleAlloc().
92 * @param cbNew The new size of the heap block. If NULL it behaves like RTHeapSimpleFree().
93 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
94 * Must be a power of 2.
95 * @remark This API isn't implemented yet.
96 */
97RTDECL(void *) RTHeapSimpleRealloc(RTHEAPSIMPLE Heap, void *pv, size_t cbNew, size_t cbAlignment);
98
99/**
100 * Reallocates / Allocates / Frees a heap block, zeroing any new bits.
101 *
102 * @param Heap The heap. This is optional and will only be used for strict assertions.
103 * @param pv The heap block returned by RTHeapSimple. If NULL it behaves like RTHeapSimpleAllocZ().
104 * @param cbNew The new size of the heap block. If NULL it behaves like RTHeapSimpleFree().
105 * @param cbAlignment The requested heap block alignment. Pass 0 for default alignment.
106 * Must be a power of 2.
107 * @remark This API isn't implemented yet.
108 */
109RTDECL(void *) RTHeapSimpleReallocZ(RTHEAPSIMPLE Heap, void *pv, size_t cbNew, size_t cbAlignment);
110
111/**
112 * Frees memory allocated from a simple heap.
113 *
114 * @param Heap The heap. This is optional and will only be used for strict assertions.
115 * @param pv The heap block returned by RTHeapSimple
116 */
117RTDECL(void) RTHeapSimpleFree(RTHEAPSIMPLE Heap, void *pv);
118
119/**
120 * Gets the size of the specified heap block.
121 *
122 * @returns The actual size of the heap block.
123 * @returns 0 if \a pv is NULL or it doesn't point to a valid heap block. An invalid \a pv
124 * can also cause traps or trigger assertions.
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
127 */
128RTDECL(size_t) RTHeapSimpleSize(RTHEAPSIMPLE Heap, void *pv);
129
130/**
131 * Gets the size of the heap.
132 *
133 * This size includes all the internal heap structures. So, even if the heap is
134 * empty the RTHeapSimpleGetFreeSize() will never reach the heap size returned
135 * by this function.
136 *
137 * @returns The heap size.
138 * @returns 0 if heap was safely detected as being bad.
139 * @param Heap The heap.
140 */
141RTDECL(size_t) RTHeapSimpleGetHeapSize(RTHEAPSIMPLE Heap);
142
143/**
144 * Returns the sum of all free heap blocks.
145 *
146 * This is the amount of memory you can theoretically allocate
147 * if you do allocations exactly matching the free blocks.
148 *
149 * @returns The size of the free blocks.
150 * @returns 0 if heap was safely detected as being bad.
151 * @param Heap The heap.
152 */
153RTDECL(size_t) RTHeapSimpleGetFreeSize(RTHEAPSIMPLE Heap);
154
155/**
156 * Printf like callbaclk function for RTHeapSimpleDump.
157 * @param pszFormat IPRT format string.
158 * @param ... Format arguments.
159 */
160typedef DECLCALLBACK(void) FNRTHEAPSIMPLEPRINTF(const char *pszFormat, ...);
161/** Pointer to a FNRTHEAPSIMPLEPRINTF function. */
162typedef FNRTHEAPSIMPLEPRINTF *PFNRTHEAPSIMPLEPRINTF;
163
164/**
165 * Dumps the hypervisor heap.
166 *
167 * @param Heap The heap handle.
168 * @param pfnPrintf Printf like function that groks IPRT formatting.
169 */
170RTDECL(void) RTHeapSimpleDump(RTHEAPSIMPLE Heap, PFNRTHEAPSIMPLEPRINTF pfnPrintf);
171
172__END_DECLS
173
174#endif
175
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