allocator.h File Reference

Interface for custom allocators. More...

#include "common.h"

Go to the source code of this file.

Data Structures
struct	cx_allocator_class
	The class definition for an allocator. More...
struct	cx_allocator_s
	Structure holding the data for an allocator. More...

Macros
#define	cx_reallocate(mem, n)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.
#define	cx_reallocatearray(mem, nmemb, size)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.
#define	cx_zalloc(n)
	Allocates memory and sets every byte to zero.
#define	cxReallocate(allocator, mem, n)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.
#define	cxReallocateArray(allocator, mem, nmemb, size)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.
#define	cxMallocDefault(...)
	Convenience macro that invokes cxMalloc() with the cxDefaultAllocator.
#define	cxZallocDefault(...)
	Convenience macro that invokes cxZalloc() with the cxDefaultAllocator.
#define	cxCallocDefault(...)
	Convenience macro that invokes cxCalloc() with the cxDefaultAllocator.
#define	cxReallocDefault(...)
	Convenience macro that invokes cxRealloc() with the cxDefaultAllocator.
#define	cxReallocateDefault(...)
	Convenience macro that invokes cxReallocate() with the cxDefaultAllocator.
#define	cxReallocateArrayDefault(...)
	Convenience macro that invokes cxReallocateArray() with the cxDefaultAllocator.
#define	cxReallocArrayDefault(...)
	Convenience macro that invokes cxReallocArray() with the cxDefaultAllocator.
#define	cxFreeDefault(...)
	Convenience macro that invokes cxFree() with the cxDefaultAllocator.

Typedefs
typedef struct cx_allocator_s	CxAllocator
	High-Level type alias for the allocator type.
typedef void(*	cx_destructor_func) (void *memory)
	Function pointer type for destructor functions.
typedef void(*	cx_destructor_func2) (void *data, void *memory)
	Function pointer type for destructor functions.
typedef void *	cx_clone_func(void *target, const void *source, const CxAllocator *allocator, void *data)
	Function pointer type for clone functions.

Functions
int	cx_reallocate_ (void **mem, size_t n)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.
int	cx_reallocatearray_ (void **mem, size_t nmemb, size_t size)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.
void	cxFree (const CxAllocator *allocator, void *mem)
	Free a block allocated by this allocator.
void *	cxMalloc (const CxAllocator *allocator, size_t n)
	Allocate n bytes of memory.
void *	cxRealloc (const CxAllocator *allocator, void *mem, size_t n)
	Reallocate the previously allocated block in mem, making the new block n bytes long.
void *	cxReallocArray (const CxAllocator *allocator, void *mem, size_t nmemb, size_t size)
	Reallocate the previously allocated block in mem, making the new block n bytes long.
int	cxReallocate_ (const CxAllocator *allocator, void **mem, size_t n)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.
int	cxReallocateArray_ (const CxAllocator *allocator, void **mem, size_t nmemb, size_t size)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.
void *	cxCalloc (const CxAllocator *allocator, size_t nmemb, size_t size)
	Allocate nmemb elements of n bytes each, all initialized to zero.
void *	cxZalloc (const CxAllocator *allocator, size_t n)
	Allocate n bytes of memory and sets every byte to zero.

Variables
const CxAllocator *const	cxStdlibAllocator
	A pre-defined allocator using standard library malloc() etc.
const CxAllocator *	cxDefaultAllocator
	The default allocator that is used by UCX.

Detailed Description

Interface for custom allocators.

Macro Definition Documentation

cx_reallocate

#define cx_reallocate	(		mem,
			n )

Value:

cx_reallocate_((void**)(mem), n)

Reallocate a previously allocated block and changes the pointer in-place, if necessary.

Note

This will use stdlib reallocate and not the cxDefaultAllocator.

Error handling

errno will be set by realloc() on failure.

Parameters

mem	(void**) pointer to the pointer to allocated block
n	(size_t) the new size in bytes

Return values

zero	success
non-zero	failure

See also

cx_reallocatearray()

cx_reallocatearray

#define cx_reallocatearray	(		mem,
			nmemb,
			size )

Value:

    cx_reallocatearray_((void**)(mem), nmemb, size)

Reallocate a previously allocated block and changes the pointer in-place, if necessary.

The size is calculated by multiplying nemb and size.

Note

This will use stdlib reallocate and not the cxDefaultAllocator.

Error handling

errno will be set by realloc() on failure or when the multiplication of nmemb and size overflows.

Parameters

mem	(void**) pointer to the pointer to allocated block
nmemb	(size_t) the number of elements
size	(size_t) the size of each element

Return values

zero	success
non-zero	failure

cx_zalloc

#define cx_zalloc

