vl_memory.c File Reference

#include "vl_memory.h"
#include <stdlib.h>
#include <string.h>

Include dependency graph for vl_memory.c:

Macros
#define	VL_MEMORY_ORIGIN_INLINE(headerPtr)   (void*)(((vl_uint8_t*)(headerPtr) - ((headerPtr)->headOffset)))
	Returns the original result of the malloc system call.
#define	VL_MEMORY_HEADER_INLINE(memPtr)   ((vl_memory_header*)(memPtr) - 1)
	Returns a pointer to the specified block of memory Assumes header is stored immediately adjacent to the memory.
#define	vl_MemSortSwap(temp, a, b, memSize)

Functions
vl_memory *	vlMemAlloc (vl_memsize_t allocSize)
	Attempts to allocate a block of memory.
vl_memory *	vlMemAllocAligned (vl_memsize_t size, vl_uint_t align)
	Allocates a block of memory with an alignment.
vl_memory *	vlMemRealloc (vl_memory *mem, vl_memsize_t allocSize)
	Reallocates the specified block of memory to hold the specified total number of bytes.
vl_memory *	vlMemClone (vl_memory *mem)
	Clones the specified block of memory, returning a pointer to its new clone.
vl_int_t	vl_MemSortPartition (vl_usmall_t *buffer, void *pivot, void *swap, vl_int_t low, vl_int_t high, vl_memsize_t elementSize, vl_compare_function comparator)
void	vl_MemSortQuicksort (vl_int_t *stack, void *buffer, void *pivot, void *swap, vl_memsize_t elementSize, vl_dsidx_t numElements, vl_compare_function comparator)
void	vlMemSort (void *buffer, vl_memsize_t elementSize, vl_dsidx_t numElements, vl_compare_function comparator)
	Sorts the specified buffer in-place according to the specified element and comparator function.
void	vlMemCopyStride (const void *src, vl_dsoffs_t srcStride, void *dest, vl_dsoffs_t dstStride, vl_memsize_t elementSize, vl_dsidx_t numElements)
	Copies data from one buffer to another, with a stride applied to both.
void	vlMemReverseSubArraysStride (void *src, vl_dsoffs_t srcStride, vl_memsize_t elementSize, vl_dsidx_t numElements)
	Reverses the bytes in a series of elements of a defined length and stride between them.
vl_uint_t	vlMemAlignment (vl_memory *mem)
	Returns the alignment of the specified block of memory.
vl_memsize_t	vlMemSize (vl_memory *mem)
	Returns the size (in total number of bytes) of the specified block of vl_memory.
void	vlMemFree (vl_memory *mem)
	Frees the specified block of memory.

Macro Definition Documentation

VL_MEMORY_HEADER_INLINE

#define VL_MEMORY_HEADER_INLINE

(

memPtr

)

((vl_memory_header*)(memPtr) - 1)

Returns a pointer to the specified block of memory Assumes header is stored immediately adjacent to the memory.

VL_MEMORY_ORIGIN_INLINE

#define VL_MEMORY_ORIGIN_INLINE

(

headerPtr

)

(void*)(((vl_uint8_t*)(headerPtr) - ((headerPtr)->headOffset)))

Returns the original result of the malloc system call.

headerPtr pointer to the memory header of an allocation

Returns

pointer to buffer origin

vl_MemSortSwap

#define vl_MemSortSwap	(		temp,
			a,
			b,
			memSize
	)

Value:

    memcpy(temp, a, memSize);                                                                                          \
    memcpy(a, b, memSize);                                                                                             \
    memcpy(b, temp, memSize)

Function Documentation

vl_MemSortPartition()

vl_int_t vl_MemSortPartition	(	vl_usmall_t *	buffer,
		void *	pivot,
		void *	swap,
		vl_int_t	low,
		vl_int_t	high,
		vl_memsize_t	elementSize,
		vl_compare_function	comparator
	)

