BRender Technical Reference Manual:3 Functions (Structured Reference):Resource Management
Next|Prev|Up
BrResAllocate()
BrResAdd()
BrResStrDup()
BrResClass()
BrResSize()
BrResChildEnum()
BrResRemove()
BrResFree()

Resource Management


BRender divides all memory allocation according to a set of classes, called memory classes, or resource classes. Each memory class is notionally separate and is useful in distinguishing between different types of memory usage (for allocation policies, debugging, performance analysis, releasing all memory in a class as a whole). The term resource class is used to indicate an advanced use of the memory class, in a structured fashion, where resource blocks (special blocks of memory allocated from the resource class) can be allocated as dependants of another resource block. Similar to C++, this enables destruction of a resource block to automatically delete all its dependent resource blocks automatically. This lightens the application programmer's burden of responsibility. BRender utilises this feature in a lot of the data structures it allocates - br_actor
74 is a good example in the way it may allocate default, type specific data.

Generally, you will not need to explicitly free resource blocks allocated by BRender, even if you overwrite pointers to them, as a separate record is maintained of their existence and what they are attached to. This ensures that when something is freed that any resource blocks attached to it are also freed. The only time attached resources need to be freed sooner is if memory is very limited and there is a disproportionately high turnover of allocations of a dependant compared to its parent's lifetime. In such cases BrResFree()51 can be used (with caution) to free the dependent immediately, e.g. destroying unwanted models loaded using BrFmtASCLoad()244.

For simple applications the simple memory allocation functions can be used (see BrMemAllocate()55), and where structured allocation is required, resource blocks can be allocated from the BR_MEMORY_APPLICATION resource class. For more advanced applications requiring greater control, new resource classes can be created (see br_resource_class324).

There are other features of resource blocks, including the ability to have a call-back function called for each resource block of a particular class.

You will find BrResStrDup()49 quite useful for specifying identifiers of various data structures.


BrResAllocate()

Description:
Allocate a new resource block of a given class.

Declaration:
void* BrResAllocate(void* vparent, br_size_t size, int res_class)

Arguments:
void * vparent

A pointer to a parental resource block, or Null if it will have no parent.

br_size_t size

Size of block in bytes.

int res_class

Resource class (See Memory Management, page 53).

Result:
void *

Returns a pointer to the allocated resource block (of at least size bytes).


BrResAdd()

Description:
Add a resource block as a dependant or child of another.

Declaration:
void* BrResAdd(void* vparent, void* vres)

Arguments:
void * vparent

A non-Null pointer to the parent resource block.

void * vres

A non-Null pointer to the child resource block (will be removed from any current parent).

Result:
void *

Returns a pointer to the child resource block.

Remarks:
Once a resource block has been added as a dependant, it can be freed due to its parent being freed.


BrResStrDup()

Description:
Duplicate a string.

Declaration:
char* BrResStrDup(void* vparent, const char* str)

Arguments:
void * vparent

A pointer to a parental resource block (or Null if independent).

const char * str

A non-Null pointer to the source string.

Effects:
Allocates a resource block (from the
BR_MEMORY_STRING resource class) and copies a string into it.

Result:
char *

Returns a pointer to the allocated resource block.

Remarks:
This is most useful for specifying identifiers for various BRender data structures.


BrResClass()

Description:
Determine the class of a given resource block.

Declaration:
br_uint_8 BrResClass(void* vres)

Arguments:
void * vres

A non-Null pointer to a resource block.

Result:
br_uint_8

Returns the resource class.


BrResSize()

Description:
Determine the size of a given resource block.

Declaration:
br_uint_32 BrResSize(void* vres)

Arguments:
void * vres

A non-Null pointer to a resource block.

Result:
br_uint_32

Returns the size of the resource block in bytes (may not necessarily be the same as that specified upon allocation, but will not be less).


BrResChildEnum()

Description:
Enumerate through all dependant resource blocks of a particular resource block.

Declaration:
br_uint_32 BrResChildEnum(void* vres, br_resenum_cbfn* callback, void* arg)

Arguments:
void * vres

A non-Null pointer to a resource block.

br_resenum_cbfn * callback

A non-Null pointer to a call-back function.

void * arg

An optional argument to pass to the call-back function.

Effects:
Invoke a call-back function for each child of a resource block. The call-back is passed a pointer to each child, and its second argument is an optional pointer (arg) supplied by the user. The call-back itself returns a br_uint_32
348 value. The enumeration will halt at any stage if the return value is non-zero.

Result:
br_uint_32

Returns the first non-zero call-back return value, or zero if all children are enumerated.

Remarks:
This function does not recurse throughout all descendants. If you require such behaviour, you'll need to implement it yourself.

Example:
	br_uint_32 example_callback(void *vres, void *arg)
	{br_uint_32 value;
	...
		return(value);
	}
	{	br_uint_32 ev;
		void *rblock;
	...
		ev = BrResChildEnum(rblock,&example_callback,NULL);
	}

BrResRemove()

Description:
Remove a resource block from a parent.

Declaration:
void* BrResRemove(void* vres)

Arguments:
void * vres

A non-Null pointer to the resource block to be removed.

Result:
void *

Returns a pointer to the removed resource block.

Remarks:
The resource block will become independent, as though it had been allocated specifying Null as its parent.


BrResFree()

Description:
Free a resource block.

Declaration:
void BrResFree(void* vres)

Arguments:
void * vres

A pointer to a resource block (previously allocated using BrResAllocate()48 or BrResStrDup()49).

Effects:
Frees the resource block, and any dependent resource blocks it has. If any resource classes have destructors (see br_resource_class324), they are invoked when appropriate.

Example:
	void BR_CALLBACK example_destructor(void* res, br_uint_8 res_class, br_size_t size)
	{
	...
	}

	#define EXAMPLE_CLASS (BR_MEMORY_APPLICATION + 1)

	static br_resource_class example={"My Class",EXAMPLE_CLASS,example_destructor};

	{	BrResClassAdd(&example);	/* Create resource class */
		...
		{	void *ptr;
			ptr = BrResAllocate(NULL,1024,EXAMPLE_CLASS);
			...
			BrResFree(ptr);	/* Destructor is invoked */
		}
	}
See Also:
BrResClassAdd()325



Generated with CERN WebMaker