(

n

)

Value:

calloc(1, n)

Allocates memory and sets every byte to zero.

Parameters

n	(size_t) the number of bytes

Returns

(void*) a pointer to the allocated memory

cxCallocDefault

#define cxCallocDefault

(

...

)

Value:

cxCalloc(cxDefaultAllocator, __VA_ARGS__)

Convenience macro that invokes cxCalloc() with the cxDefaultAllocator.

cxFreeDefault

#define cxFreeDefault

(

...

)

Value:

cxFree(cxDefaultAllocator, __VA_ARGS__)

Convenience macro that invokes cxFree() with the cxDefaultAllocator.

cxMallocDefault

#define cxMallocDefault

(

...

)

Value:

cxMalloc(cxDefaultAllocator, __VA_ARGS__)

Convenience macro that invokes cxMalloc() with the cxDefaultAllocator.

cxReallocArrayDefault

#define cxReallocArrayDefault

(

...

)

Value:

cxReallocArray(cxDefaultAllocator, __VA_ARGS__)

Convenience macro that invokes cxReallocArray() with the cxDefaultAllocator.

cxReallocate

#define cxReallocate	(		allocator,
			mem,
			n )

Value:

    cxReallocate_(allocator, (void**)(mem), n)

Reallocate a previously allocated block and changes the pointer in-place, if necessary.

This function acts like cxRealloc() using the pointer pointed to by mem.

Note

Re-allocating a block allocated by a different allocator is undefined.

Error handling

errno will be set if the underlying realloc function does so.

Parameters

allocator	(CxAllocator*) the allocator
mem	(void**) pointer to the pointer to allocated block
n	(size_t) the new size in bytes

Return values

zero	success
non-zero	failure

cxReallocateArray

#define cxReallocateArray	(		allocator,
			mem,
			nmemb,
			size )

Value:

        cxReallocateArray_(allocator, (void**) (mem), nmemb, size)

Reallocate a previously allocated block and changes the pointer in-place, if necessary.

This function acts like cxReallocArray() using the pointer pointed to by mem.

Note

Re-allocating a block allocated by a different allocator is undefined.

Error handling

errno will be set, if the underlying realloc function does so or the multiplication of nmemb and size overflows.

Parameters

allocator	(CxAllocator*) the allocator
mem	(void**) pointer to the pointer to allocated block
nmemb	(size_t) the number of elements
size	(size_t) the size of each element

Return values

zero	success
non-zero	failure

cxReallocateArrayDefault

#define cxReallocateArrayDefault

(

...

)

Value:

cxReallocateArray(cxDefaultAllocator, __VA_ARGS__)

Convenience macro that invokes cxReallocateArray() with the cxDefaultAllocator.

cxReallocateDefault

#define cxReallocateDefault

(

...

)

Value:

cxReallocate(cxDefaultAllocator, __VA_ARGS__)

Convenience macro that invokes cxReallocate() with the cxDefaultAllocator.

cxReallocDefault

#define cxReallocDefault

(

...

)

Value:

cxRealloc(cxDefaultAllocator, __VA_ARGS__)

Convenience macro that invokes cxRealloc() with the cxDefaultAllocator.

cxZallocDefault

#define cxZallocDefault

(

...

)

Value:

cxZalloc(cxDefaultAllocator, __VA_ARGS__)

Convenience macro that invokes cxZalloc() with the cxDefaultAllocator.

Typedef Documentation

cx_clone_func

typedef void * cx_clone_func(void *target, const void *source, const CxAllocator *allocator, void *data)

Function pointer type for clone functions.

A clone function is supposed to create a deep copy of the memory pointed to by the source pointer. If the target pointer is non-null, the clone function is supposed to store the copy into that memory region. Otherwise, the clone function shall use the specified allocator to create a new object.

The return value of a clone function is always a pointer to the target memory region, or NULL if any allocation failed. A clone function SHOULD NOT fail for any other reason than an allocation failure.

Parameters

target	the target memory or NULL, if memory shall be allocated
source	the source memory
allocator	the allocator that shall be used
data	optional additional data

Returns

either the specified target, a pointer to the allocated memory, or NULL, if any error occurred

cx_destructor_func

typedef void(* cx_destructor_func) (void *memory)

Function pointer type for destructor functions.

A destructor function deallocates possible contents and MAY free the memory pointed to by memory. Read the documentation of the respective function pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that particular implementation.

Parameters

memory

a pointer to the object to destruct

cx_destructor_func2

typedef void(* cx_destructor_func2) (void *data, void *memory)

Function pointer type for destructor functions.

A destructor function deallocates possible contents and MAY free the memory pointed to by memory. Read the documentation of the respective function pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that particular implementation.

