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)   cx_reallocate_((void**)(mem), n)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.
#define	cx_reallocatearray(mem, nmemb, size)    cx_reallocatearray_((void**)(mem), nmemb, size)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.
#define	cxReallocate(allocator, mem, n)    cxReallocate_(allocator, (void**)(mem), n)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.
#define	cxReallocateArray(allocator, mem, nmemb, size)    cxReallocateArray_(allocator, (void**) (mem), nmemb, size)
	Reallocate a previously allocated block and changes the pointer in-place, if necessary.

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.

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.

Variables
const CxAllocator *const	cxDefaultAllocator
	A default allocator using standard library malloc() etc.

Detailed Description

Interface for custom allocators.

Macro Definition Documentation

cx_reallocate

#define cx_reallocate	(		mem,
			n )   cx_reallocate_((void**)(mem), n)

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

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

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

cxReallocate

#define cxReallocate	(		allocator,
			mem,
			n )    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 )    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

Typedef Documentation

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.

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.

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 that was 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 that was 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