#include <malloc.h>
#include "vl_compare.h"
#include "vl_numtypes.h"

Include dependency graph for vl_memory.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	VL_KB(x) ((vl_memsize_t)(x) << 10)

#define	VL_MB(x) ((vl_memsize_t)(x) << 20)

#define	VL_DEFAULT_MEMORY_SIZE VL_KB(1)
	Default 1kb allocation size.

#define	VL_ALIGNOF(T) __alignof__(T)

#define	VL_DEFAULT_MEMORY_ALIGN VL_ALIGNOF(vl_ularge_t)
	Default memory alignment. Defaults to maximum system word size.

#define	VL_MEMORY_PAD_UP(len, pad) (((len) + (pad) - 1) & ~((pad) - 1))
	Calculate the next offset such that it is a multiple of an alignment.

#define	VL_ALIGN_HINT(x)
	Structure alignment hint.

#define	vlMemAllocType(element_type) ((element_type*)vlMemAllocAligned(sizeof(element_type), VL_ALIGNOF(element_type)))
	Type-safe heap allocation for a single element.

#define	vlMemAllocTypeArray(element_type, count) ((element_type)vlMemAllocAligned(sizeof(element_type) (count), VL_ALIGNOF(element_type)))
	Type-safe heap allocation for an array of elements.

#define	vlMemAllocStackType(element_type) ((element_type*)vlMemAllocStackAligned(sizeof(element_type), VL_ALIGNOF(element_type)))
	Type-safe stack allocation for a single element.

#define	vlMemAllocStackTypeArray(element_type, count) ((element_type)vlMemAllocStackAligned((count) sizeof(element_type), VL_ALIGNOF(element_type)))
	Type-safe stack allocation for an array of elements.

#define	vlMemReverse(src, numBytes) vlMemReverseSubArraysStride(src, 1, numBytes, 1)
	Reverses the order of bytes in the specified block of memory.

#define	vlMemReverseSubArrays(src, elementSize, numElements) vlMemReverseSubArraysStride(src, elementSize, elementSize, numElements)
	Reverses the bytes in a tightly packed series of elements of a defined length.

Typedefs
typedef VL_MEMORY_T	vl_memory

typedef VL_MEMORY_T	vl_transient

Functions
VL_API vl_memory *	vlMemAlloc (vl_memsize_t allocSize)
	Attempts to allocate a block of memory.

VL_API 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_API vl_memory *	vlMemAllocAligned (vl_memsize_t allocSize, vl_uint_t align)
	Allocates a block of memory with an alignment.

vl_transient *	vlMemAllocStack (vl_memsize_t allocSize)
	Allocate memory on the stack (automatic storage).

vl_transient *	vlMemAllocStackAligned (vl_memsize_t allocSize, vl_uint16_t align)
	Allocate aligned memory on the stack (automatic storage).

VL_API vl_memory *	vlMemClone (vl_memory *mem)
	Clones the specified block of memory, returning a pointer to its new clone.

VL_API vl_memsize_t	vlMemSize (vl_memory *mem)
	Returns the size (in total number of bytes) of the specified block of vl_memory.

VL_API vl_uint_t	vlMemAlignment (vl_memory *mem)
	Returns the alignment of the specified block of memory.

VL_API 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.

VL_API 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.

VL_API 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_API void	vlMemFree (vl_memory *mem)
	Frees the specified block of memory.

Macro Definition Documentation

◆ VL_ALIGN_HINT

#define VL_ALIGN_HINT ( x )

Structure alignment hint.

Hints to the compiler that the declared structure should be aligned to the specified value.

◆ VL_ALIGNOF

#define VL_ALIGNOF ( T ) __alignof__(T)

◆ VL_DEFAULT_MEMORY_ALIGN

#define VL_DEFAULT_MEMORY_ALIGN VL_ALIGNOF(vl_ularge_t)

Default memory alignment. Defaults to maximum system word size.

◆ VL_DEFAULT_MEMORY_SIZE

#define VL_DEFAULT_MEMORY_SIZE VL_KB(1)

Default 1kb allocation size.

◆ VL_KB

#define VL_KB ( x ) ((vl_memsize_t)(x) << 10)

Convenience macro to define blocks of memory which contain a multiple of X-many kilobytes.

Parameters

x	total kilobytes.

◆ VL_MB

#define VL_MB ( x ) ((vl_memsize_t)(x) << 20)

Convenience macro to define blocks of memory which contain a multiple of X-many megabytes.

Parameters

x	total megabytes.

◆ VL_MEMORY_PAD_UP

#define VL_MEMORY_PAD_UP	(	len,
		pad
	)	(((len) + (pad) - 1) & ~((pad) - 1))

Calculate the next offset such that it is a multiple of an alignment.

This will return len when already a multiple of pad.

Warning: pad must be a power of 2.

len size of the memory block

pad bytes to pad it to.

Returns: len

◆ vlMemAllocStackType

#define vlMemAllocStackType ( element_type ) ((element_type*)vlMemAllocStackAligned(sizeof(element_type), VL_ALIGNOF(element_type)))

Type-safe stack allocation for a single element.

Allocates memory on the stack for a single object of the specified type. The allocated memory is automatically aligned to the type's natural alignment requirement and automatically freed when the enclosing scope exits.

This macro combines type safety with automatic alignment, ensuring the allocation is properly sized and aligned for the type without manual alignment calculations.

Example

struct point {
    float x, y, z;
};
 
struct point *p = vlMemAllocStackType(struct point);
p->x = 1.0f;
p->y = 2.0f;
p->z = 3.0f;
// p is automatically freed when scope exits

When to Use

Temporary struct/object instances within a function
When you need both type safety and proper alignment
Quick prototyping or temporary calculations
The type's size is small and known at compile time

Parameters

element_type The type to allocate (e.g., int, struct foo, MyType)

Returns: Pointer to allocated and aligned stack memory of the specified type, automatically freed when scope exits

Note: No NULL return is possible (stack overflow causes a crash instead); Stack memory is NOT managed by vlMemFree(); it's automatic; Alignment is automatically derived from the type using VL_ALIGNOF()

See also: vlMemAllocStackTypeArray, vlMemAllocStackAligned, vlMemAllocType

◆ vlMemAllocStackTypeArray

#define vlMemAllocStackTypeArray	(	element_type,
		count
	)	((element_type)vlMemAllocStackAligned((count) sizeof(element_type), VL_ALIGNOF(element_type)))

Type-safe stack allocation for an array of elements.

Allocates memory on the stack for an array of the specified type and count. The allocated memory is automatically aligned to the type's natural alignment requirement and automatically freed when the enclosing scope exits.

This macro combines type safety, proper sizing, and automatic alignment, eliminating manual calculations and reducing errors.

Example

int *numbers = vlMemAllocStackTypeArray(int, 50);
for (int i = 0; i < 50; i++) {
    numbers[i] = i * 2;
}
// numbers is automatically freed when scope exits

When to Use

Temporary arrays within a function scope
Known, small array sizes (typically < 1 MB of stack)
Quick prototyping or intermediate computations
When automatic alignment and type safety are desired

Parameters

element_type	The element type in the array (e.g., `int`, `struct foo`)
count	Number of elements to allocate space for

Returns: Pointer to allocated and aligned stack array of the specified type and count, automatically freed when scope exits

Note: No NULL return is possible (stack overflow causes a crash instead); Stack memory is NOT managed by vlMemFree(); it's automatic; Alignment is automatically derived from the element type using VL_ALIGNOF()

Warning: Verify that count > 0 to avoid allocating zero bytes; behavior is undefined for negative counts.

See also: vlMemAllocStackType, vlMemAllocTypeArray, vlMemAllocStackAligned

◆ vlMemAllocType

#define vlMemAllocType ( element_type ) ((element_type*)vlMemAllocAligned(sizeof(element_type), VL_ALIGNOF(element_type)))

Type-safe heap allocation for a single element.

Allocates memory on the heap for a single object of the specified type. The allocated memory is properly sized and return type is cast to the desired type.

This macro provides a convenient, type-safe alternative to manual vlMemAlloc(sizeof(type)) calls, reducing the risk of size mismatches.

Example

struct my_data {
    int x;
    float y;
};
 
struct my_data *obj = vlMemAllocType(struct my_data);
if (obj != NULL) {
    obj->x = 42;
    vlMemFree((vl_memory*)obj);
}

Parameters

element_type The type to allocate (e.g., int, struct foo, MyType)

Returns: Pointer to allocated and zero-initialized memory of the specified type, or NULL on allocation failure.

Note: The returned pointer is managed with vlMemFree() like any heap allocation.; Memory alignment follows the alignment of the specified element type.

See also: vlMemAllocTypeArray, vlMemAlloc, vlMemFree

◆ vlMemAllocTypeArray

#define vlMemAllocTypeArray	(	element_type,
		count
	)	((element_type)vlMemAllocAligned(sizeof(element_type) (count), VL_ALIGNOF(element_type)))

Type-safe heap allocation for an array of elements.

Allocates memory on the heap for an array of the specified type and count. The allocated memory is properly sized and the return type is cast to the desired type.