Parameters

data	an optional pointer to custom data
memory	a pointer to the object to destruct

Function Documentation

cx_reallocate_()

int cx_reallocate_	(	void **	mem,
		size_t	n )

Reallocate a previously allocated block and changes the pointer in-place, if necessary.

Note

This will use stdlib reallocate and not the cxDefaultAllocator.

Error handling

errno will be set by realloc() on failure.

Parameters

mem	pointer to the pointer to allocated block
n	the new size in bytes

Return values

zero	success
non-zero	failure

See also

cx_reallocatearray()

cx_reallocatearray_()

int cx_reallocatearray_	(	void **	mem,
		size_t	nmemb,
		size_t	size )

Reallocate a previously allocated block and changes the pointer in-place, if necessary.

The size is calculated by multiplying nemb and size.

Note

This will use stdlib reallocate and not the cxDefaultAllocator.

Error handling

errno will be set by realloc() on failure or when the multiplication of nmemb and size overflows.

Parameters

mem	pointer to the pointer to allocated block
nmemb	the number of elements
size	the size of each element

Return values

zero	success
non-zero	failure

See also

cx_reallocate()

cxCalloc()

void * cxCalloc	(	const CxAllocator *	allocator,
		size_t	nmemb,
		size_t	size )

Allocate nmemb elements of n bytes each, all initialized to zero.

Parameters

allocator	the allocator
nmemb	the number of elements
size	the size of each element in bytes

Returns

a pointer to the allocated memory

cxFree()

void cxFree	(	const CxAllocator *	allocator,
		void *	mem )

Free a block allocated by this allocator.

Note

Freeing a block of a different allocator is undefined.

Parameters

allocator	the allocator
mem	a pointer to the block to free

cxMalloc()

void * cxMalloc	(	const CxAllocator *	allocator,
		size_t	n )

Allocate n bytes of memory.

Parameters

allocator	the allocator
n	the number of bytes

Returns

a pointer to the allocated memory

cxRealloc()

void * cxRealloc	(	const CxAllocator *	allocator,
		void *	mem,
		size_t	n )

Reallocate the previously allocated block in mem, making the new block n bytes long.

This function may return the same pointer passed to it if moving the memory was not necessary.

Note

Re-allocating a block allocated by a different allocator is undefined.

Parameters

allocator	the allocator
mem	pointer to the previously allocated block
n	the new size in bytes

Returns

a pointer to the reallocated memory

cxReallocArray()

void * cxReallocArray	(	const CxAllocator *	allocator,
		void *	mem,
		size_t	nmemb,
		size_t	size )

Reallocate the previously allocated block in mem, making the new block n bytes long.

This function may return the same pointer passed to it if moving the memory was not necessary.

The size is calculated by multiplying nemb and size. If that multiplication overflows, this function returns NULL, and errno will be set.

Note

Re-allocating a block allocated by a different allocator is undefined.

Parameters

allocator	the allocator
mem	pointer to the previously allocated block
nmemb	the number of elements
size	the size of each element

Returns

a pointer to the reallocated memory

cxReallocate_()

int cxReallocate_	(	const CxAllocator *	allocator,
		void **	mem,
		size_t	n )

Reallocate a previously allocated block and changes the pointer in-place, if necessary.

This function acts like cxRealloc() using the pointer pointed to by mem.

Note

Re-allocating a block allocated by a different allocator is undefined.

Error handling

errno will be set if the underlying realloc function does so.

Parameters

allocator	the allocator
mem	pointer to the pointer to allocated block
n	the new size in bytes

Return values

zero	success
non-zero	failure

cxReallocateArray_()

int cxReallocateArray_	(	const CxAllocator *	allocator,
		void **	mem,
		size_t	nmemb,
		size_t	size )

Reallocate a previously allocated block and changes the pointer in-place, if necessary.

This function acts like cxReallocArray() using the pointer pointed to by mem.

Note

Re-allocating a block allocated by a different allocator is undefined.

Error handling

errno will be set, if the underlying realloc function does so or the multiplication of nmemb and size overflows.

Parameters

allocator	the allocator
mem	pointer to the pointer to allocated block
nmemb	the number of elements
size	the size of each element

Return values

zero	success
non-zero	on failure

cxZalloc()

void * cxZalloc	(	const CxAllocator *	allocator,
		size_t	n )

Allocate n bytes of memory and sets every byte to zero.

Parameters

allocator	the allocator
n	the number of bytes

Returns

a pointer to the allocated memory

Variable Documentation

cxDefaultAllocator

const CxAllocator* cxDefaultAllocator

extern

The default allocator that is used by UCX.

Initialized with cxStdlibAllocator, but you may change it.