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(n)
	Allocate n bytes of memory.
#define	cxZallocDefault(n)
	Allocate n bytes of memory and sets every byte to zero.
#define	cxCallocDefault(nmemb, size)
	Allocate nmemb elements of size bytes each, all initialized to zero.
#define	cxReallocDefault(mem, n)
	Reallocate the previously allocated block in mem.
#define	cxReallocateDefault(mem, n)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.
#define	cxReallocateArrayDefault(mem, nmemb, size)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.
#define	cxReallocArrayDefault(mem, nmemb, size)
	Reallocate the previously allocated block in mem.

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
unsigned long	cx_system_page_size (void)
	Returns the system's memory page size.
int	cx_reallocate_ (void **mem, size_t n)
	Reallocate a previously allocated block.
int	cx_reallocatearray_ (void **mem, size_t nmemb, size_t size)
	Reallocate a previously allocated block.
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.
int	cxReallocate_ (const CxAllocator *allocator, void **mem, size_t n)
	Reallocate a previously allocated block.
int	cxReallocateArray_ (const CxAllocator *allocator, void **mem, size_t nmemb, size_t size)
	Reallocate a previously allocated block.
void *	cxCalloc (const CxAllocator *allocator, size_t nmemb, size_t size)
	Allocate nmemb elements of size 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.
void	cxFreeDefault (void *mem)
	Free a block of memory.

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	(		nmemb,
			size )

Value:

cxCalloc(cxDefaultAllocator, nmemb, size)

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

Convenience macro that invokes cxCalloc() with the cxDefaultAllocator.

Parameters

nmemb	(size_t) the number of elements
size	(size_t) the size of each element in bytes

Returns

(void*) a pointer to the allocated memory

cxMallocDefault

#define cxMallocDefault

(

n

)

Value:

cxMalloc(cxDefaultAllocator, n)

Allocate n bytes of memory.

Convenience macro that invokes cxMalloc() with the cxDefaultAllocator.

Parameters

n	(size_t) the number of bytes

Returns

(void*) a pointer to the allocated memory

cxReallocArrayDefault

#define cxReallocArrayDefault	(		mem,
			nmemb,
			size )

Value:

cxReallocArray(cxDefaultAllocator, mem, nmemb, size)

Reallocate the previously allocated block in mem.

Convenience macro that invokes cxReallocArray() with the cxDefaultAllocator.

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.

Attention

This function is bug-prone. Consider using cxReallocateArrayDefault().

Parameters

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

Returns

(void*) a pointer to the reallocated memory

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	(		mem,
			nmemb,
			size )

Value:

        cxReallocateArray(cxDefaultAllocator, 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.

Convenience macro that invokes cxReallocateArray() with the cxDefaultAllocator.

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

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

cxReallocateDefault

#define cxReallocateDefault	(		mem,
			n )

Value:

cxReallocate(cxDefaultAllocator, 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.

Convenience macro that invokes cxReallocate() with the cxDefaultAllocator.

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

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

Return values

zero	success
non-zero	failure

cxReallocDefault

#define cxReallocDefault	(		mem,
			n )

Value:

cxRealloc(cxDefaultAllocator, mem, n)

Reallocate the previously allocated block in mem.

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

Convenience macro that invokes cxRealloc() with the cxDefaultAllocator.

Attention

This function is bug-prone. Consider using cxReallocateDefault().

Parameters

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

Returns

(void*) a pointer to the reallocated memory

cxZallocDefault

#define cxZallocDefault

(

n

)

Value:

cxZalloc(cxDefaultAllocator, n)

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

Convenience macro that invokes cxZalloc() with the cxDefaultAllocator.

Parameters

n	(size_t) the number of bytes

Returns

(void*) a pointer to the allocated memory

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.

Internal function - do not use.

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.

Internal function - do not use.

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()

cx_system_page_size()

unsigned long cx_system_page_size

(

void

)

Returns the system's memory page size.

If the page size cannot be retrieved from the system, a default of 4096 bytes is assumed.

Returns

the system's memory page size in bytes

cxCalloc()

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

Allocate nmemb elements of size 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

cxFreeDefault()

void cxFreeDefault

(

void *

mem

)

Free a block of memory.

Convenience function that invokes cxFree() with the cxDefaultAllocator.

Parameters

mem	the memory to deallocate

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.

Attention

This function is bug-prone. Consider using cxReallocate().

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.

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.

Attention

This function is bug-prone. Consider using cxReallocateArray().

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.

Internal function - do not use.

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.

Internal function - do not use.

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.