Here is the caller graph for this function:

vl_MemSortQuicksort()

void vl_MemSortQuicksort	(	vl_int_t *	stack,
		void *	buffer,
		void *	pivot,
		void *	swap,
		vl_memsize_t	elementSize,
		vl_dsidx_t	numElements,
		vl_compare_function	comparator
	)

Here is the call graph for this function:

Here is the caller graph for this function:

vlMemAlignment()

vl_uint_t vlMemAlignment

(

vl_memory *

mem

)

Returns the alignment of the specified block of memory.

Minimum alignment is defined as VL_DEFAULT_MEMORY_ALIGN, or the largest available word size.

Contract

• Ownership: Does not transfer or affect ownership.
• Lifetime: The mem pointer must be valid at the time of the call.
• Thread Safety: Thread-safe for concurrent reads of the same memory block's metadata.
• Nullability: Returns VL_DEFAULT_MEMORY_ALIGN if mem is NULL.
• Error Conditions: None.
• Undefined Behavior: Passing a pointer not originally allocated by vlMemAlloc or vlMemAllocAligned.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns the byte alignment of the user-data portion of the allocation.

Parameters

mem	pointer to memory block

Returns

alignment

Here is the caller graph for this function:

vlMemAlloc()

vl_memory * vlMemAlloc

(

vl_memsize_t

allocSize

)

Attempts to allocate a block of memory.

Returns NULL on failure.

Contract

• Ownership: The caller owns the returned memory and is responsible for calling vlMemFree.
• Lifetime: The memory block is valid until it is passed to vlMemFree or vlMemRealloc.
• Thread Safety: This function is thread-safe as it uses the system malloc.
• Nullability: Returns NULL on allocation failure. allocSize is not checked for zero, but malloc(0) is implementation-defined.
• Error Conditions: Returns NULL if the underlying malloc fails.
• Undefined Behavior: Using the returned pointer after it has been freed, or passing it to the standard free function instead of vlMemFree.
• Memory Allocation Expectations: Allocates allocSize plus the size of an internal header (vl_memory_header).
• Return-value Semantics: Returns a pointer to the start of the user-data portion of the allocation, or NULL if allocation failed.

Parameters

allocSize

size of the allocation, in bytes.

Returns

pointer to allocated block, or NULL.

Here is the caller graph for this function:

vlMemAllocAligned()

vl_memory * vlMemAllocAligned	(	vl_memsize_t	allocSize,
		vl_uint_t	align
	)

Allocates a block of memory with an alignment.

Guarantees that the returned pointer will have a value that is a multiple of the specified alignment.

The VL_MEMORY_PAD_UP macro may be used to ensure that the actual length of the memory block is also a multiple of the alignment.

Contract

• Ownership: The caller owns the returned memory and is responsible for calling vlMemFree.
• Lifetime: The memory block is valid until it is passed to vlMemFree or vlMemRealloc.
• Thread Safety: This function is thread-safe as it uses the system malloc.
• Nullability: Returns NULL on allocation failure.
• Error Conditions: Returns NULL if the underlying malloc fails.
• Undefined Behavior: align is not a power of 2.
• Memory Allocation Expectations: Allocates allocSize + align + sizeof(vl_memory_header) to guarantee alignment.
• Return-value Semantics: Returns a pointer to the aligned start of the user-data portion of the allocation, or NULL if allocation failed.

See also

VL_MEMORY_PAD_UP

Parameters

allocSize	size of the allocation, in bytes.
align

Returns

pointer to the aligned block

Here is the call graph for this function:

Here is the caller graph for this function:

vlMemClone()

vl_memory * vlMemClone

(

vl_memory *

mem

)

Clones the specified block of memory, returning a pointer to its new clone.

Returns NULL on failure.

If the source block has an alignment, the result will also have an alignment.

Contract

