vl_buffer.h File Reference

#include "vl_memory.h"
#include "vl_numtypes.h"

Include dependency graph for vl_buffer.h:

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

Go to the source code of this file.

Functions
VL_API vl_buffer *	vlBufferNewExt (vl_memsize_t size, vl_uint16_t align)
	Allocates a new buffer, and initializes it with the specified capacity. The buffer must be deleted with vlBufferDelete(...) when it is no longer being used to avoid leaking memory.
VL_API void	vlBufferInitExt (vl_buffer *buffer, vl_memsize_t size, vl_uint16_t align)
	Initializes a buffer instance with specific size and alignment.
VL_API void	vlBufferReset (vl_buffer *buffer, vl_memsize_t newCapacity)
	Resets the state of the specified buffer, setting the offset integer to zero and the computed size to zero. This will re-allocate the buffer to hold the specified capacity.
VL_API void	vlBufferClear (vl_buffer *buffer)
	Sets the entirety of the buffer to zero. Also resets offset and computed size to zero.
VL_API void	vlBufferShrinkToFit (vl_buffer *buffer)
	Resizes the specified buffer to hold a capacity equal to the current computed size.
VL_API vl_buffer *	vlBufferClone (const vl_buffer *src, vl_buffer *dest)
	Clones the source buffer to the destination buffer.
VL_API vl_memsize_t	vlBufferCopy (vl_buffer *src, vl_buffer *dest, vl_memsize_t len)
	Copies a series of bytes from one buffer to another.
VL_API vl_memsize_t	vlBufferWrite (vl_buffer *buffer, vl_memsize_t size, const void *src)
	Performs a copy from the specified source pointer into the buffer. The bytes are written at the current offset integer belonging to the buffer state. This function will resize the buffer when necessary, doubling capacity iteratively until it fits. The buffer offset will be incremented by the total number of bytes written.
VL_API vl_memsize_t	vlBufferRead (vl_buffer *buffer, vl_memsize_t size, void *dest)
	Copies bytes from the buffer to the specified destination. Performs a copy from the buffer to the specified destination pointer. This will increment the buffer offset.
VL_API void	vlBufferFree (vl_buffer *buffer)
	Frees the internal data of the specified buffer.
VL_API void	vlBufferDelete (vl_buffer *buffer)
	Deletes the specified buffer and its internal data.

Function Documentation

vlBufferClear()

VL_API void vlBufferClear

(

vl_buffer *

buffer

)

Sets the entirety of the buffer to zero. Also resets offset and computed size to zero.

Contract

• Ownership: Unchanged.
• Lifetime: Unchanged.
• Thread Safety: Not thread-safe.
• Nullability: buffer must not be NULL.
• Error Conditions: None.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Complexity O(n) where n = buffer capacity

Parameters

buffer

struct pointer

Here is the call graph for this function:

vlBufferClone()

VL_API vl_buffer * vlBufferClone	(	const vl_buffer *	src,
		vl_buffer *	dest
	)

Clones the source buffer to the destination buffer.

This is a 'complete' clone of the entirety of the buffer, and thus includes all related state (offset, size) alongside a copy of the underlying block of memory.

When simply copying data from one buffer to another, consider the more stateful vlBufferCopy.

The 'src' buffer must be non-null and point to an initialized buffer. The 'dest' buffer must be either null, or a pointer to an initialized buffer.

If the 'dest' buffer is null, a new instance is created via vlBufferNew. It must later be disposed using vlBufferDelete if this is the case.

Contract

• Ownership: If dest is NULL, the caller owns the returned vl_buffer. If dest is provided, ownership remains with the caller.
• Lifetime: The dest buffer is valid until vlBufferDelete (if newly allocated) or vlBufferFree.
• Thread Safety: Not thread-safe.
• Nullability: src must not be NULL. dest can be NULL.
• Error Conditions: Returns NULL if new buffer allocation fails when dest is NULL.
• Undefined Behavior: Passing an uninitialized buffer.
• Memory Allocation Expectations: May allocate a new vl_buffer struct and/or a new data block via vlMemAllocAligned or vlMemRealloc.
• Return-value Semantics: Returns the pointer to the cloned buffer (dest or the new instance).

See also

vlBufferNew

vlBufferCopy

Parameters

src	source buffer pointer
dest	destination buffer pointer, or NULL.

Complexity O(n) where n = buffer capacity.

Returns

'dest' buffer, or buffer created via vlBufferNew.

Here is the call graph for this function:

vlBufferCopy()

