Main Page   Modules   Alphabetical List   Data Structures   Data Fields  

RwFreeList
[Initialization & Resource Management]


Data Structures
struct   RwFreeList

Defines
#define  rwFREELISTFLAG_STATIC   0x00000001
#define  rwFREELISTFLAG_FREEBLOCKS

Typedefs
typedef void(*  RwFreeListCallBack )(void *pMem, void *pData)

Functions
RwFreeList *  RwFreeListCreate (RwInt32 entrySize, RwInt32 entriesPerBlock, RwInt32 alignment)
RwFreeList *  RwFreeListCreateAndPreallocateSpace (RwInt32 entrySize, RwInt32 entriesPerBlock, RwInt32 alignment, RwInt32 numBlocksToPreallocate, RwFreeList *inPlaceSpaceForFreeListStruct)
RwBool  RwFreeListDestroy (RwFreeList *freeList)
void  RwFreeListSetFlags (RwFreeList *freeList, RwUInt32 flags)
RwUInt32  RwFreeListGetFlags (RwFreeList *freeList)
void *  RwFreeListAlloc (RwFreeList *freelist)
RwFreeList *  RwFreeListFree (RwFreeList *freelist, void *pBlock)
RwInt32  RwFreeListPurge (RwFreeList *freeList)
RwFreeList *  RwFreeListForAllUsed (RwFreeList *freeList, RwFreeListCallBack fpCallBack, void *pData)
RwInt32  RwFreeListPurgeAllFreeLists (void)

Detailed Description

Free lists

RwFreeList Overview

Requirements

Overview

This object provides a platform-neutral memory allocation API.

A free list can be used to allocate memory for lists of identical data types. As the list is filled, the free list mechanism can be set to automatically allocate more memory in developer-defined chunks. Getting the most out of this system can require some fine-tuning work, but the result should be an optimal trade-off between the amount of memory used and speed.

RenderWare's internal freelists can be configured as appropriate for your application's usage.

See also:
RwCameraSetFreeListCreateParams , RwFrameSetFreeListCreateParams , RwImageSetFreeListCreateParams , RwImageFormatSetFreeListCreateParams , RwRasterSetFreeListCreateParams , RwTextureSetFreeListCreateParams , RwTexDictionarySetFreeListCreateParams , RwMatrixSetFreeListCreateParams , RwStreamSetFreeListCreateParams , RwPluginRegistrySetFreeListCreateParams , RxPipelineSetFreeListCreateParams , RpAtomicSetFreeListCreateParams , RpClumpSetFreeListCreateParams , RpLightSetFreeListCreateParams , RpLightTieSetFreeListCreateParams , RpMaterialSetFreeListCreateParams , RpTieSetFreeListCreateParams , RpHAnimHierarchySetFreeListCreateParams , RpLODAtomicCacheSetFreeListCreateParams , RpMatFXMaterialDataSetFreeListCreateParams , RpPatchAtomicSetFreeListCreateParams , RpPatchGeometrySetFreeListCreateParams , RpSkinSetFreeListCreateParams , Rt2dBrushSetFreeListCreateParams , Rt2dFontSetFreeListCreateParams , Rt2dFontDictNodeSetFreeListCreateParams , Rt2dObjectSetFreeListCreateParams , Rt2dPathSetFreeListCreateParams , RtAnimAnimationFreeListCreateParams
Freelists -- from Page 131 Advanced Animation and Rendering Techniques Alan Watt and Mark Watt Addison-Wesley 1993, ISBN 0-201-54412-1:

"Lastly, on a more general note concerning speedups for renderers, the implementor should be aware that a lot of suggestions for improving efficiency fall into the category of ingenious, but complex, algorithms for very specific contexts that may save a few microseconds but which make your code unreadable. A more general computer science perspective that takes a `global view' of the renderer can be more fruitful. For example, the renderer devotes a lot of time to allocating and deallocating chunks of memory for storing data. A lot of these chunks are always the same size - such as those that are continually required to store the data structure for fragment lists. Using memory management techniques that recognize this fact can yield considerable dividends. One such scheme would be to hold a series of empty lists in memory for all the commonly used data structures. An empty list for fragments, say, would contain a list of previously allocated, but no longer needed, fragment structures. When the renderer needs memory for a new fragment, it looks first at this empty list. If there is nothing there it allocates space directly, otherwise it takes a fragments off the end of the list and uses that. Conversely, when the renderer no longer needs a fragment, instead of freeing it, it goes onto the end of the empty list. In the authors' experience, replacing the naive allocate/deallocate scheme with this way of managing memory can result in 100% speedup. "

Define Documentation

#define rwFREELISTFLAG_FREEBLOCKS
 

Free blocks as soon as they are empty

See also:
RwFreeListSetFlags
#define rwFREELISTFLAG_STATIC   0x00000001
 

The free list was statically allocated

See also:
RwFreeListSetFlags

Typedef Documentation

typedef void(* RwFreeListCallBack)(void *pMem, void *pData)
 

RwFreeListCallBack represents the function called from RwFreeListForAllUsed for all used entries in a given free list.

Parameters:
pMem  Pointer to the start of the current entries.
pData  User-defined data pointer.
See also:
RwFreeListForAllUsed

Function Documentation

void* RwFreeListAlloc (  RwFreeList *    freelist ) 
 

RwFreeListAlloc is used to retrieve an unused entry from the specified free list. If, prior to this function call, the free list is empty, the whole free list block is allocated memory. If there are no more unused entries left, new entries are retrieved from another allocated block. Note that this function can be coerced to call RwMalloc through the second argument to RwEngineInit. This is actually implemented as a macro that expands to either _rwFreeListAllocReal or RwMalloc.

Parameters:
freelist  Pointer to the free list.
Returns:
Returns pointer to an unused entry if successful or NULL is there is an error.
See also:
RwFreeListCreate , RwFreeListFree , RwFreeListPurge , RwFreeListForAllUsed , RwFreeListDestroy , RwFreeListPurgeAllFreeLists
RwFreeList* RwFreeListCreate (  RwInt32    entrySize,
RwInt32    entriesPerBlock,
RwInt32    alignment
) 
 

RwFreeListCreate is deprecated. RwFreeListCreateAndPreallocateSpace should be used instead to give better control over freelist allocations.

Parameters:
entrySize  An RwInt32 value equal to the size of each entry (in bytes)
entriesPerBlock  An RwInt32 value equal to the number of entries per block
alignment  An RwInt32 value equal to the desired byte alignment of entries. The alignment must be a power of two. Zero indicates don't care.
Returns:
Returns a pointer to the new free list if successful or NULL if there is an error.
See also:
RwFreeListAlloc , RwFreeListFree , RwFreeListPurge , RwFreeListForAllUsed , RwFreeListDestroy , RwFreeListPurgeAllFreeLists
RwFreeList* RwFreeListCreateAndPreallocateSpace (  RwInt32    entrySize,
RwInt32    entriesPerBlock,
RwInt32    alignment,
RwInt32    numBlocksToPreallocate,
RwFreeList *    inPlaceSpaceForFreeListStruct
) 
 

RwFreeListCreateAndPreallocateSpace is used to create a new free list that will contain the specified number of entries, each of the specified size (in bytes), in a single block of memory. More blocks can be be allocated or freed as necessary in response to RwFreeListAlloc or RwFreeListFree.

Parameters:
entrySize  An RwInt32 value equal to the size of each entry (in bytes)
entriesPerBlock  An RwInt32 value equal to the number of entries per block
alignment  An RwInt32 value equal to the desired byte alignment of entries. The alignment must be a power of two.
numBlocksToPreallocate  An RwInt32 value specifying how many blocks to allocate now. 0 will wait until the first RwFreeListAlloc called on this list. Note that this isn't always a good policy and can cause fragmentation - allocating at least one block is often better.
inPlaceSpaceForFreeListStruct  A pointer to enough memory to store an RwFreeList structure. If NULL is passed memory will instead be allocated for the structure with RwMalloc.
Returns:
Returns a pointer to the new free list if successful or NULL if there is an error.
See also:
RwFreeListAlloc , RwFreeListFree , RwFreeListPurge , RwFreeListForAllUsed , RwFreeListDestroy , RwFreeListPurgeAllFreeLists
RwBool RwFreeListDestroy (  RwFreeList *    freeList ) 
 

