Memory Managment

Convenient and safe memory allocation macros. More...

Macros
#define	csnip_mem_Alloc(nMember, ptr, err)
	Allocate a member or an array of members. More...
#define	csnip_mem_Alloc0(nMember, ptr, err)
	Allocate and zero-initialize an array. More...
#define	csnip_mem_AlignedAlloc(nMember, nAlign, ptr, err)    csnip_mem__AlignedAlloc((nMember), (nAlign), (ptr), (err))
	Aligned memory allocation. More...
#define	csnip_mem_Realloc(nMember, ptr, err)    csnip_mem__Realloc((nMember), (ptr), (err), csnip__p)
	Reallocate an array. More...
#define	csnip_mem_Free(ptr)
	Free memory. More...
#define	csnip_mem_AlignedFree(ptr)
	Free aligned memory. More...

Functions
void *	csnip_mem_aligned_alloc (size_t nAlign, size_t nSize, int *err)
	Allocate aligned memory. More...
void	csnip_mem_aligned_free (void *mem)
	Free aligned memory. More...

Detailed Description

These macros provide an improved interface to the malloc() / free() libc functions. They can be intermixed with conventional malloc() / free() calls, e.g. memory allocated with csnip_mem_Alloc() can be freed with free(), etc. Improvements over the conventional malloc interface include:

1. Automatic element size computation, the frequently used sizeof construct is builtin, including overflow checks.
2. Works also in C++ without cast.
3. Better error handling in particular for csnip_mem_Realloc().

Macro Definition Documentation

csnip_mem_AlignedAlloc

#define csnip_mem_AlignedAlloc	(		nMember,
			nAlign,
			ptr,
			err
	)		csnip_mem__AlignedAlloc((nMember), (nAlign), (ptr), (err))

This macro is similar to csnip_mem_Alloc, except that the memory alloc is aligned to nAlign bytes, which must be a power of two. Unlike C11's aligned_alloc, there is no requirement that the size of the requested memory block must be a multiple of the alignment. This is convenient, since it's frequently a nuisance to ensure this requirement is satisfied.

csnip_mem_AlignedFree

#define csnip_mem_AlignedFree

(

ptr

)

Frees the memory pointed-to by ptr. This is for memory that was alloc allocated with an aligned allocator. On POSIX systems this is equivalent to csnip_mem_Free(), but some systems, such as Windows, require a special deallocator to be used for aligned allocations.

csnip_mem_Alloc

#define csnip_mem_Alloc	(		nMember,
			ptr,
			err
	)

Allocate memory for the target type of ptr; nMember members will be allocated; the allocated pointer is written into the ptr member.

This function uses malloc() under the hood, so it can be freed with either libc's free() or csnip_mem_Free().

Parameters

nMember	Number of members in the array to alocate for; use 1 to allocate a single member.
ptr	The lvalue to assign to. This must be a pointer type, and the per-object size allocated is sizeof(*ptr).
err	Error return; accepts the special _ and error_ignore values, as explained in csnip_err_Raise().

csnip_mem_Alloc0

#define csnip_mem_Alloc0	(		nMember,
			ptr,
			err
	)

This is similar to csnip_mem_Alloc, except that additionally the allocated memory is zero-initialized.

csnip_mem_Free

#define csnip_mem_Free

(

ptr

)

Frees the memory pointed-to by ptr. The pointer is cleared afterward. The memory must have been allocated with one of the C allocator functions malloc(), calloc(), realloc() or one of csnip's mem_Alloc() or similar functions. As a special exception, for aligned allocations using csnip_mem_aligned_alloc() or csnip_mem_AlignedAlloc(), portable code should use csnip_mem_AlignedFree() instead.

csnip_mem_Realloc

#define csnip_mem_Realloc	(		nMember,
			ptr,
			err
	)		csnip_mem__Realloc((nMember), (ptr), (err), csnip__p)

Csnip's version of realloc(). If the reallocation fails, ptr remains unchanged.

Parameters

[in]	nMember	New array size
[in,out]	ptr	Pointer containing the original value upon the call, and the new value after the call
[in,out]	err	error return

Function Documentation

csnip_mem_aligned_alloc()

void* csnip_mem_aligned_alloc	(	size_t	nAlign,
		size_t	nSize,
		int *	err
	)

The aligned allocator is similar to C11's aligned_alloc, but does not have the requirement that nSize be a multiple of nAlign.

csnip_mem_aligned_free()

void csnip_mem_aligned_free

(

void *

mem

)

Free memory that was allocated with csnip_mem_aligned_alloc() or csnip_mem_AlignedAlloc(). On many systems this is equivalent to free() or csnip's wrappers thereof, but e.g., Windows requires special function calls to free aligned memory.