Reference¶
Useful Defines¶
The C-Craft mem module defines some useful macros.
-
FALSE¶
-
TRUE¶
-
ARRAYLEN(x)¶
The number of elements in an array ‘x’
-
MAX_ALLOCATION¶
The maximum number of bytes allowed to be allocated.
Types¶
-
typedef struct mem_scope *MEM_SCOPE¶
A memory scope. Memory is always allocated within a scope, and there may be many scopes.
-
typedef struct bin *BIN¶
A block of binary data.
Scoped Memory¶
A memory scope is created with sm_create(), and released with sm_free(). Within a scope memory allocation is very similar to standard UNIX memory allocation, except free() is not necessary since all memory in a scope is released when the scope is released.
-
void *sm_alloc(MEM_SCOPE scope, size_t size)¶
Allocate memory within a scoped block.
Remark
Memory is aligned to size_t boundary. Unlike malloc() memory is initialised to zero. If you do not want this behaviour, use sm_ualloc() instead.
No single allocation may successfully exceed MAX_ALLOCATION bytes. An attempt to do so will result in a fatal exit, preceded by an assert in debug mode.
See also
sm_create(), sm_ualloc()
- Parameters:
scope – The handle to the scoped context, returned by sm_create().
size – The size in bytes to be allocated to the object.
- Returns:
A pointer to the allocated memory.
-
void sm_allocator(void *(*malloc)(size_t bytes), void (*free)())¶
Set a custom allocator, replacing malloc() and free().
Remark
Scoped memory uses malloc() and free() by default to allocate memory for scopes. You may specify a custom implementation of these two functions instead using this method.
- Parameters:
malloc – A pointer to the custom malloc() function.
free – A pointer to the custom free() function.
-
void *sm_calloc(MEM_SCOPE scope, size_t nelems, size_t size)¶
Allocates memory for an array of objects and initialises all elements to zero.
Remark
Memory is aligned to element size boundary.
No single allocation may successfully exceed MAX_ALLOCATION bytes. An attempt to do so will result in a fatal exit, preceded by an assert in debug mode.
- Parameters:
scope – The handle to the scoped context, returned by sm_create().
nelems – The number of elements in the array.
size – The size in bytes of a single element in the array.
- Returns:
A pointer to the allocated memory.
-
MEM_SCOPE sm_create(size_t blk_size)¶
Create a scoped memory block.
Remark
The value returned is the context of the created memory scope and is needed for further operations on it.
- Parameters:
blk_size – The initial size to allocate. The memory expands to allocation requests anyway. Use 0 to use default size of 1k * sizeof(size_t) bytes.
- Returns:
A MEM_SCOPE for use in subsequent memory operations.
-
void sm_free(MEM_SCOPE scope)¶
Releases all memory allocated with the scope.
Remark
The entire memory scope is released with this. All allocations within the scope should be considered no longer valid.
- Parameters:
scope – The handle to the scoped context, returned by sm_create().
-
void *sm_realloc(MEM_SCOPE scope, void *mem, size_t size)¶
Reallocates the block to a new size.
Remark
This function is provided for compatibility only. The implementation will always create a new block and copy ‘new_size’ bytes of data to it. The old data block will remain, though that should not be relied on. In scoped memory there is no concept of free other than the entire scope. Existing blocks are not even tracked, for performance reasons. Consequently this function is not really considered appropriate for scoped memory. If reallocation is a major concern more suitable memory functions should be sought, or standard library functions used.
No single allocation may successfully exceed MAX_ALLOCATION bytes. An attempt to do so will result in a fatal exit, preceded by an assert in debug mode.
- Parameters:
scope – The handle to the scoped context, returned by sm_create().
mem – The allocated item to be resized.
size – The new required size.
- Returns:
A pointer to the resized memory.
-
char *sm_strdup(MEM_SCOPE scope, const char *s)¶
Allocates space for a string and copies the contents to it. A duplicated string.
Remark
Memory returned is not aligned to any specific boundary. The string to copy must be null terminated. Passing a string that is not null terminated will result in undefined behaviour. Passing a NULL string will result in a NULL string being returned.
No single allocation may successfully exceed MAX_ALLOCATION bytes. An attempt to do so will result in a fatal exit, preceded by an assert in debug mode.
- Parameters:
scope – The handle to the scoped context, returned by sm_create().
s – The string to copy.
- Returns:
A pointer to the new string.
-
void *sm_ualloc(MEM_SCOPE scope, size_t size)¶
Allocate uninitialised memory within a scoped block.
Remark
Memory is aligned to size_t boundary. Memory is not specifically initialised to zero. If you require initialised memory use sm_alloc() instead.
No single allocation may successfully exceed MAX_ALLOCATION bytes. An attempt to do so will result in a fatal exit, preceded by an assert in debug mode.
See also
sm_alloc(), sm_create().
- Parameters:
scope – The handle to the scoped context, returned by sm_create().
size – The size in bytes to be allocated to the object.
- Returns:
A pointer to the allocated memory.
Binary Data¶
-
BIN bin_create(MEM_SCOPE mem, unsigned char *data, size_t len)¶
Create a binary data block.
Remark
There is no requirement to use the same memory scope that was used for allocation of the data. However, it is good practice to do so. BIN is only useful for returning a binary block from a function, including the length.
- Parameters:
mem – A memory scope to own the memory.
data – The binary data. It must already be allocated.
len – The length of the binary data block in bytes.
- Returns:
A binary data block.
-
unsigned char *bin_data(BIN bin)¶
Get the binary data from a binary data block.
- Parameters:
bin – The binary data block.
- Returns:
The binary data.
