vl_deque.h File Reference

#include "vl_pool.h"

Include dependency graph for vl_deque.h:

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

Go to the source code of this file.

Functions
VL_API void	vlDequeInit (vl_deque *deq, vl_uint16_t elementSize)
	Initializes the specified instance of vl_deque with specific element size.
VL_API void	vlDequeFree (vl_deque *deq)
	De-initializes and frees the internal resources of the specified deque.
VL_API vl_deque *	vlDequeNew (vl_uint16_t elementSize)
	Allocates on the heap, initializes, and returns a new deque instance.
VL_API void	vlDequeDelete (vl_deque *deq)
	De-initializes and deletes the specified deque and its resources.
VL_API void	vlDequeClear (vl_deque *deq)
	Clears the specified deque.
VL_API void	vlDequeReserve (vl_deque *deque, vl_dsidx_t n)
	Reserves space for n-many elements in the underlying buffer of the specified deque.
VL_API vl_deque *	vlDequeClone (const vl_deque *src, vl_deque *dest)
	Clones the specified source deque to another.
VL_API void	vlDequePushFront (vl_deque *deq, const void *val)
	Adds and copies an element to the front of the deque.
VL_API int	vlDequePopFront (vl_deque *deq, void *val)
	Copies and removes an element from the front of the deque.
VL_API void	vlDequePushBack (vl_deque *deq, const void *val)
	Adds and copies an element to the end of the deque.
VL_API int	vlDequePopBack (vl_deque *deq, void *val)
	Copies and removes an element from the end of the deque.

Function Documentation

vlDequeClear()

VL_API void vlDequeClear

(

vl_deque *

deq

)

Clears the specified deque.

Resets the head and tail iterators and clears the internal node pool.

Contract

• Ownership: Unchanged.
• Lifetime: All pointers to elements in the deque become invalid.
• Thread Safety: Not thread-safe.
• Nullability: deq must not be NULL.
• Error Conditions: None.
• Undefined Behavior: Passing an uninitialized deque.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Parameters

deq

pointer

Complexity O(1) constant.

Here is the call graph for this function:

vlDequeClone()

VL_API vl_deque * vlDequeClone	(	const vl_deque *	src,
		vl_deque *	dest
	)

Clones the specified source deque to another.

Clones the entirety of the src deque to the dest deque, including all elements and order.

The 'src' deque pointer must be non-null and initialized. The 'dest' deque pointer may be null, but if it is not null it must be initialized.

If the 'dest' deque pointer is null, a new deque is created via vlDequeNew. Otherwise, its element size is set to the source's and all of its existing data is replaced.

Contract

• Ownership: If dest is NULL, the caller owns the returned vl_deque. If dest is provided, ownership remains with the caller.
• Lifetime: The cloned deque is valid until deleted or freed.
• Thread Safety: Not thread-safe.
• Nullability: src must not be NULL. dest can be NULL.
• Error Conditions: Returns NULL if allocation fails.
• Undefined Behavior: Passing an uninitialized deque.
• Memory Allocation Expectations: May allocate a new deque struct and multiple nodes.
• Return-value Semantics: Returns the pointer to the cloned deque, or NULL on failure.

Parameters

src	pointer
dest	pointer

Returns

pointer to deque that was copied to or created.

Here is the call graph for this function:

vlDequeDelete()

VL_API void vlDequeDelete

(

vl_deque *

deq

)

De-initializes and deletes the specified deque and its resources.

The deque should have been initialized via vlDequeNew.

Contract

• Ownership: Releases ownership of the internal node pool and the vl_deque struct.
• Lifetime: The deque pointer becomes invalid.
• Thread Safety: Not thread-safe.
• Nullability: Safe to call if deq is NULL.
• Error Conditions: None.
• Undefined Behavior: Double deletion.
• Memory Allocation Expectations: Deallocates internal resources and the deque struct.
• Return-value Semantics: None (void).

See also

vlDequeNew

Parameters

deq

pointer

Complexity O(1) constant.

Here is the call graph for this function:

vlDequeFree()

VL_API void vlDequeFree

(

vl_deque *

deq

)

De-initializes and frees the internal resources of the specified deque.

The deque should have been initialized via vlDequeInit.

Contract

• Ownership: Releases ownership of the internal node pool. Does NOT release the deq struct itself.
• Lifetime: The deque becomes invalid for use.
• Thread Safety: Not thread-safe.
• Nullability: deq must not be NULL.
• Error Conditions: None.
• Undefined Behavior: Double free.
• Memory Allocation Expectations: Deallocates internal pool structures.
• Return-value Semantics: None (void).

See also

vlDequeInit

Parameters

deq

pointer

Here is the call graph for this function:

Here is the caller graph for this function:

vlDequeInit()

VL_API void vlDequeInit	(	vl_deque *	deq,
		vl_uint16_t	elementSize
	)

Initializes the specified instance of vl_deque with specific element size.

The deque should later be de-initialized via vlDequeFree.

Contract