• Ownership: The caller owns the returned memory and is responsible for calling vlMemFree.
• Lifetime: The cloned memory block is valid until it is passed to vlMemFree or vlMemRealloc.
• Thread Safety: Safe to call concurrently on different source blocks. Not thread-safe if the source block is being modified by another thread.
• Nullability: Returns NULL if mem is NULL or if allocation fails.
• Error Conditions: Returns NULL on allocation failure.
• Undefined Behavior: Passing a pointer not originally allocated by vlMemAlloc or vlMemAllocAligned.
• Memory Allocation Expectations: Allocates a new block of memory with the same size and alignment as the source block.
• Return-value Semantics: Returns a pointer to the start of the user-data portion of the cloned allocation, or NULL if cloning failed.

Parameters

mem

pointer

Returns

cloned memory pointer

Here is the call graph for this function:

Here is the caller graph for this function:

vlMemCopyStride()

void vlMemCopyStride	(	const void *	src,
		vl_dsoffs_t	srcStride,
		void *	dest,
		vl_dsoffs_t	dstStride,
		vl_memsize_t	elementSize,
		vl_dsidx_t	numElements
	)

Copies data from one buffer to another, with a stride applied to both.

Stride is the amount of space (in bytes) between each element.

Contract

• Ownership: Does not transfer or affect ownership of the buffers.
• Lifetime: Both src and dest buffers must remain valid for the duration of the copy.
• Thread Safety: Not thread-safe if multiple threads access src or dest concurrently where at least one thread is writing.
• Nullability: src and dest should not be NULL.
• Error Conditions: None.
• Undefined Behavior: Overlapping memory regions when srcStride or dstStride allow it, as memcpy is used for individual elements.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Parameters

src	memory block pointer
srcStride	total number of bytes between each element in "src"
dest	memory block pointer
dstStride	total number of bytes between each element in "dest"
elementSize	total number of bytes wide of each element
numElements	total number of elements

Complexity of O(n) linear.

vlMemFree()

void vlMemFree

(

vl_memory *

mem

)

Frees the specified block of memory.

Contract

• Ownership: Releases ownership of the memory block.
• Lifetime: The memory block and its associated pointer become invalid after this call.
• Thread Safety: This function is thread-safe as it uses the system free.
• Nullability: Safe to call with NULL (no-op).
• Error Conditions: None.
• Undefined Behavior: Passing a pointer not originally allocated by vlMemAlloc or vlMemAllocAligned, or double-freeing the same pointer.
• Memory Allocation Expectations: Deallocates the user-data portion and the internal header.
• Return-value Semantics: None (void).

Parameters

mem	pointer to block.

Here is the caller graph for this function:

vlMemRealloc()

vl_memory * vlMemRealloc	(	vl_memory *	mem,
		vl_memsize_t	allocSize
	)

Reallocates the specified block of memory to hold the specified total number of bytes.

If the specified memory block is explicitly aligned, its alignment is preserved.

Contract

• Ownership: The caller maintains ownership of the returned pointer. The original mem pointer may become invalid upon success.
• Lifetime: The new memory block is valid until it is passed to vlMemFree or another vlMemRealloc.
• Thread Safety: This function is thread-safe as it uses the system realloc.
• Nullability: If mem is NULL, this function behaves like vlMemAlloc. If allocSize is zero, behavior is realloc-dependent.
• Error Conditions: Returns NULL if the underlying realloc fails. In this case, the original mem pointer remains valid and its memory is not leaked.
• Undefined Behavior: Passing a pointer not originally allocated by vlMemAlloc or vlMemAllocAligned.
• Memory Allocation Expectations: Reallocates the underlying block to the new size plus internal header size. Preserves existing alignment if any.
• Return-value Semantics: Returns a pointer to the new user-data portion of the allocation, or NULL if reallocation failed.

Parameters

mem	pointer to block
allocSize	new size of the allocation.

Returns

pointer to reallocated memory

Here is the call graph for this function:

Here is the caller graph for this function:

vlMemReverseSubArraysStride()

void vlMemReverseSubArraysStride	(	void *	src,
		vl_dsoffs_t	srcStride,
		vl_memsize_t	elementSize,
		vl_dsidx_t	numElements
	)

Reverses the bytes in a series of elements of a defined length and stride between them.

This function operates on a sequence of elements (or sub-arrays) within a memory block, where each element is separated by a defined stride. It reverses the bytes of each individual element but does not alter the overall structure of the memory. The elements are processed sequentially, one by one, with each element's bytes reversed in-place.

This is useful when you need to reverse the bytes in each element of a collection of data structures that are tightly packed but may have a varying stride (i.e., distance between consecutive elements in memory).

Example: Suppose we have an array of 32-bit integers, each 4 bytes, with a stride of 8 bytes:

Input (elements of size 4 bytes, stride of 8 bytes): [0xAABBCCDD, 0x11223344, 0x55667788] Memory block: [0xAABBCCDD, pad, 0x11223344, pad, 0x55667788, pad] (Where 'pad' represents the unused memory between elements, i.e., stride.)

Output (each element reversed): [0xDDCCBBAA, 0x44332211, 0x88776655] Memory block: [0xDDCCBBAA, pad, 0x44332211, pad, 0x88776655, pad]

The bytes within each element are reversed, but the stride between elements is respected.

Contract

• Ownership: Does not transfer or affect ownership of src.
• Lifetime: The src buffer must remain valid for the duration of the operation.
• Thread Safety: Not thread-safe if multiple threads access src concurrently.
• Nullability: src should not be NULL.
• Error Conditions: None.
• Undefined Behavior: Invalid srcStride or elementSize that leads to out-of-bounds memory access.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Parameters

src	memory block pointer. The base address of the memory containing the elements to be reversed.
srcStride	total number of bytes between each sub-array (or element). This defines the gap between consecutive elements.
elementSize	size of each sub-array (or element) in bytes. This is the number of bytes that constitute one element.
numElements	total number of sub-arrays (or elements). This is the number of individual elements to process.

Complexity of O(n) linear.

vlMemSize()

vl_memsize_t vlMemSize

(

vl_memory *

mem

)

Returns the size (in total number of bytes) of the specified block of vl_memory.

Contract

• Ownership: Does not transfer or affect ownership.
• Lifetime: The mem pointer must be valid at the time of the call.
• Thread Safety: Thread-safe for concurrent reads of the same memory block's metadata.
• Nullability: Returns 0 if mem is NULL.
• Error Conditions: None.
• Undefined Behavior: Passing a pointer not originally allocated by vlMemAlloc or vlMemAllocAligned.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns the size of the user-data portion of the allocation in bytes.

mem pointer to memory block

Returns

size of the specified memory block, in bytes.

Here is the caller graph for this function:

vlMemSort()

void vlMemSort	(	void *	buffer,
		vl_memsize_t	elementSize,
		vl_dsidx_t	numElements,
		vl_compare_function	comparator
	)

Sorts the specified buffer in-place according to the specified element and comparator function.

This function implements an iterative Quicksort.

Contract

• Ownership: Does not transfer or affect ownership of the buffer.
• Lifetime: The buffer must remain valid for the duration of the sort.
• Thread Safety: Not thread-safe if multiple threads access the same buffer concurrently.
• Nullability: buffer must not be NULL. comparator must not be NULL.
• Error Conditions: If internal temporary memory allocation fails, the function returns without sorting the buffer.
• Undefined Behavior: Passing a NULL buffer or comparator. Overlapping memory regions during sort operations.
• Memory Allocation Expectations: Allocates temporary scratch space on the heap proportional to numElements and elementSize.
• Return-value Semantics: None (void).

Parameters

buffer
elementSize
numElements
comparator

Complexity of O(n log(n)) (space complexity of O(n)).

Here is the call graph for this function: