6.3.3 Memory-allocation functions

The coNCePTuaL run-time library provides its own wrappers for malloc(), free(), realloc(), and strdup() as well as a specialized malloc() designed specifically for allocating message buffers. The wrappers’ “value added” is that they support the explicit data alignments needed by ALIGNED messages (see Message alignment) and that they automatically call ncptl_fatal() on failure, so the return value does not need to be checked for NULL.

Function: void * ncptl_malloc (ncptl_int numbytes, ncptl_int alignment)

Allocate numbytes bytes of memory aligned to an alignment-byte boundary. If alignment is ‘0’, ncptl_malloc() will use whatever alignment is “natural” for the underlying architecture. ncptl_malloc() will automatically call ncptl_fatal() if memory allocation fails. Therefore, unlike malloc(), there is no need to check the return value for NULL.

Function: void * ncptl_malloc_misaligned (ncptl_int numbytes, ncptl_int misalignment)

Allocate numbytes bytes of memory from the heap aligned misalignment bytes past a page boundary. If alignment is ‘0’, ncptl_malloc_misaligned() will return page-aligned memory. ncptl_malloc_misaligned() will automatically call ncptl_fatal() if memory allocation fails. Therefore, unlike malloc(), there is no need to check the return value for NULL.

Function: void ncptl_free (void *pointer)

Free memory previously allocated by ncptl_malloc() . It is an error to pass ncptl_free() memory not allocated by ncptl_malloc() .

Function: void * ncptl_realloc (void *pointer, ncptl_int numbytes, ncptl_int alignment)

Given a pointer returned by ncptl_malloc(), change its size to numbytes and byte-alignment to alignment without altering the contents (except for truncation in the case of a smaller target size). If alignment is ‘0’, ncptl_realloc() will use whatever alignment is “natural” for the underlying architecture. ncptl_realloc() will automatically call ncptl_fatal() if memory allocation fails. Therefore, unlike realloc(), there is no need to check the return value for NULL.

Function: char * ncptl_strdup (const char *string)

ncptl_strdup() copies a string as does the standard C strdup() function. However, ncptl_strdup() uses ncptl_malloc() instead of malloc() to allocate memory for the copy, which must therefore be deallocated using ncptl_free().

Function: void * ncptl_malloc_message (ncptl_int numbytes, ncptl_int alignment, ncptl_int outstanding, int misaligned)

Allocate numbytes bytes of memory from the heap either aligned on an alignment-byte boundary (if misaligned is ‘0’) or alignment bytes past a page boundary (if misaligned is ‘1’). All calls with the same value of outstanding will share a buffer. ncptl_malloc_message() is intended to be used in two passes. The first time the function is called on a set of messages it merely determines how much memory to allocate. The second time, it returns valid memory buffers. Note that the returned pointer can be neither free()d nor ncptl_free() d.

Function: void * ncptl_get_message_buffer (ncptl_int buffernum)

Return a pointer to a message buffer previously allocated (and finalized) by ncptl_malloc_message(). The buffernum argument to ncptl_get_message_buffer(), which corresponds to the outstanding argument to ncptl_malloc_message(), specifies the number of the buffer to return. ncptl_get_message_buffer() returns NULL if buffer buffernum is either unallocated or uninitialized.