• Ownership: The caller maintains ownership of the deq struct. The function initializes the internal node pool.
• Lifetime: The deque is valid until vlDequeFree or vlDequeDelete.
• Thread Safety: Not thread-safe. Concurrent access must be synchronized.
• Nullability: deq must not be NULL.
• Error Conditions: None.
• Undefined Behavior: Passing an already initialized deque without first calling vlDequeFree (causes memory leak).
• Memory Allocation Expectations: Initializes an internal vl_pool which allocates management structures.
• Return-value Semantics: None (void).

See also

vlDequeFree

Parameters

deq	pointer
elementSize	size of each element, in bytes.

Complexity O(1) constant.

Here is the caller graph for this function:

vlDequeNew()

VL_API vl_deque * vlDequeNew

(

vl_uint16_t

elementSize

)

Allocates on the heap, initializes, and returns a new deque instance.

The deque should later be deleted via vlDequeDelete.

Contract

• Ownership: The caller owns the returned vl_deque pointer and is responsible for calling vlDequeDelete.
• Lifetime: The deque is valid until vlDequeDelete.
• Thread Safety: Not thread-safe.
• Nullability: Returns NULL if heap allocation for the deque struct fails.
• Error Conditions: Returns NULL on allocation failure.
• Undefined Behavior: None.
• Memory Allocation Expectations: Allocates memory for the vl_deque struct and its internal node pool.
• Return-value Semantics: Returns a pointer to the newly allocated and initialized deque, or NULL.

See also

vlDequeDelete

Parameters

elementSize

size of each element, in bytes.

Complexity O(1) constant.

Returns

deque pointer

Here is the call graph for this function:

Here is the caller graph for this function:

vlDequePopBack()

VL_API int vlDequePopBack	(	vl_deque *	deq,
		void *	val
	)

Copies and removes an element from the end of the deque.

If specified pointer val is NULL, the element is not copied, but the element is still removed.

Contract

• Ownership: Transfers ownership of the element slot back to the internal pool. The caller owns the data copied into val.
• Lifetime: The popped element's storage in the deque becomes invalid.
• Thread Safety: Not thread-safe.
• Nullability: deq must not be NULL. val can be NULL.
• Error Conditions: Returns 0 if the deque is empty.
• Undefined Behavior: Passing an uninitialized deque.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns 1 if an element was successfully popped, 0 if the deque was empty.

Parameters

deq	pointer
val	pointer where the element will be copied to.

Returns

1 if success, 0 if failed.

Here is the call graph for this function:

vlDequePopFront()

VL_API int vlDequePopFront	(	vl_deque *	deq,
		void *	val
	)

Copies and removes an element from the front of the deque.

If specified pointer val is NULL, the element is not copied, but the element is still removed.

Contract

• Ownership: Transfers ownership of the element slot back to the internal pool. The caller owns the data copied into val.
• Lifetime: The popped element's storage in the deque becomes invalid.
• Thread Safety: Not thread-safe.
• Nullability: deq must not be NULL. val can be NULL.
• Error Conditions: Returns 0 if the deque is empty.
• Undefined Behavior: Passing an uninitialized deque.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns 1 if an element was successfully popped, 0 if the deque was empty.

Parameters

deq	pointer
val	pointer where the element will be copied to.

Complexity O(1) constant.

Returns

1 if success, 0 if failed

Here is the call graph for this function:

vlDequePushBack()

VL_API void vlDequePushBack	(	vl_deque *	deq,
		const void *	val
	)

Adds and copies an element to the end of the deque.

Contract

• Ownership: Unchanged. The deque maintains its own copy.
• Lifetime: Valid until popped.
• Thread Safety: Not thread-safe.
• Nullability: deq must not be NULL. val should not be NULL.
• Error Conditions: None checked.
• Undefined Behavior: Passing an uninitialized deque.
• Memory Allocation Expectations: May trigger expansion of the underlying node pool.
• Return-value Semantics: None (void).

Parameters

deq	pointer
val	element data pointer

Complexity O(1) constant.

Here is the call graph for this function:

vlDequePushFront()

VL_API void vlDequePushFront	(	vl_deque *	deq,
		const void *	val
	)

Adds and copies an element to the front of the deque.

Contract

• Ownership: Unchanged. The deque maintains its own copy.
• Lifetime: Valid until popped.
• Thread Safety: Not thread-safe.
• Nullability: deq must not be NULL. val should not be NULL.
• Error Conditions: None checked.
• Undefined Behavior: Passing an uninitialized deque.
• Memory Allocation Expectations: May trigger expansion of the underlying node pool.
• Return-value Semantics: None (void).

Parameters

deq	pointer
val	element data pointer

Complexity O(1) constant.

Here is the call graph for this function:

vlDequeReserve()

VL_API void vlDequeReserve	(	vl_deque *	deque,
		vl_dsidx_t	n
	)

Reserves space for n-many elements in the underlying buffer of the specified deque.

Contract

• Ownership: Unchanged.
• Lifetime: Unchanged.
• Thread Safety: Not thread-safe.
• Nullability: deque must not be NULL.
• Error Conditions: None checked.
• Undefined Behavior: Passing an uninitialized deque.
• Memory Allocation Expectations: Triggers expansion of the underlying node pool.
• Return-value Semantics: None (void).

Parameters

deque	pointer
n	total number of elements to reserve space for.

Here is the call graph for this function: