VirtualBox

Changeset 25055 in vbox


Ignore:
Timestamp:
Nov 27, 2009 3:45:49 PM (15 years ago)
Author:
vboxsync
Message:

iprt/heap.h: Prototypes an offset based variation of the simple heap. Docs in the header only. Cleanup before code fork.

Location:
trunk
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/iprt/heap.h

    r22273 r25055  
    11/** @file
    2  * IPRT - A Simple Heap.
     2 * IPRT - Heap Implementations
    33 */
    44
    55/*
    6  * Copyright (C) 2006-2007 Sun Microsystems, Inc.
     6 * Copyright (C) 2006-2009 Sun Microsystems, Inc.
    77 *
    88 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    3636RT_C_DECLS_BEGIN
    3737
     38/** @defgroup grp_rt_heap       RTHeap - Heap Implementations
     39 * @ingroup grp_rt
     40 * @{
     41 */
     42
     43
     44/** @defgroup grp_rt_heap_simple    RTHeapSimple - Simple Heap
     45 * @{
     46 */
     47
    3848/**
    3949 * Initializes the heap.
    … …  
    5969RTDECL(int) RTHeapSimpleMerge(PRTHEAPSIMPLE pHeap, RTHEAPSIMPLE Heap1, RTHEAPSIMPLE Heap2);
    6070
    61 /** 
    62  * Relocater the heap internal structures after copying it to a new location. 
    63  * 
    64  * This can be used when loading a saved heap. 
    65  * 
    66  * @returns IPRT status code. 
     71/**
     72 * Relocater the heap internal structures after copying it to a new location.
     73 *
     74 * This can be used when loading a saved heap.
     75 *
     76 * @returns IPRT status code.
    6777 * @param   hHeap       Heap handle that has already been adjusted by to the new
    6878 *                      location.  That is to say, when calling
    … …  
    7181 *                      must be used when calcuating the handle value for the
    7282 *                      new location.  The offset may in some cases not be zero!
    73  * @param   offDelta    The delta between the new and old location, i.e. what 
     83 * @param   offDelta    The delta between the new and old location, i.e. what
    7484 *                      should be added to the internal pointers.
    7585 */
    7686RTDECL(int) RTHeapSimpleRelocate(RTHEAPSIMPLE hHeap, uintptr_t offDelta);
    77  
     87
    7888/**
    7989 * Allocates memory from the specified simple heap.
    … …  
    187197RTDECL(void) RTHeapSimpleDump(RTHEAPSIMPLE Heap, PFNRTHEAPSIMPLEPRINTF pfnPrintf);
    188198
     199/** @}  */
     200
     201
     202
     203/** @defgroup grp_rt_heap_offset    RTHeapOffset - Offset Based Heap
     204 *
     205 * This is a variation on the simple heap that doesn't use pointers internally
     206 * and therefore can be saved and restored without any extra effort.
     207 *
     208 * @{
     209 */
     210
     211/**
     212 * Initializes the heap.
     213 *
     214 * @returns IPRT status code.
     215 * @param   phHeap      Where to store the heap anchor block on success.
     216 * @param   pvMemory    Pointer to the heap memory.
     217 * @param   cbMemory    The size of the heap memory.
     218 */
     219RTDECL(int) RTHeapOffsetInit(PRTHEAPOFFSET phHeap, void *pvMemory, size_t cbMemory);
     220
     221/**
     222 * Merge two simple heaps into one.
     223 *
     224 * The requirement is of course that they next two each other memory wise.
     225 *
     226 * @returns IPRT status code.
     227 * @param   phHeap      Where to store the handle to the merged heap on success.
     228 * @param   hHeap1      Handle to the first heap.
     229 * @param   hHeap2      Handle to the second heap.
     230 * @remark  This API isn't implemented yet.
     231 */
     232RTDECL(int) RTHeapOffsetMerge(PRTHEAPOFFSET phHeap, RTHEAPOFFSET hHeap1, RTHEAPOFFSET hHeap2);
     233
     234/**
     235 * Allocates memory from the specified simple heap.
     236 *
     237 * @returns Pointer to the allocated memory block on success.
     238 * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
     239 *
     240 * @param   hHeap       The heap to allocate the memory on.
     241 * @param   cb          The requested heap block size.
     242 * @param   cbAlignment The requested heap block alignment. Pass 0 for default alignment.
     243 *                      Must be a power of 2.
     244 */
     245RTDECL(void *) RTHeapOffsetAlloc(RTHEAPOFFSET hHeap, size_t cb, size_t cbAlignment);
     246
     247/**
     248 * Allocates zeroed memory from the specified simple heap.
     249 *
     250 * @returns Pointer to the allocated memory block on success.
     251 * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
     252 *
     253 * @param   hHeap       The heap to allocate the memory on.
     254 * @param   cb          The requested heap block size.
     255 * @param   cbAlignment The requested heap block alignment. Pass 0 for default
     256 *                      alignment. Must be a power of 2.
     257 */
     258RTDECL(void *) RTHeapOffsetAllocZ(RTHEAPOFFSET hHeap, size_t cb, size_t cbAlignment);
     259
     260/**
     261 * Reallocates / Allocates / Frees a heap block.
     262 *
     263 * @param   hHeap       The heap, mandatory.
     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, mandatory.
     278 * @param   pv          The heap block returned by RTHeapOffset. If NULL it
     279 *                      behaves like RTHeapOffsetAllocZ().
     280 * @param   cbNew       The new size of the heap block. If NULL it behaves like
     281 *                      RTHeapOffsetFree().
     282 * @param   cbAlignment The requested heap block alignment. Pass 0 for default
     283 *                      alignment. Must be a power of 2.
     284 * @remark  This API isn't implemented yet.
     285 */
     286RTDECL(void *) RTHeapOffsetReallocZ(RTHEAPOFFSET hHeap, void *pv, size_t cbNew, size_t cbAlignment);
     287
     288/**
     289 * Frees memory allocated from a simple heap.
     290 *
     291 * @param   hHeap       The heap handle, mandatory.
     292 * @param   pv          The heap block returned by RTHeapOffset
     293 */
     294RTDECL(void) RTHeapOffsetFree(RTHEAPOFFSET hHeap, void *pv);
     295
     296/**
     297 * Gets the size of the specified heap block.
     298 *
     299 * @returns The actual size of the heap block.
     300 * @returns 0 if \a pv is NULL or it doesn't point to a valid heap block. An
     301 *          invalid \a pv can also cause traps or trigger assertions.
     302 *
     303 * @param   hHeap       The heap handle, mandatory.
     304 * @param   pv          The heap block returned by RTHeapOffset
     305 */
     306RTDECL(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 */
     319RTDECL(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 */
     331RTDECL(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 */
     338typedef DECLCALLBACK(void) FNRTHEAPOFFSETPRINTF(const char *pszFormat, ...);
     339/** Pointer to a FNRTHEAPOFFSETPRINTF function. */
     340typedef 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 */
     348RTDECL(void) RTHeapOffsetDump(RTHEAPOFFSET hHeap, PFNRTHEAPOFFSETPRINTF pfnPrintf);
     349
     350/** @}  */
     351
     352/** @}  */
    189353RT_C_DECLS_END
    190354

  • trunk/include/iprt/types.h

    r23525 r25055  
    12371237#define NIL_RTHEAPSIMPLE                            ((RTHEAPSIMPLE)0)
    12381238
     1239/** Handle to a offset based heap. */
     1240typedef R3R0PTRTYPE(struct RTHEAPOFFSETINTERNAL *)  RTHEAPOFFSET;
     1241/** Pointer to a handle to a offset based heap. */
     1242typedef RTHEAPOFFSET                               *PRTHEAPOFFSET;
     1243/** NIL offset based heap handle. */
     1244#define NIL_RTHEAPOFFSET                            ((RTHEAPOFFSET)0)
     1245
    12391246/** Handle to an environment block. */
    12401247typedef R3PTRTYPE(struct RTENVINTERNAL *)           RTENV;

  • trunk/src/VBox/Runtime/common/alloc/heapsimple.cpp

    r22281 r25055  
    282282
    283283
    284 /**
    285  * Initializes the heap.
    286  *
    287  * @returns IPRT status code.
    288  * @param   pHeap       Where to store the heap anchor block on success.
    289  * @param   pvMemory    Pointer to the heap memory.
    290  * @param   cbMemory    The size of the heap memory.
    291  */
    292 RTDECL(int) RTHeapSimpleInit(PRTHEAPSIMPLE pHeap, void *pvMemory, size_t cbMemory)
     284RTDECL(int) RTHeapSimpleInit(PRTHEAPSIMPLE phHeap, void *pvMemory, size_t cbMemory)
    293285{
    294286    PRTHEAPSIMPLEINTERNAL pHeapInt;
    … …  
    338330    pFree->cb = pHeapInt->cbFree;
    339331
    340     *pHeap = pHeapInt;
     332    *phHeap = pHeapInt;
    341333
    342334#ifdef RTHEAPSIMPLE_STRICT
    … …  
    348340
    349341
    350 /**
    351  * Relocater the heap internal structures after copying it to a new location.
    352  * 
    353  * This can be used when loading a saved heap.
    354  * 
    355  * @returns IPRT status code.
    356  * @param   hHeap       Heap handle that has already been adjusted by to the new
    357  *                      location.  That is to say, when calling
    358  *                      RTHeapSimpleInit, the caller must note the offset of the
    359  *                      returned heap handle into the heap memory.  This offset
    360  *                      must be used when calcuating the handle value for the
    361  *                      new location.  The offset may in some cases not be zero!
    362  * @param   offDelta    The delta between the new and old location, i.e. what
    363  *                      should be added to the internal pointers.
    364  */
    365342RTDECL(int) RTHeapSimpleRelocate(RTHEAPSIMPLE hHeap, uintptr_t offDelta)
    366343{
    … …  
    373350    AssertPtrReturn(pHeapInt, VERR_INVALID_HANDLE);
    374351    AssertReturn(pHeapInt->uMagic == RTHEAPSIMPLE_MAGIC, VERR_INVALID_HANDLE);
    375     AssertMsgReturn((uintptr_t)pHeapInt - (uintptr_t)pHeapInt->pvEnd + pHeapInt->cbHeap == offDelta, 
    376                     ("offDelta=%p, expected=%p\n", offDelta, (uintptr_t)pHeapInt->pvEnd - pHeapInt->cbHeap - (uintptr_t)pHeapInt), 
     352    AssertMsgReturn((uintptr_t)pHeapInt - (uintptr_t)pHeapInt->pvEnd + pHeapInt->cbHeap == offDelta,
     353                    ("offDelta=%p, expected=%p\n", offDelta, (uintptr_t)pHeapInt->pvEnd - pHeapInt->cbHeap - (uintptr_t)pHeapInt),
    377354                    VERR_INVALID_PARAMETER);
    378355
    … …  
    388365     * Walk the heap blocks.
    389366     */
    390     for (pCur = (PRTHEAPSIMPLEFREE)(pHeapInt + 1); 
    391          pCur && (uintptr_t)pCur < (uintptr_t)pHeapInt->pvEnd; 
     367    for (pCur = (PRTHEAPSIMPLEFREE)(pHeapInt + 1);
     368         pCur && (uintptr_t)pCur < (uintptr_t)pHeapInt->pvEnd;
    392369         pCur = (PRTHEAPSIMPLEFREE)pCur->Core.pNext)
    393370    {
    … …  
    409386    rtHeapSimpleAssertAll(pHeapInt);
    410387#endif
    411     return VINF_SUCCESS; 
     388    return VINF_SUCCESS;
    412389}
    413390RT_EXPORT_SYMBOL(RTHeapSimpleRelocate);
    414391
    415392
    416 
    417 /**
    418  * Allocates memory from the specified simple heap.
    419  *
    420  * @returns Pointer to the allocated memory block on success.
    421  * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
    422  *
    423  * @param   Heap        The heap to allocate the memory on.
    424  * @param   cb          The requested heap block size.
    425  * @param   cbAlignment The requested heap block alignment. Pass 0 for default alignment.
    426  *                      Must be a power of 2.
    427  */
    428 RTDECL(void *) RTHeapSimpleAlloc(RTHEAPSIMPLE Heap, size_t cb, size_t cbAlignment)
    429 {
    430     PRTHEAPSIMPLEINTERNAL pHeapInt = Heap;
     393RTDECL(void *) RTHeapSimpleAlloc(RTHEAPSIMPLE hHeap, size_t cb, size_t cbAlignment)
     394{
     395    PRTHEAPSIMPLEINTERNAL pHeapInt = hHeap;
    431396    PRTHEAPSIMPLEBLOCK pBlock;
    432397
    … …  
    463428
    464429
    465 /**
    466  * Allocates zeroed memory from the specified simple heap.
    467  *
    468  * @returns Pointer to the allocated memory block on success.
    469  * @returns NULL if the request cannot be satisfied. (A VERR_NO_MEMORY condition.)
    470  *
    471  * @param   Heap        The heap to allocate the memory on.
    472  * @param   cb          The requested heap block size.
    473  * @param   cbAlignment The requested heap block alignment. Pass 0 for default alignment.
    474  *                      Must be a power of 2.
    475  */
    476 RTDECL(void *) RTHeapSimpleAllocZ(RTHEAPSIMPLE Heap, size_t cb, size_t cbAlignment)
    477 {
    478     PRTHEAPSIMPLEINTERNAL pHeapInt = Heap;
     430RTDECL(void *) RTHeapSimpleAllocZ(RTHEAPSIMPLE hHeap, size_t cb, size_t cbAlignment)
     431{
     432    PRTHEAPSIMPLEINTERNAL pHeapInt = hHeap;
    479433    PRTHEAPSIMPLEBLOCK pBlock;
    480434
    … …  
    519473 * @returns Pointer to the allocated block.
    520474 * @returns NULL on failure.
     475 *
    521476 * @param   pHeapInt    The heap.
    522477 * @param   cb          Size of the memory block to allocate.
    … …  
    686641
    687642
    688 
    689 
    690 /**
    691  * Frees memory allocated from a simple heap.
    692  *
    693  * @param   Heap    The heap. This is optional and will only be used for strict assertions.
    694  * @param   pv      The heap block returned by RTHeapSimple
    695  */
    696 RTDECL(void) RTHeapSimpleFree(RTHEAPSIMPLE Heap, void *pv)
     643RTDECL(void) RTHeapSimpleFree(RTHEAPSIMPLE hHeap, void *pv)
    697644{
    698645    PRTHEAPSIMPLEINTERNAL pHeapInt;
    … …  
    714661    ASSERT_BLOCK_USED(pHeapInt, pBlock);
    715662    ASSERT_ANCHOR(pHeapInt);
    716     Assert(pHeapInt == (PRTHEAPSIMPLEINTERNAL)Heap || !Heap);
     663    Assert(pHeapInt == (PRTHEAPSIMPLEINTERNAL)hHeap || !hHeap);
    717664
    718665#ifdef RTHEAPSIMPLE_FREE_POISON
    … …  
    887834
    888835
    889 /**
    890  * Gets the size of the specified heap block.
    891  *
    892  * @returns The actual size of the heap block.
    893  * @returns 0 if \a pv is NULL or it doesn't point to a valid heap block. An invalid \a pv
    894  *          can also cause traps or trigger assertions.
    895  * @param   Heap    The heap. This is optional and will only be used for strict assertions.
    896  * @param   pv      The heap block returned by RTHeapSimple
    897  */
    898 RTDECL(size_t) RTHeapSimpleSize(RTHEAPSIMPLE Heap, void *pv)
     836RTDECL(size_t) RTHeapSimpleSize(RTHEAPSIMPLE hHeap, void *pv)
    899837{
    900838    PRTHEAPSIMPLEINTERNAL pHeapInt;
    … …  
    917855    ASSERT_BLOCK_USED(pHeapInt, pBlock);
    918856    ASSERT_ANCHOR(pHeapInt);
    919     Assert(pHeapInt == (PRTHEAPSIMPLEINTERNAL)Heap || !Heap);
     857    Assert(pHeapInt == (PRTHEAPSIMPLEINTERNAL)hHeap || !hHeap);
    920858
    921859    /*
    … …  
    929867
    930868
    931 /**
    932  * Gets the size of the heap.
    933  *
    934  * This size includes all the internal heap structures. So, even if the heap is
    935  * empty the RTHeapSimpleGetFreeSize() will never reach the heap size returned
    936  * by this function.
    937  *
    938  * @returns The heap size.
    939  * @returns 0 if heap was safely detected as being bad.
    940  * @param   Heap    The heap.
    941  */
    942 RTDECL(size_t) RTHeapSimpleGetHeapSize(RTHEAPSIMPLE Heap)
     869RTDECL(size_t) RTHeapSimpleGetHeapSize(RTHEAPSIMPLE hHeap)
    943870{
    944871    PRTHEAPSIMPLEINTERNAL pHeapInt;
    945872
    946     if (Heap == NIL_RTHEAPSIMPLE)
     873    if (hHeap == NIL_RTHEAPSIMPLE)
    947874        return 0;
    948875
    949     pHeapInt = Heap;
     876    pHeapInt = hHeap;
    950877    AssertPtrReturn(pHeapInt, 0);
    951878    ASSERT_ANCHOR(pHeapInt);
    … …  
    955882
    956883
    957 /**
    958  * Returns the sum of all free heap blocks.
    959  *
    960  * This is the amount of memory you can theoretically allocate
    961  * if you do allocations exactly matching the free blocks.
    962  *
    963  * @returns The size of the free blocks.
    964  * @returns 0 if heap was safely detected as being bad.
    965  * @param   Heap    The heap.
    966  */
    967 RTDECL(size_t) RTHeapSimpleGetFreeSize(RTHEAPSIMPLE Heap)
     884RTDECL(size_t) RTHeapSimpleGetFreeSize(RTHEAPSIMPLE hHeap)
    968885{
    969886    PRTHEAPSIMPLEINTERNAL pHeapInt;
    970887
    971     if (Heap == NIL_RTHEAPSIMPLE)
     888    if (hHeap == NIL_RTHEAPSIMPLE)
    972889        return 0;
    973890
    974     pHeapInt = Heap;
     891    pHeapInt = hHeap;
    975892    AssertPtrReturn(pHeapInt, 0);
    976893    ASSERT_ANCHOR(pHeapInt);
    … …  
    980897
    981898
    982 /**
    983  * Dumps the hypervisor heap.
    984  *
    985  * @param   Heap        The heap handle.
    986  * @param   pfnPrintf   Printf like function that groks IPRT formatting.
    987  */
    988 RTDECL(void) RTHeapSimpleDump(RTHEAPSIMPLE Heap, PFNRTHEAPSIMPLEPRINTF pfnPrintf)
    989 {
    990     PRTHEAPSIMPLEINTERNAL pHeapInt = (PRTHEAPSIMPLEINTERNAL)Heap;
     899RTDECL(void) RTHeapSimpleDump(RTHEAPSIMPLE hHeap, PFNRTHEAPSIMPLEPRINTF pfnPrintf)
     900{
     901    PRTHEAPSIMPLEINTERNAL pHeapInt = (PRTHEAPSIMPLEINTERNAL)hHeap;
    991902    PRTHEAPSIMPLEFREE pBlock;
    992903
    993904    pfnPrintf("**** Dumping Heap %p - cbHeap=%zx cbFree=%zx ****\n",
    994               Heap, pHeapInt->cbHeap, pHeapInt->cbFree);
     905              hHeap, pHeapInt->cbHeap, pHeapInt->cbFree);
    995906
    996907    for (pBlock = (PRTHEAPSIMPLEFREE)(pHeapInt + 1);
    … …  
    1008919                      pBlock, (uintptr_t)pBlock - (uintptr_t)(pHeapInt + 1), pBlock->Core.pNext, pBlock->Core.pPrev, pBlock->Core.fFlags, cb);
    1009920    }
    1010     pfnPrintf("**** Done dumping Heap %p ****\n", Heap);
     921    pfnPrintf("**** Done dumping Heap %p ****\n", hHeap);
    1011922}
    1012923RT_EXPORT_SYMBOL(RTHeapSimpleDump);
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette