CFAllocator Reference

Overview

CFAllocator is an opaque type that allocates and deallocates memory for you. You never have to allocate, reallocate, or deallocate memory directly for Core Foundation objects—and rarely should you. You pass CFAllocator objects into functions that create objects; these functions have “Create” embedded in their names, for example, CFStringCreateWithPascalString. The creation functions use the allocators to allocate memory for the objects they create.

Functions by Task

Creating an Allocator

• CFAllocatorCreate

Managing Memory with an Allocator

• CFAllocatorAllocate
• CFAllocatorDeallocate
• CFAllocatorGetPreferredSizeForSize
• CFAllocatorReallocate

Getting and Setting the Default Allocator

• CFAllocatorGetDefault
• CFAllocatorSetDefault

Getting an Allocator's Context

• CFAllocatorGetContext

Getting the CFAllocator Type ID

• CFAllocatorGetTypeID

Functions

CFAllocatorAllocate

Allocates memory using the specified allocator.

void * CFAllocatorAllocate (
   CFAllocatorRef allocator,
   CFIndex size,
   CFOptionFlags hint
);

CFAllocatorCreate

Creates an allocator object.

CFAllocatorRef CFAllocatorCreate (
   CFAllocatorRef allocator,
   CFAllocatorContext *context
);

CFAllocatorDeallocate

Deallocates a block of memory with a given allocator.

void CFAllocatorDeallocate (
   CFAllocatorRef allocator,
   void *ptr
);

CFAllocatorGetContext

Obtains the context of the specified allocator or of the default allocator.

void CFAllocatorGetContext (
   CFAllocatorRef allocator,
   CFAllocatorContext *context
);

CFAllocatorGetDefault

Gets the default allocator object for the current thread.

CFAllocatorRef CFAllocatorGetDefault (
   void
);

CFAllocatorGetPreferredSizeForSize

Obtains the number of bytes likely to be allocated upon a specific request.

CFIndex CFAllocatorGetPreferredSizeForSize (
   CFAllocatorRef allocator,
   CFIndex size,
   CFOptionFlags hint
);

CFAllocatorGetTypeID

Returns the type identifier for the CFAllocator opaque type.

CFTypeID CFAllocatorGetTypeID (
   void
);

CFAllocatorReallocate

Reallocates memory using the specified allocator.

void * CFAllocatorReallocate (
   CFAllocatorRef allocator,
   void *ptr,
   CFIndex newsize,
   CFOptionFlags hint
);

CFAllocatorSetDefault

Sets the given allocator as the default for the current thread.

void CFAllocatorSetDefault (
   CFAllocatorRef allocator
);

Callbacks

CFAllocatorAllocateCallBack

A prototype for a function callback that allocates memory of a requested size.

typedef void *(*CFAllocatorAllocateCallBack) (
   CFIndex allocSize,
   CFOptionFlags hint,
   void *info
);

If you name your function MyCallBack, you would declare it like this:

void *MyCallBack (
   CFIndex allocSize,
   CFOptionFlags hint,
   void *info
);

CFAllocatorCopyDescriptionCallBack

A prototype for a function callback that provides a description of the specified data.

typedef CFStringRef (*CFAllocatorCopyDescriptionCallBack) (
   const void *info
);

If you name your function MyCallBack, you would declare it like this:

CFStringRef MyCallBack (
   const void *info
);

CFAllocatorDeallocateCallBack

A prototype for a function callback that deallocates a block of memory.

typedef void (*CFAllocatorDeallocateCallBack) (
   void *ptr,
   void *info
);

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   void *ptr,
   void *info
);

CFAllocatorPreferredSizeCallBack

A prototype for a function callback that gives the size of memory likely to be allocated, given a certain request.

typedef CFIndex (*CFAllocatorPreferredSizeCallBack) (
   CFIndex size,
   CFOptionFlags hint,
   void *info
);

If you name your function MyCallBack, you would declare it like this:

CFIndex MyCallBack (
   CFIndex size,
   CFOptionFlags hint,
   void *info
);

CFAllocatorReallocateCallBack

A prototype for a function callback that reallocates memory of a requested size for an existing block of memory.

typedef void *(*CFAllocatorReallocateCallBack) (
   void *ptr,
   CFIndex newsize,
   CFOptionFlags hint,
   void *info
);

If you name your function MyCallBack, you would declare it like this:

void *MyCallBack (
   void *ptr,
   CFIndex newsize,
   CFOptionFlags hint,
   void *info
);

CFAllocatorReleaseCallBack

A prototype for a function callback that releases the given data.

typedef void (*CFAllocatorReleaseCallBack) (
   const void *info
);

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   const void *info
);

CFAllocatorRetainCallBack

A prototype for a function callback that retains the given data.

typedef const void *(*CFAllocatorRetainCallBack) (
   const void *info
);

If you name your function MyCallBack, you would declare it like this:

const void *MyCallBack (
   const void *info
);

Data Types

CFAllocatorContext

A structure that defines the context or operating environment for an allocator (CFAllocator) object. Every Core Foundation allocator object must have a context defined for it.

struct CFAllocatorContext {
   CFIndex version;
   void *info;
   CFAllocatorRetainCallBack retain;
   CFAllocatorReleaseCallBack release;
   CFAllocatorCopyDescriptionCallBack copyDescription;
   CFAllocatorAllocateCallBack allocate;
   CFAllocatorReallocateCallBack reallocate;
   CFAllocatorDeallocateCallBack deallocate;
   CFAllocatorPreferredSizeCallBack preferredSize;
};
typedef struct CFAllocatorContext CFAllocatorContext;

Fields

version

An integer of type CFIndex. Assign the version number of the allocator. Currently the only valid value is 0.

info

An untyped pointer to program-defined data. Allocate memory for this data and assign a pointer to it. This data is often control information for the allocator. You may assign NULL.

retain

A prototype for a function callback that retains the data pointed to by the info field. In implementing this function, retain the data you have defined for the allocator context in this field. (This might make sense only if the data is a Core Foundation object.) You may set this function pointer to NULL.

release

A prototype for a function callback that releases the data pointed to by the info field. In implementing this function, 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.

copyDescription

A prototype for a function callback that provides a description of the data pointed to by the info field. In implementing this function, return a reference to a CFString object that describes your allocator, particularly some characteristics of your program-defined data. You may set this function pointer to NULL, in which case Core Foundation will provide a rudimentary description.

allocate

A prototype for a function callback that allocates memory of a requested size. In implementing this function, 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 (that is, assign 0). The size parameter should always be greater than 0. If it is not, or if problems in allocation occur, return NULL. This function pointer may not be assigned NULL.

reallocate

A prototype for a function callback that reallocates memory of a requested size for an existing block of memory. In implementing this function, 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:

• The ptr parameter is NULL.

• The newsize parameter is not greater than 0.

  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 (that is, assign 0). If you set this callback to NULL the CFAllocatorReallocate function returns NULL in most cases when it attempts to use this allocator.

deallocate

A prototype for a function callback that deallocates a given block of memory. In implementing this function, 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.

preferredSize

A prototype for a function callback that determines whether there is enough free memory to satisfy a request. In implementing this function, 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.

CFAllocatorRef

A reference to a CFAllocator object.

typedef const struct __CFAllocator *CFAllocatorRef;

Constants

Predefined Allocators

CFAllocator provides the following predefined allocators. In general, you should use kCFAllocatorDefault unless one of the special circumstances exist below.

const CFAllocatorRef kCFAllocatorDefault;
const CFAllocatorRef kCFAllocatorSystemDefault;
const CFAllocatorRef kCFAllocatorMalloc;
const CFAllocatorRef kCFAllocatorMallocZone;
const CFAllocatorRef kCFAllocatorNull;
const CFAllocatorRef kCFAllocatorUseContext;

Constants

kCFAllocatorDefault

This is a synonym for NULL.

Available in iOS 2.0 and later.

Declared in CFBase.h.

kCFAllocatorSystemDefault

Default system allocator.

You rarely need to use this.

Available in iOS 2.0 and later.

Declared in CFBase.h.

kCFAllocatorMalloc

This allocator uses malloc(), realloc(), and free().

Typically you should not use this allocator, use kCFAllocatorDefault instead. This allocator is useful as the bytesDeallocator in CFData or contentsDeallocator in CFString where the memory was obtained as a result of malloc type functions.

Available in iOS 2.0 and later.

Declared in CFBase.h.

kCFAllocatorMallocZone

This allocator explicitly uses the default malloc zone, returned by malloc_default_zone().

You should only use this when an object is safe to be allocated in non-scanned memory.

Available in iOS 2.0 and later.

Declared in CFBase.h.

kCFAllocatorNull

This allocator does nothing—it allocates no memory.

This allocator is useful as the bytesDeallocator in CFData or contentsDeallocator in CFString where the memory should not be freed.

Available in iOS 2.0 and later.

Declared in CFBase.h.

kCFAllocatorUseContext

Special allocator argument to CFAllocatorCreate—it uses the functions given in the context to allocate the allocator.

Available in iOS 2.0 and later.

Declared in CFBase.h.