VL_API vl_memsize_t vlBufferCopy	(	vl_buffer *	src,
		vl_buffer *	dest,
		vl_memsize_t	len
	)

Copies a series of bytes from one buffer to another.

The read from the src buffer and the write to the dest buffer are relative to their current respective offsets.

If there are less bytes available in the source buffer than those specified by len, the copy is performed up to the end of the source.

Contract

• Ownership: Ownership of buffers is unchanged.
• Lifetime: Both buffers must be valid during the call.
• Thread Safety: Not thread-safe.
• Nullability: src and dest must not be NULL.
• Error Conditions: Same as vlBufferWrite regarding potential dest allocation failures.
• Undefined Behavior: Passing uninitialized buffers.
• Memory Allocation Expectations: May trigger expansion of the dest buffer.
• Return-value Semantics: Returns the total number of bytes successfully copied from src to dest.

Parameters

src	source buffer pointer
dest	destination buffer pointer
len	total number of bytes to attempt to copy.

Complexity O(n) where n = len

Returns

total number of bytes copied from src to dest.

Here is the call graph for this function:

vlBufferDelete()

VL_API void vlBufferDelete

(

vl_buffer *

buffer

)

Deletes the specified buffer and its internal data.

The buffer should have been initialized via vlBufferNew(Ext) or vlBufferClone. This function frees both the internal data and the vl_buffer struct itself.

Contract

• Ownership: Releases ownership of both the internal data block and the vl_buffer struct.
• Lifetime: Both the buffer and its pointer become invalid.
• Thread Safety: Not thread-safe.
• Nullability: Safe to call if buffer is NULL.
• Error Conditions: None.
• Undefined Behavior: Double deletion.
• Memory Allocation Expectations: Deallocates the internal data block and the vl_buffer struct.
• Return-value Semantics: None (void).

See also

vlBufferNew

vlBufferNewExt

vlBufferClone

Parameters

buffer

struct pointer

Complexity O(1) constant.

Here is the call graph for this function:

vlBufferFree()

VL_API void vlBufferFree

(

vl_buffer *

buffer

)

Frees the internal data of the specified buffer.

The buffer should have been initialized via vlBufferInit(Ext). This function does NOT free the vl_buffer struct itself.

Contract

• Ownership: Releases ownership of the internal data block. The caller still owns the vl_buffer struct.
• Lifetime: The internal data becomes invalid. The vl_buffer struct remains valid but is in an uninitialized state.
• Thread Safety: Not thread-safe.
• Nullability: Safe to call if buffer is NULL (due to vlMemFree check).
• Error Conditions: None.
• Undefined Behavior: Double free of internal data.
• Memory Allocation Expectations: Deallocates the internal data block.
• Return-value Semantics: None (void).

See also

vlBufferInit

vlBufferInitExt

Parameters

buffer

struct pointer

Complexity O(1) constant.

Here is the call graph for this function:

Here is the caller graph for this function:

vlBufferInitExt()

VL_API void vlBufferInitExt	(	vl_buffer *	buffer,
		vl_memsize_t	size,
		vl_uint16_t	align
	)

Initializes a buffer instance with specific size and alignment.

Contract

• Ownership: The caller maintains ownership of the buffer struct. The function manages the internal data allocation.
• Lifetime: The buffer struct must remain valid as long as it is in use. Internal data is valid until vlBufferFree or vlBufferDelete.
• Thread Safety: Not thread-safe.
• Nullability: If buffer is NULL, the function returns immediately (no-op).
• Error Conditions: None.
• Undefined Behavior: Passing an already initialized buffer without first calling vlBufferFree (causes memory leak).
• Memory Allocation Expectations: Uses vlMemAllocAligned to allocate the initial data block.
• Return-value Semantics: None (void).

Parameters

buffer	pointer to buffer
size	initial capacity N
align	byte-level alignment of the allocated memory

Complexity O(1) constant

Here is the call graph for this function:

Here is the caller graph for this function:

vlBufferNewExt()

VL_API vl_buffer * vlBufferNewExt	(	vl_memsize_t	size,
		vl_uint16_t	align
	)

Allocates a new buffer, and initializes it with the specified capacity. The buffer must be deleted with vlBufferDelete(...) when it is no longer being used to avoid leaking memory.

Contract

