ubuntu/vbox/include/iprt/heap.h

   1 /** @file
   2  * IPRT - Heap Implementations
   3  */
   4
   5 /*
   6  * Copyright (C) 2006-2016 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_heap_h
  27 #define ___iprt_heap_h
  28
  29 #include <iprt/cdefs.h>
  30 #include <iprt/types.h>
  31
  32 RT_C_DECLS_BEGIN
  33
  34 /** @defgroup grp_rt_heap       RTHeap - Heap Implementations
  35  * @ingroup grp_rt
  36  * @{
  37  */
  38
  39
  40 /** @defgroup grp_rt_heap_simple    RTHeapSimple - Simple Heap
  41  * @{
  42  */
  43
  44 /**
  45  * Initializes the heap.
  46  *
  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.
  51  */
  52 RTDECL(int) RTHeapSimpleInit(PRTHEAPSIMPLE pHeap, void *pvMemory, size_t cbMemory);
  53
  54 /**
  55  * Merge two simple heaps into one.
  56  *
  57  * The requirement is of course that they next two each other memory wise.
  58  *
  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.
  64  */
  65 RTDECL(int) RTHeapSimpleMerge(PRTHEAPSIMPLE pHeap, RTHEAPSIMPLE Heap1, RTHEAPSIMPLE Heap2);
  66
  67 /**
  68  * Relocater the heap internal structures after copying it to a new location.
  69  *
  70  * This can be used when loading a saved heap.
  71  *
  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.
  81  */
  82 RTDECL(int) RTHeapSimpleRelocate(RTHEAPSIMPLE hHeap, uintptr_t offDelta);
  83
  84 /**
  85  * Allocates memory from the specified simple heap.
  86  *
  87  * @returns Pointer to the allocated memory block on success.
  88  * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
  89  *
  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.
  94  */
  95 RTDECL(void *) RTHeapSimpleAlloc(RTHEAPSIMPLE Heap, size_t cb, size_t cbAlignment);
  96
  97 /**
  98  * Allocates zeroed memory from the specified simple heap.
  99  *
 100  * @returns Pointer to the allocated memory block on success.
 101  * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
 102  *
 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.
 107  */
 108 RTDECL(void *) RTHeapSimpleAllocZ(RTHEAPSIMPLE Heap, size_t cb, size_t cbAlignment);
 109
 110 /**
 111  * Reallocates / Allocates / Frees a heap block.
 112  *
 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.
 119  */
 120 RTDECL(void *) RTHeapSimpleRealloc(RTHEAPSIMPLE Heap, void *pv, size_t cbNew, size_t cbAlignment);
 121
 122 /**
 123  * Reallocates / Allocates / Frees a heap block, zeroing any new bits.
 124  *
 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.
 131  */
 132 RTDECL(void *) RTHeapSimpleReallocZ(RTHEAPSIMPLE Heap, void *pv, size_t cbNew, size_t cbAlignment);
 133
 134 /**
 135  * Frees memory allocated from a simple heap.
 136  *
 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
 139  */
 140 RTDECL(void) RTHeapSimpleFree(RTHEAPSIMPLE Heap, void *pv);
 141
 142 /**
 143  * Gets the size of the specified heap block.
 144  *
 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
 150  */
 151 RTDECL(size_t) RTHeapSimpleSize(RTHEAPSIMPLE Heap, void *pv);
 152
 153 /**
 154  * Gets the size of the heap.
 155  *
 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
 158  * by this function.
 159  *
 160  * @returns The heap size.
 161  * @returns 0 if heap was safely detected as being bad.
 162  * @param   Heap    The heap.
 163  */
 164 RTDECL(size_t) RTHeapSimpleGetHeapSize(RTHEAPSIMPLE Heap);
 165
 166 /**
 167  * Returns the sum of all free heap blocks.
 168  *
 169  * This is the amount of memory you can theoretically allocate
 170  * if you do allocations exactly matching the free blocks.
 171  *
 172  * @returns The size of the free blocks.
 173  * @returns 0 if heap was safely detected as being bad.
 174  * @param   Heap    The heap.
 175  */
 176 RTDECL(size_t) RTHeapSimpleGetFreeSize(RTHEAPSIMPLE Heap);
 177
 178 /**
 179  * Printf like callbaclk function for RTHeapSimpleDump.
 180  * @param   pszFormat   IPRT format string.
 181  * @param   ...         Format arguments.
 182  */
 183 typedef DECLCALLBACK(void) FNRTHEAPSIMPLEPRINTF(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
 184 /** Pointer to a FNRTHEAPSIMPLEPRINTF function. */
 185 typedef FNRTHEAPSIMPLEPRINTF *PFNRTHEAPSIMPLEPRINTF;
 186
 187 /**
 188  * Dumps the hypervisor heap.
 189  *
 190  * @param   Heap        The heap handle.
 191  * @param   pfnPrintf   Printf like function that groks IPRT formatting.
 192  */
 193 RTDECL(void) RTHeapSimpleDump(RTHEAPSIMPLE Heap, PFNRTHEAPSIMPLEPRINTF pfnPrintf);
 194
 195 /** @}  */
 196
 197
 198
 199 /** @defgroup grp_rt_heap_offset    RTHeapOffset - Offset Based Heap
 200  *
 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.
 203  *
 204  * @{
 205  */
 206
 207 /**
 208  * Initializes the heap.
 209  *
 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.
 214  */
 215 RTDECL(int) RTHeapOffsetInit(PRTHEAPOFFSET phHeap, void *pvMemory, size_t cbMemory);
 216
 217 /**
 218  * Merge two simple heaps into one.
 219  *
 220  * The requirement is of course that they next two each other memory wise.
 221  *
 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.
 227  */
 228 RTDECL(int) RTHeapOffsetMerge(PRTHEAPOFFSET phHeap, RTHEAPOFFSET hHeap1, RTHEAPOFFSET hHeap2);
 229
 230 /**
 231  * Allocates memory from the specified simple heap.
 232  *
 233  * @returns Pointer to the allocated memory block on success.
 234  * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
 235  *
 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.
 240  */
 241 RTDECL(void *) RTHeapOffsetAlloc(RTHEAPOFFSET hHeap, size_t cb, size_t cbAlignment);
 242
 243 /**
 244  * Allocates zeroed memory from the specified simple heap.
 245  *
 246  * @returns Pointer to the allocated memory block on success.
 247  * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
 248  *
 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.
 253  */
 254 RTDECL(void *) RTHeapOffsetAllocZ(RTHEAPOFFSET hHeap, size_t cb, size_t cbAlignment);
 255
 256 /**
 257  * Reallocates / Allocates / Frees a heap block.
 258  *
 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.
 268  */
 269 RTDECL(void *) RTHeapOffsetRealloc(RTHEAPOFFSET hHeap, void *pv, size_t cbNew, size_t cbAlignment);
 270
 271 /**
 272  * Reallocates / Allocates / Frees a heap block, zeroing any new bits.
 273  *
 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.
 283  */
 284 RTDECL(void *) RTHeapOffsetReallocZ(RTHEAPOFFSET hHeap, void *pv, size_t cbNew, size_t cbAlignment);
 285
 286 /**
 287  * Frees memory allocated from a simple heap.
 288  *
 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
 292  */
 293 RTDECL(void) RTHeapOffsetFree(RTHEAPOFFSET hHeap, void *pv);
 294
 295 /**
 296  * Gets the size of the specified heap block.
 297  *
 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.
 301  *
 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
 305  */
 306 RTDECL(size_t) RTHeapOffsetSize(RTHEAPOFFSET hHeap, void *pv);
 307
 308 /**
 309  * Gets the size of the heap.
 310  *
 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
 313  * by this function.
 314  *
 315  * @returns The heap size.
 316  * @returns 0 if heap was safely detected as being bad.
 317  * @param   hHeap       The heap handle.
 318  */
 319 RTDECL(size_t) RTHeapOffsetGetHeapSize(RTHEAPOFFSET hHeap);
 320
 321 /**
 322  * Returns the sum of all free heap blocks.
 323  *
 324  * This is the amount of memory you can theoretically allocate
 325  * if you do allocations exactly matching the free blocks.
 326  *
 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.
 330  */
 331 RTDECL(size_t) RTHeapOffsetGetFreeSize(RTHEAPOFFSET hHeap);
 332
 333 /**
 334  * Printf like callbaclk function for RTHeapOffsetDump.
 335  * @param   pszFormat   IPRT format string.
 336  * @param   ...         Format arguments.
 337  */
 338 typedef DECLCALLBACK(void) FNRTHEAPOFFSETPRINTF(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
 339 /** Pointer to a FNRTHEAPOFFSETPRINTF function. */
 340 typedef FNRTHEAPOFFSETPRINTF *PFNRTHEAPOFFSETPRINTF;
 341
 342 /**
 343  * Dumps the hypervisor heap.
 344  *
 345  * @param   hHeap       The heap handle.
 346  * @param   pfnPrintf   Printf like function that groks IPRT formatting.
 347  */
 348 RTDECL(void) RTHeapOffsetDump(RTHEAPOFFSET hHeap, PFNRTHEAPOFFSETPRINTF pfnPrintf);
 349
 350 /** @}  */
 351
 352 /** @}  */
 353 RT_C_DECLS_END
 354
 355 #endif
 356