Memory allocation callback API

RIP memory allocation callback API. More...

Files
file	swmemapi.h
	Header file defining the Memory allocation callback API.

Data Structures
struct	sw_memory_instance
	An instance of the memory callback API implementation. More...
struct	sw_memory_api
	A structure containing callback functions for memory allocation. More...

Typedefs
typedef struct sw_memory_api	sw_memory_api
	Type definition of the memory callback interface implementation.
typedef struct sw_memory_instance	sw_memory_instance
	An instance of the memory callback API implementation. More...

Enumerations
enum	{ SW_MEMORY_API_VERSION_20070525 = 2 , SW_MEMORY_API_VERSION_20071110 }
	Version numbers defined for the memory management callback API. More...

Functions
sw_memory_instance *	SwAllocAPI (void)

Detailed Description

RIP memory allocation callback API.

This API is provided to modules which may need to do memory allocation, to allow the RIP to track and manage allocations from modules. Some APIs and callback functions are provided with a sw_memory_instance pointer. This is a pointer to an instantiation of a memory callback API. The callback function or API functions that have access to the sw_memory_instance pointer may call methods on the instance's sw_memory_instance::implementation pointer (of type sw_memory_api) to allocate and deallocate memory, in a manner that is appropriate to the callback or API.

The sw_memory_api implementation structure contains just two methods, sw_memory_api::alloc() to allocate memory, and sw_memory_api::free() to free memory. Both methods take the sw_memory_instance pointer as their first parameter, and the size of the allocation for sw_memory_api::alloc(), or the memory pointer to free for sw_memory_api::free() as the second parameter.

Using the callback memory API (where provided) is preferable to generic malloc() and free() calls or other RIP or skin allocation methods because the provider of the memory API instance can provide a context-aware allocator. For example, the allocator may understand the lifetime of the objects in the API that it is provided for, and may be able to automatically reclaim objects that are no longer valid; the allocator may interact with the RIP's low memory recovery better than a generic allocator; or the allocator may be able to track, debug and fix leaks from the API's usage.

A utility method, SwAllocAPI() is provided to return a memory callback API instance that allocates memory from the core library's memory pools. This function is implemented by the core library.

Typedef Documentation

sw_memory_instance

typedef struct sw_memory_instance sw_memory_instance

An instance of the memory callback API implementation.

There is only one public field in this structure, which is the required implementation pointer. The RIP will subclass instances to add private instance specific data.

The RIP manages the memory for this structure. Modules should not attempt to copy the structure, or access any data except the public fields.

Enumeration Type Documentation

anonymous enum

anonymous enum

Version numbers defined for the memory management callback API.

Enumerator
SW_MEMORY_API_VERSION_20070525	Obsolete as of 20071110
SW_MEMORY_API_VERSION_20071110	Current version

Function Documentation

SwAllocAPI()

sw_memory_instance* SwAllocAPI

(

void

)

Get an instance of the memory API for minor allocations from the core RIP's memory.

This can be used for minor allocations, like the old SwAlloc().