This macro provides a convenient, type-safe alternative to manual vlMemAlloc(count * sizeof(type)) calls, eliminating manual size calculations and reducing overflow risks.

Example

int *numbers = vlMemAllocTypeArray(int, 100);
if (numbers != NULL) {
    numbers[0] = 42;
    numbers[99] = -1;
    vlMemFree((vl_memory*)numbers);
}

Parameters

element_type	The element type in the array (e.g., `int`, `struct foo`)
count	Number of elements to allocate space for

Returns: Pointer to allocated and zero-initialized array of the specified type and count, or NULL on allocation failure.

Note: The returned pointer is managed with vlMemFree() like any heap allocation.; Memory alignment follows the alignment of the specified element type.

Warning: Verify that count > 0 to avoid allocating zero bytes; behavior is undefined for negative counts.

See also: vlMemAllocType, vlMemAlloc, vlMemFree

◆ vlMemReverse

#define vlMemReverse	(	src,
		numBytes
	)	vlMemReverseSubArraysStride(src, 1, numBytes, 1)

Reverses the order of bytes in the specified block of memory.

This is to be used on tightly packed sequences of bytes. Attempting to blindly reverse the memory of a structure can result in unexpected results due to padding inserted by the compiler.

Assuming the input is of the sequence [0x0A, 0x0B, 0x0C, 0x0D, 0x0E], the expected output would be [0x0E, 0x0D, 0x0C, 0x0B, 0x0A].

See also: vlMemReverseSubArraysStride

Parameters

src	memory block pointer
numBytes	total number of bytes to reverse

Complexity of O(n) linear.

◆ vlMemReverseSubArrays

#define vlMemReverseSubArrays	(	src,
		elementSize,
		numElements
	)	vlMemReverseSubArraysStride(src, elementSize, elementSize, numElements)

Reverses the bytes in a tightly packed series of elements of a defined length.

This is to be used on tightly packed sequences of elements. An element is defined as a discrete sub-array of bytes in a larger sequence.

Assuming you have the following input: [0xAABBCCDD, 0x11223344, 0x55667788], the expected output would be: [0xDDCCBBAA, 0x44332211, 0x88776655].

This differs from the vlMemReverse function, where given that input the expected output would be: [0x88776655, 0x44332211, 0xDDCCBBAA].

See also: vlMemReverseSubArraysStride

Parameters

src	memory block pointer
elementSize	size of each sub array, or element, in bytes
numElements	total number of sub arrays, or elements

Complexity of O(n) linear.

Typedef Documentation

◆ vl_memory

typedef VL_MEMORY_T vl_memory

The typedef for vl_memory is defined as the smallest possible word size. This is intended to improve code readability and intent.

This is used only to indicate blocks of memory allocated through vlMemAlloc(/Aligned) and vlMemRealloc.

See also: vlMemAlloc; vlMemAllocAligned; vlMemRealloc

vl_memory pointers have a header associated with them.

◆ vl_transient

typedef VL_MEMORY_T vl_transient

The typedef for vl_transient is, similarly, the smallest possible word size. This is intended to improve code readability and intent.

This is used to indicate pointers to blocks of memory which that might be moved, deleted, or erased through some operation on a data structure, allocator, or stack scope.

Function Documentation

◆ vlMemAlignment()

VL_API 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_API 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_API 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:

◆ vlMemAllocStack()

vl_transient * vlMemAllocStack ( vl_memsize_t allocSize )

inline

Allocate memory on the stack (automatic storage).

Allocates memory from the stack for the specified size. The allocated memory is automatically freed when the enclosing scope exits. Stack allocation is very fast but is limited by stack size (typically a few MB on most systems).

Characteristics

Speed: Nearly free (just stack pointer adjustment)
Automatic cleanup: Memory is freed when scope exits
Size limit: Constrained by stack size (~1-8 MB typically)
Alignment: Uses default system alignment; for custom alignment, use vlMemAllocStackAligned()

Contract

Ownership: The current function scope maintains implicit ownership; the memory is automatically reclaimed on function exit.
Lifetime: Valid only within the scope of the calling function.
Thread Safety: Thread-safe (allocates from the thread-local stack).
Nullability: Never returns NULL.
Error Conditions: Stack overflow if allocSize is too large for the remaining stack space (leads to process crash).
Undefined Behavior: Accessing the returned pointer after the allocating function has returned.
Memory Allocation Expectations: Allocates allocSize bytes directly on the stack via alloca or equivalent.
Return-value Semantics: Returns a pointer to the allocated stack memory.

Example

void process_data(void) {
    vl_transient *buf = vlMemAllocStack(1024);
    // Use buf...
    // buf is automatically freed when process_data() returns
}

When to Use

Temporary buffers within a single function scope
Known, reasonably small sizes (< 1 MB)
Performance-critical code where allocation speed matters
Scratch space for intermediate computations

Parameters

allocSize Number of bytes to allocate

Returns: Pointer to allocated stack memory

Note: No NULL return is possible (stack overflow causes a crash instead); Stack memory is NOT managed by vlMemFree(); it's automatic; Allocating large amounts may cause stack overflow—verify size limits

See also: vlMemAllocStackAligned, vlMemAllocStackType, vlMemAllocStackTypeArray

Here is the caller graph for this function:

◆ vlMemAllocStackAligned()

vl_transient * vlMemAllocStackAligned	(	vl_memsize_t	allocSize,
		vl_uint16_t	align
	)

inline

Allocate aligned memory on the stack (automatic storage).

Allocates memory from the stack with custom alignment requirements. The allocated memory is automatically freed when the enclosing scope exits.

Characteristics

Speed: Very fast (stack pointer adjustment + alignment math)
Automatic cleanup: Memory is freed when scope exits
Custom alignment: Guarantees pointer is aligned to specified boundary
Size limit: Constrained by stack size (~1-8 MB typically)

Alignment Requirements

The alignment must be a power of 2 (16, 32, 64, 128, etc.). Passing a non-power-of-2 alignment will produce undefined behavior.

Contract

Ownership: The current function scope maintains implicit ownership; the memory is automatically reclaimed on function exit.
Lifetime: Valid only within the scope of the calling function.
Thread Safety: Thread-safe (allocates from the thread-local stack).
Nullability: Never returns NULL.
Error Conditions: Stack overflow if the padded allocation size is too large for the remaining stack space.
Undefined Behavior: Accessing the returned pointer after the allocating function has returned. align is not a power of 2.
Memory Allocation Expectations: Allocates allocSize + align - 1 bytes on the stack and returns an aligned pointer.
Return-value Semantics: Returns a pointer to the aligned stack memory.

Example

// Allocate 256 bytes aligned to 16-byte boundary (common for SIMD)
vl_transient *simd_buf = vlMemAllocStackAligned(256, 16);
// Allocate 512 bytes aligned to 64-byte boundary (cache line)
vl_transient *cache_buf = vlMemAllocStackAligned(512, 64);

When to Use

SIMD operations requiring aligned data (SSE, AVX, NEON, etc.)
Cache-line alignment for performance-sensitive data
Temporary aligned scratch buffers within a function
Interfacing with APIs that require specific alignment

Parameters

allocSize	Number of bytes to allocate
align	Required byte alignment (must be a power of 2)

Returns: Pointer to allocated and aligned stack memory

Warning: align MUST be a power of 2, or behavior is undefined

Note: No NULL return is possible (stack overflow causes a crash instead); Stack memory is NOT managed by vlMemFree(); it's automatic; The actual stack space used may be slightly more than allocSize due to alignment padding

See also: vlMemAllocStack, vlMemAllocStackType, vlMemAllocStackTypeArray

Here is the call graph for this function:

◆ vlMemClone()

VL_API 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()

VL_API 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()

VL_API 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_API 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()

VL_API 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_API 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()

VL_API 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:

Macros

Typedefs

Functions

Macro Definition Documentation

◆ VL_ALIGN_HINT

◆ VL_ALIGNOF

◆ VL_DEFAULT_MEMORY_ALIGN

◆ VL_DEFAULT_MEMORY_SIZE

◆ VL_KB

◆ VL_MB

◆ VL_MEMORY_PAD_UP

◆ vlMemAllocStackType

Example

When to Use

◆ vlMemAllocStackTypeArray

Example

When to Use

◆ vlMemAllocType

Example

◆ vlMemAllocTypeArray

Example

◆ vlMemReverse

◆ vlMemReverseSubArrays

Typedef Documentation

◆ vl_memory

◆ vl_transient

Function Documentation

◆ vlMemAlignment()

Contract

◆ vlMemAlloc()

Contract

◆ vlMemAllocAligned()

Contract

◆ vlMemAllocStack()

Characteristics

Contract

Example

When to Use

◆ vlMemAllocStackAligned()

Characteristics

Alignment Requirements

Contract

Example

When to Use

◆ vlMemClone()

Contract

◆ vlMemCopyStride()

Contract

◆ vlMemFree()

Contract

◆ vlMemRealloc()

Contract

◆ vlMemReverseSubArraysStride()

Contract

◆ vlMemSize()

Contract

◆ vlMemSort()

Contract