C Standard Library Extensions  1.0.5
Functions
Memory Management Utilities

Functions

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

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 immediatly 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_deque_new(), cx_deque_push_back(), cx_deque_push_front(), 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_sort(), cx_list_new(), cx_log_set_handler(), cx_slist_new(), 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. The function can be called only once before any of the memory handling functions has been called!

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