RwFreeListDestroy is used to release the block (or blocks) of memory used by the specified free list.

Parameters:
freeList  A pointer to the free list
Returns:
Returns TRUE if successful or FALSE if there is an error
See also:
RwFreeListAlloc , RwFreeListCreate , RwFreeListFree , RwFreeListPurge , RwFreeListForAllUsed , RwFreeListPurgeAllFreeLists
RwFreeList* RwFreeListForAllUsed (  RwFreeList *    freeList,
RwFreeListCallBack    fpCallBack,
void *    pData
) 
 

RwFreeListForAllUsed is used to apply the given callback function to all used entries in the specified free list. The format of the callback function is:

        void (*RwFreeListCallBack)(void *mem, void *data);
where "data" is a pointer to user-defined data pointer to pass to the callback function.
Parameters:
freeList  A pointer to the free list
fpCallBack  A pointer to the callback to apply to call with each used block
pData  A pointer to user-supplied data to pass to callback function.
Returns:
Returns pointer to the free list if successful or NULL if there is an error.
See also:
RwFreeListAlloc , RwFreeListCreate , RwFreeListFree , RwFreeListPurge , RwFreeListDestroy , RwFreeListPurgeAllFreeLists
RwFreeList* RwFreeListFree (  RwFreeList *    freelist,
void *    pBlock
) 
 

RwFreeListFree is used to mark the specified entry contained in the given free list as unused. Note that this function can be coerced to call RwFree through the second argument to RwEngineInit. This function is actually implemented as a macro that expands to either _rwFreeListFreeReal or RwFree.

Parameters:
freelist  A pointer a to freelist
pBlock  A pointer to a used entry.
Returns:
Returns a pointer to the free list if successful or NULL if there is an error.
See also:
RwFreeListAlloc , RwFreeListCreate , RwFreeListPurge , RwFreeListForAllUsed , RwFreeListDestroy , RwFreeListPurgeAllFreeLists
RwUInt32 RwFreeListGetFlags (  RwFreeList *    freeList ) 
 

RwFreeListGetFlags Get the allocation mode of a freelist. For more information see RwFreeListSetFlags

Parameters:
freeList  Pointer to the free list to retrive flags from.
Returns:
Currently set flags for the specified freelist
See also:
RwFreeListSetFlags
RwInt32 RwFreeListPurge (  RwFreeList *    freeList ) 
 

RwFreeListPurge is used to the release the memory for any blocks in the specified free list that wholly contain unused entries. It returns the amount of memory (in bytes) recovered.

Parameters:
freeList  A pointer to free list.
Returns:
Returns the amount of memory freed, or -1 if there is an error.
See also:
RwFreeListAlloc , RwFreeListCreate , RwFreeListFree , RwFreeListForAllUsed , RwFreeListDestroy , RwFreeListPurgeAllFreeLists
RwInt32 RwFreeListPurgeAllFreeLists (  void    ) 
 

RwFreeListPurgeAllFreeLists is used to purge all free lists in the system. It returns the amount of memory freed as a result.

Returns:
Returns the amount of memory freed if successful, or -1 if there is an error.
See also:
RwFreeListAlloc , RwFreeListCreate , RwFreeListFree , RwFreeListPurge , RwFreeListDestroy , RwFreeListForAllUsed
void RwFreeListSetFlags (  RwFreeList *    freeList,
RwUInt32    flags
) 
 

RwFreeListSetFlags Set the allocation mode of a freelist. Currently the only flag available is rwFREELISTFLAG_FREEBLOCKS. This flag is set by default and causes free blocks to be deallocated from the heap as soon as a freelist entry is freed. If this flag is cleared all free freelist blocks will remain.

Parameters:
freeList  Pointer to the free list to change the flags on.
flags  The new flags for the free list.
Returns:
Nothing
See also:
RwFreeListGetFlags , RwFreeListAlloc , RwFreeListFree
Criterion Software © 1993-2003 Criterion Software Limited. All rights reserved. Built Tue Apr 22 12:46:13 2003. Send Feedback
Converted from CHM to HTML with chm2web Pro 2.85 (unicode)