• Ownership: The caller owns the returned vl_buffer pointer and is responsible for calling vlBufferDelete.
• Lifetime: The buffer is valid until it is passed to vlBufferDelete.
• Thread Safety: Not thread-safe. Concurrent access to the same buffer must be synchronized.
• Nullability: Returns NULL if heap allocation for the vl_buffer struct fails.
• Error Conditions: Returns NULL on allocation failure.
• Undefined Behavior: None.
• Memory Allocation Expectations: Allocates memory for the vl_buffer struct and then uses vlMemAllocAligned for the data portion.
• Return-value Semantics: Returns a pointer to the newly allocated and initialized buffer, or NULL.

Complexity O(1) constant

Parameters

size	initial capacity N
align	byte-level alignment of the allocated memory

Returns

pointer to buffer.

Here is the call graph for this function:

Here is the caller graph for this function:

vlBufferRead()

VL_API vl_memsize_t vlBufferRead	(	vl_buffer *	buffer,
		vl_memsize_t	size,
		void *	dest
	)

Copies bytes from the buffer to the specified destination. Performs a copy from the buffer to the specified destination pointer. This will increment the buffer offset.

Contract

• Ownership: Unchanged.
• Lifetime: Buffer and dest must be valid.
• Thread Safety: Not thread-safe.
• Nullability: buffer and dest must not be NULL.
• Error Conditions: None.
• Undefined Behavior: If the requested size exceeds available data, the function may still attempt to copy size bytes, potentially reading into uninitialized capacity beyond buffer->size.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns the number of bytes that were within the valid data range of the buffer (up to buffer->size).

Complexity O(n) where n = param size

Parameters

buffer	struct pointer
size	total number of bytes to attempt to copy
dest	pointer to the memory that will be copied to

Returns

actual number of bytes copied

vlBufferReset()

VL_API void vlBufferReset	(	vl_buffer *	buffer,
		vl_memsize_t	newCapacity
	)

Resets the state of the specified buffer, setting the offset integer to zero and the computed size to zero. This will re-allocate the buffer to hold the specified capacity.

Contract

• Ownership: Ownership of the buffer remains unchanged.
• Lifetime: The buffer remains valid. Existing data may be lost or overwritten.
• Thread Safety: Not thread-safe.
• Nullability: buffer must not be NULL.
• Error Conditions: If vlMemRealloc fails, buffer->data may become NULL.
• Undefined Behavior: Passing a pointer to an uninitialized buffer.
• Memory Allocation Expectations: Uses vlMemRealloc to change the capacity of the underlying data block.
• Return-value Semantics: None (void).

Complexity O(1) constant

Parameters

buffer	struct pointer
newCapacity	new capacity, in bytes

Here is the call graph for this function:

Here is the caller graph for this function:

vlBufferShrinkToFit()

VL_API void vlBufferShrinkToFit

(

vl_buffer *

buffer

)

Resizes the specified buffer to hold a capacity equal to the current computed size.

Contract

• Ownership: Unchanged.
• Lifetime: Unchanged.
• Thread Safety: Not thread-safe.
• Nullability: buffer must not be NULL.
• Error Conditions: If vlMemRealloc fails, the buffer's data pointer may be lost.
• Undefined Behavior: None.
• Memory Allocation Expectations: Uses vlMemRealloc to shrink the data block.
• Return-value Semantics: None (void).

Complexity O(n) where n = new buffer capacity

Parameters

buffer

struct pointer

Here is the call graph for this function:

vlBufferWrite()

VL_API vl_memsize_t vlBufferWrite	(	vl_buffer *	buffer,
		vl_memsize_t	size,
		const void *	src
	)

Performs a copy from the specified source pointer into the buffer. The bytes are written at the current offset integer belonging to the buffer state. This function will resize the buffer when necessary, doubling capacity iteratively until it fits. The buffer offset will be incremented by the total number of bytes written.

Providing a NULL source pointer will reserve space in the buffer without copying any data. Existing data within the reserved range is not modified, and can be directly written to.

Contract

• Ownership: Ownership of buffer and src is unchanged.
• Lifetime: Both must be valid during the call.
• Thread Safety: Not thread-safe.
• Nullability: buffer must not be NULL. src can be NULL to reserve space.
• Error Conditions: If internal reallocation fails, buffer->data may become invalid or NULL.
• Undefined Behavior: Passing an uninitialized buffer.
• Memory Allocation Expectations: Automatically grows the buffer capacity (doubling) if the write exceeds current capacity.
• Return-value Semantics: Returns the offset at which the write started.

Complexity O(n) where n = param size

Parameters

buffer	struct pointer
size	total number of bytes to write
src	pointer to the memory that will be copied from

Returns

the offset at which the bytes were written into the buffer.

Here is the call graph for this function:

Here is the caller graph for this function: