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.
- Return
- A pointer to the allocated memory.
- 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
- 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.
-
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.
- Return
- A pointer to the allocated memory.
- 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.
-
MEM_SCOPE
sm_create(size_t blk_size)¶ Create a scoped memory block.
- Return
- A MEM_SCOPE for use in subsequent memory operations.
- 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.
-
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.
- Return
- A pointer to the resized memory.
- 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.
-
char *
sm_strdup(MEM_SCOPE scope, const char *s)¶ Allocates space for a string and copies the contents to it. A duplicated string.
- Return
- A pointer to the new 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.
-
void *
sm_ualloc(MEM_SCOPE scope, size_t size)¶ Allocate uninitialised memory within a scoped block.
- Return
- A pointer to the allocated memory.
- 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
- 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.
Binary Data¶
-
BIN
bin_create(MEM_SCOPE mem, unsigned char *data, size_t len)¶ Create a binary data block.
- Return
- 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.
-
unsigned char *
bin_data(BIN bin)¶ Get the binary data from a binary data block.
- Return
- The binary data.
- Parameters
bin: The binary data block.
