The
CFAllocatorContext
structure has seven fields defining callback functions. If you create a custom allocator you must implement at least the
allocate
function. Allocator callbacks should be thread-safe and, if the callback invokes other functions, they should be re-entrant as well.
The retain, release, and copy-description callbacks all take as their single argument the
info
field of the
CFAllocatorContext
structure. Typed as
void *
, this field points to and data that you define for the allocator, such as a structure containing control information.
const void *(*retain)(const void *info);
Retain the data you have defined for the allocator context in
info
. This might make sense only if the data is a Core Foundation object. You may set this function pointer to
NULL
.
void (*release)(const void *info);
Release (or free) the data you have defined for the allocator context. You may set this function pointer to
NULL
, but doing so might result in memory leaks.
CFStringRef (*copyDescription)(const void *info);
Return a reference to a CFString that describes your allocator, particularly some characteristics of your user-defined data. You may set this function pointer to
NULL
, in which case Core Foundation will provide a rudimentary description.
void * (*allocate)(CFIndex size, CFOptionFlags hint, void *info);
Allocate a block of memory of at least
size
bytes and return a pointer to the start of the block. The
hint
argument is a bitfield that you should currently not use. The
size
parameter should always be greater than zero. If it is not, or if problems in allocation occur, return
NULL
. This callback may not be
NULL
.
void * (*reallocate)(void *ptr, CFIndex newsize, CFOptionFlags hint, void *info);
Change the size of the block of memory pointed to by
ptr
to the size specified by
newsize
and return the pointer to the larger block of memory. Return
NULL
on any reallocation failure, leaving the old block of memory untouched. Also return
NULL
immediately if any of the following conditions apply:
Leave the contents of the old block of memory unchanged up to the lesser of the new or old sizes. If the
ptr
parameter is not a block of memory that has been previously allocated by the allocator, the results are undefined; abnormal program termination can occur. The
hint
argument is a bitfield that you should currently not use. If set this callback to
NULL
the
CFAllocatorReallocate
function returns
NULL
in most cases when it attempts to use this allocator.
void (*deallocate)(void *ptr, void *info);
Make the block of memory pointed to by
ptr
available for subsequent reuse by the allocator but unavailable for continued use by the program. The
ptr
parameter cannot be
NULL
and if the
ptr
parameter is not a block of memory that has been previously allocated by the allocator, the results are undefined; abnormal program termination can occur. You can set this callback to
NULL
, in which case the
CFAllocatorDeallocate
function has no effect.
CFIndex (*preferredSize)(CFIndex size, CFOptionFlags hint, void *info);
Return the actual size the allocator is likely to allocate given a request for a block of memory of size
size
. The
hint
argument is a bitfield that you should currently not use.