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 immediately when running out of resources. The memory deallocator is protected against passing `NULL`.

Synopsis:
  #include "cxmemory.h"

## Function Documentation

## cx_calloc()

cxptr cx_calloc | ( | cxsize | natoms,
|  | cxsize | nbytes )

Allocate memory for natoms elements of size size.

Parameters

  natoms | Number of atomic elements.
  nbytes | Element 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(), cx_string_extend(), and cx_strndup().

## cx_free()

void cx_free | ( | cxptr | memory | ) |

Memory block deallocation.

Returns
  Nothing.

Deallocates a memory block previously allocated by cx_malloc(), cx_malloc_clear(), cx_calloc(), or cx_realloc().

See also
  cx_malloc(), cx_malloc_clear(), cx_calloc()

Referenced by cx_deque_delete(), cx_deque_destroy(), cx_list_delete(), cx_list_destroy(), cx_log_remove_handler(), cx_logv(), cx_print(), cx_printerr(), cx_program_set_name(), cx_slist_delete(), cx_slist_destroy(), cx_strfreev(), cx_string_append(), cx_string_delete(), cx_string_erase(), cx_string_extend(), cx_string_insert(), cx_string_prepend(), cx_string_resize(), cx_string_substr(), and cx_tree_delete().

## cx_malloc()

cxptr cx_malloc | ( | cxsize | nbytes | ) |

Allocate nbytes bytes.

Parameters

  nbytes | Number 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_string_resize(), cx_string_substr(), cx_strjoinv(), cx_strsplit(), cx_tree_new(), and cx_vasprintf().

## cx_malloc_clear()

cxptr cx_malloc_clear | ( | cxsize | nbytes | ) |

Allocate nbytes bytes and clear them.

Parameters

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

## cx_memory_is_system_malloc()

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

## cx_memory_vtable_set()

void cx_memory_vtable_set | ( | const cx_memory_vtable * | table | ) |

Install a new set of memory managmement functions.

Parameters

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

## cx_realloc()

cxptr cx_realloc | ( | cxptr | memory,
|  | cxsize | nbytes )

Change the size of a memory block.

Parameters

  memory | Number of atomic elements.
  nbytes | New 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().