C Standard Library Extensions  1.1.1
Functions
Memory Management Utilities

Functions

void cx_memory_vtable_set (const cx_memory_vtable *table)
 Install a new set of memory managmement functions. More...
 
cxptr cx_malloc (cxsize nbytes)
 Allocate nbytes bytes. More...
 
cxptr cx_malloc_clear (cxsize nbytes)
 Allocate nbytes bytes and clear them. More...
 
cxptr cx_calloc (cxsize natoms, cxsize nbytes)
 Allocate memory for natoms elements of size size. More...
 
cxptr cx_realloc (cxptr memory, cxsize nbytes)
 Change the size of a memory block. More...
 
void cx_free (cxptr memory)
 Memory block deallocation. More...
 
cxbool cx_memory_is_system_malloc (void)
 Check if the system's defaults are used for memory allocation. More...
 

Detailed Description

The module provides wrapper routines for the standard C memory management functions. The wrappers for the system memory allocators guarantee to always return valid pointer to the allocated memory block of memory. If the requested memory cannot be allocated the functions stop the program calling abort(), following the philosophy that it is better to terminate the application immediately when running out of resources. The memory deallocator is protected against* passing NULL.

Synopsis:
#include <cxmemory.h>

Function Documentation

cxptr cx_calloc ( cxsize  natoms,
cxsize  nbytes 
)

Allocate memory for natoms elements of size size.

Parameters
natomsNumber of atomic elements.
nbytesElement size in bytes.
Returns
Pointer to the allocated memory block.

The function allocates memory suitable for storage of natoms elements of size nbytes bytes. The allocated memory is cleared, i.e. the value 0 is written to each single byte. If the allocation fails the function does not return, but the program execution is stopped printing a message to the error channel showing the current code position.

References cx_error().

Referenced by cx_line_alloc(), cx_path_alloc(), and cx_strndup().

void cx_free ( cxptr  memory)
cxptr cx_malloc ( cxsize  nbytes)

Allocate nbytes bytes.

Parameters
nbytesNumber of bytes.
Returns
Pointer to the allocated memory block.

The function allocates nbytes bytes of memory. The allocated memory is not cleared. If the allocation fails the function does not return, but the program execution is stopped printing a message to the error channel showing the current code position.

See Also
cx_malloc_clear()

References cx_error().

Referenced by cx_deque_new(), cx_list_new(), cx_log_set_handler(), cx_slist_new(), cx_string_append(), cx_string_erase(), cx_string_insert(), cx_string_prepend(), cx_strjoinv(), cx_strsplit(), cx_tree_new(), and cx_vasprintf().

cxptr cx_malloc_clear ( cxsize  nbytes)

Allocate nbytes bytes and clear them.

Parameters
nbytesNumber of bytes.
Returns
Pointer to the allocated memory block.

The function works as cx_malloc(), but the allocated memory is cleared, i.e. a 0 is written to each byte of the allocated block.

See Also
cx_malloc()

References cx_error().

cxbool cx_memory_is_system_malloc ( void  )

Check if the system's defaults are used for memory allocation.

Returns
It returns TRUE if memory is allocated through the system's malloc() implementation, it not it returns FALSE.

Checks whether the allocator used by cx_malloc() is the system's malloc implementation. If the system's malloc implementation is used memory allocated with the system's malloc() call can be used interchangeable with memory allocated by cx_malloc().

See Also
cx_memory_vtable_set()

Referenced by cx_vasprintf().

void cx_memory_vtable_set ( const cx_memory_vtable *  table)

Install a new set of memory managmement functions.

Parameters
tableSet of memory management functions.
Returns
Nothing.

The function installs the replacements for malloc(), calloc(), realloc() and free() provided by table in the internal vtable.

Attention
The function can be called only once before any of the memory handling functions are called, either explicitly or implicitly through another library functions! For thread-safety reasons the function may only be called from the main thread!

References cx_warning().

cxptr cx_realloc ( cxptr  memory,
cxsize  nbytes 
)

Change the size of a memory block.

Parameters
memoryNumber of atomic elements.
nbytesNew memory block size in bytes.
Returns
Pointer to the allocated memory block.

The function changes the size of an already allocated memory block memory to the new size nbytes bytes. The contents is unchanged to the minimum of old and new size; newly allocated memory is not initialized. If memory is NULL the call to cx_realloc() is equivalent to cx_malloc(), and if nbytes is 0 the call is equivalent to cx_free(). Unless memory is NULL, it must have been returned by a previous call to cx_malloc(), cx_malloc_clear(), cx_calloc(), or cx_realloc().

Note
The returned memory block returned on successfull allocation may not be the same as the one pointed to by memory. Existing references pointing to locations within the original memory block might be invalidated!
See Also
cx_malloc(), cx_malloc_clear(), cx_calloc()

References cx_error().