QuesaMemory.h

Discussion

Functions

( void * ) Q3Memory_Allocate (
    TQ3Uns32 theSize
);

Discussion

Allocates a block of memory of the specified size.

The pointer returned must be disposed of with Q3Memory_Free. The initial contents of the block are undefined.

This function is not available in QD3D.

Parameter Descriptions

theSize

The size in bytes of the block to allocate.

function result

A pointer to the block.

( void * ) Q3Memory_AllocateClear (
    TQ3Uns32 theSize
);

Discussion

Allocates a zero-filled block of memory of the specified size.

The pointer returned must be disposed of with Q3Memory_Free.

This function is not available in QD3D.

Parameter Descriptions

theSize

The size in bytes of the block to allocate.

function result

A pointer to the block.

( void ) Q3Memory_Clear (
    void *thePtr,
    TQ3Uns32 theSize
);

Discussion

Clears a block of memory.

Sets theSize bytes from thePtr to 0.

This function is not available in QD3D.

Parameter Descriptions

thePtr

A pointer to the memory to set.

theSize

The number of bytes to set.

( void ) Q3Memory_Copy (
    const void *srcPtr,
    void *dstPtr,
    TQ3Uns32 theSize
);

Discussion

Copies a block of memory.

Copies theSize bytes from srcPtr to dstPtr. The memory pointed to by srcPtr and dstPtr is allowed to overlap, although this may reduce performance.

This function is not available in QD3D.

Parameter Descriptions

srcPtr

A pointer to the block to copy.

dstPtr

A pointer to the memory to copy to.

theSize

The number of bytes to copy.

( TQ3Uns32 ) Q3Memory_CountRecords (void);

Discussion

Return the number of recorded allocations of Quesa objects.

In non-debug builds, this function returns 0.

This function is not available in QD3D.

function result

Success or failure of the operation.

( TQ3Status ) Q3Memory_DumpRecording (
    const char *fileName,
    const char *memo
);

Discussion

Write a text file listing Quesa objects that were created when recording was turned on and still exist. If there is already a file in the default directory with the specified name, new text is appended to it.

In non-debug builds, this function does nothing.

If recording is on when Q3Exit shuts down Quesa, this function will be called for you.

This function is not available in QD3D.

Parameter Descriptions

fileName

Name of memory dump file.

memo

Text written at start of dump for identification. May be NULL.

function result

Success or failure of the operation.

( TQ3Status ) Q3Memory_ForgetRecording (void);

Discussion

Forget any previously recorded allocations of Quesa objects.

In non-debug builds, this function does nothing.

This function is not available in QD3D.

function result

Success or failure of the operation.

#undef Q3Memory_Free #define Q3Memory_Free Q3Memory_Free_ (void) (
    Q3Memory_Free ( void **thePtr
);

Discussion

Frees a previously allocated block of memory.

Takes a pointer to a pointer, which points to a block of previously allocated memory.

After freeing the memory, the supplied pointer will be reset to NULL to prevent future dereferences.

Note that you must pass a pointer to a pointer, and not simply the pointer to the allocated memory. The double-indirection is deliberate, to ensure that the pointer can be fully invalidated after disposal.

This function is not available in QD3D.

Parameter Descriptions

thePtr

A pointer to the pointer to free.

( TQ3Status ) Q3Memory_GetStatistics (
    TQ3MemoryStatistics* info
);

Discussion

Retrieve debugging statistics about memory allocations by Quesa.

In non-debug builds (compiled with Q3_DEBUG or Q3_MEMORY_DEBUG set to 0) this function returns kQ3Failure.

This function is not available in QD3D.

Parameter Descriptions

info

Structure to receive memory statistics. You must initialize the structureVersion field to kQ3MemoryStatisticsStructureVersion.

function result

Success or failure of the operation.

( void ) Q3Memory_Initialize (
    void *thePtr,
    TQ3Uns32 theSize,
    TQ3Uns8 theValue
);

Discussion

Initialises a block of memory.

Sets theSize bytes from thePtr to theValue.

This function is not available in QD3D.

Parameter Descriptions

thePtr

A pointer to the memory to set.

theSize

The number of bytes to set.

theValue

The value to set at each byte.

( TQ3Boolean ) Q3Memory_IsRecording (void);

Discussion

Determine whether object allocations are being recorded.

This function is not available in QD3D.

function result

kQ3True if allocation recording is on.

( TQ3Object ) Q3Memory_NextRecordedObject (
    TQ3Object inObject
);

Discussion

This function can be used to iterate through the list of Quesa objects that were created while recording was turned on. Pass NULL to get the first object in the list. When it returns NULL, you have reached the end.

Example:

TQ3Object	leaked = NULL;
while (NULL != (leaked = Q3Memory_NextRecordedObject( leaked )))
{
  	// do something nondestructive to the object
}

Parameter Descriptions

inObject

NULL or a recorded object.

function result

Next recorded object, or NULL.

#undef Q3Memory_Reallocate #define Q3Memory_Reallocate Q3Memory_Reallocate_ (
    TQ3Status
) (
    Q3Memory_Reallocate ( void **thePtr,
    TQ3Uns32 newSize
);

Discussion

Attempts to reallocate a previously allocated block of memory.

Implements the same behaviour as realloc, allowing memory to be allocated, freed, or resized with a single call. See the documentation for realloc for the exact specification. Unlike some implementations of realloc, passing a size of zero frees the memory and returns NULL.

Note that like Q3Memory_Free, a pointer to the pointer is passed to allow it to be set to NULL after disposal, and to allow it to be changed when resized.

This function is not available in QD3D.

Parameter Descriptions

thePtr

A pointer to the pointer to reallocate.

newSize

The size in bytes to reallocate the block to.

function result

Success or failure of the operation.

( TQ3Status ) Q3Memory_StartRecording (void);

Discussion

Begin recording allocations of Quesa objects.

In non-debug builds, this function does nothing.

This function is not available in QD3D.

function result

Success or failure of the operation.

( TQ3Status ) Q3Memory_StopRecording (void);

Discussion

Stop recording allocations of Quesa objects.

In non-debug builds, this function does nothing.

This function is not available in QD3D.

function result

Success or failure of the operation.

( void * ) Q3SlabMemory_AppendData (
    TQ3SlabObject theSlab,
    TQ3Uns32 numItems,
    const void *itemData
);

Discussion

Append items to the end of a slab.

The slab will be grown as required, and the specified number of items will be appended to the end of the slab. A pointer to the newly-added items within the slab will be returned, or NULL on failure.

The slab may move in memory when it is grown, and any existing pointers into the slab should be invalidated.


If itemData is non-NULL, it is assumed to point to a contiguous block of item data. This data is copied into the slab to initialise the new items.

If no initialisation data is supplied, the contents of the items will be left uninitialised.


This function is not available in QD3D.

Parameter Descriptions

theSlab

The slab to update.

numItems

The number of items to append.

itemData

The data to initialise the new items, or NULL.

function result

A pointer to the first newly-added item within the slab.

( TQ3Uns32 ) Q3SlabMemory_GetCount (
    TQ3SlabObject theSlab
);

Discussion

Get the number of items within a slab.

This function is not available in QD3D.

Parameter Descriptions

theSlab

The slab to query.

function result

The number of items within the slab.

( void * ) Q3SlabMemory_GetData (
    TQ3SlabObject theSlab,
    TQ3Uns32 itemIndex
);

Discussion

Get a pointer to the data for an item within a slab.

Items are stored contiguously within a slab, and are indexed from 0.

The item index must be between 0 and the number of items in the slab, which can be obtained with Q3SlabMemory_GetCount.

This function is not available in QD3D.

Parameter Descriptions

theSlab

The slab to query.

itemIndex

The index of the item within the slab.

function result

A pointer to the specified item within the slab.

( TQ3SlabObject ) Q3SlabMemory_New (
    TQ3Uns32 itemSize,
    TQ3Uns32 numItems,
    const void *itemData
);

Discussion

Create a new memory slab object.

A slab may be created with an initial number of allocated items, which can be optionally initialised with supplied data.

Either numItems or itemData may be 0 (or NULL, respectively), however if itemData is non-NULL then numItems should be non-zero.

The itemSize parameter must be non-zero.

This function is not available in QD3D.

Parameter Descriptions

itemSize

The size of each item within the slab.

numitems

The initial number of items in the slab.

itemData

The data to initialise the new items, or NULL.

function result

The new slab object.

( TQ3Status ) Q3SlabMemory_SetCount (
    TQ3SlabObject theSlab,
    TQ3Uns32 numItems
);

Discussion

Set the number of items within a slab.

Existing items within the slab will be preserved when the slab is grown, and lost when the slab is shrunk.

The slab may move in memory on any resize operation, and pointers into the slab should be invalidated.

This function is not available in QD3D.

Parameter Descriptions

theSlab

The slab to update.

numItems

The number of items required in the slab.

function result

Success or failure of the operation.

Constants

Structs

typedef struct TQ3MemoryStatistics {
    TQ3Uns32  structureVersion;
    TQ3Uns32  currentAllocations;
    TQ3Uns32  maxAllocations;
    TQ3Int64  currentBytes;
    TQ3Int64  maxBytes;
} TQ3MemoryStatistics;

Field Descriptions

structureVersion

Version of this structure. Initialize to kQ3MemoryStatisticsStructureVersion.

currentAllocations

Current number of memory blocks allocated by Quesa.

maxAllocations

Maximum number of memory blocks allocated by Quesa.

currentBytes

Current number of memory bytes allocated by Quesa.

maxBytes

Maximum number of memory bytes allocated by Quesa ("high-water mark").

© 1999-2008 Quesa Developers (Last Updated 5/10/2008)