vl_queue.h File Reference

#include "vl_pool.h"

Include dependency graph for vl_queue.h:

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

Go to the source code of this file.

Functions
VL_API void	vlQueueInit (vl_queue *queue, vl_uint16_t elementSize)
	Initializes the specified queue with a specific element size.
VL_API void	vlQueueFree (vl_queue *queue)
	De-initializes and frees the internal resources of the specified queue.
VL_API vl_queue *	vlQueueNew (vl_uint16_t elementSize)
	Allocates on the heap, initializes, and returns a new queue instance.
VL_API void	vlQueueDelete (vl_queue *queue)
	De-initializes and deletes the specified queue and its resources.
VL_API vl_queue *	vlQueueClone (const vl_queue *src, vl_queue *dest)
	Clones the specified source queue to another.
VL_API void	vlQueueReserve (vl_queue *queue, vl_dsidx_t n)
	Reserves space for n-many elements in the underlying buffer of the specified queue.
VL_API void	vlQueueClear (vl_queue *queue)
	Clears the specified queue.
VL_API void	vlQueuePushBack (vl_queue *queue, const void *element)
	Adds a new element to the end of the queue.
VL_API int	vlQueuePopFront (vl_queue *queue, void *element)
	Copies the first element in the queue and removes it.

Function Documentation

vlQueueClear()

VL_API void vlQueueClear

(

vl_queue *

queue

)

Clears the specified queue.

The underlying data in the queue is untouched, but rather some book-keeping variables are reset.

Contract

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

Parameters

queue

Complexity of O(1) constant.

Here is the call graph for this function:

vlQueueClone()

VL_API vl_queue * vlQueueClone	(	const vl_queue *	src,
		vl_queue *	dest
	)

Clones the specified source queue to another.

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

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

If the 'dest' queue pointer is null, a new queue is created via vlQueueNew. 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_queue. If dest is provided, ownership remains with the caller.
• Lifetime: The cloned queue 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 queue.
• Memory Allocation Expectations: May allocate a new queue struct and multiple nodes.
• Return-value Semantics: Returns the pointer to the cloned queue, or NULL on failure.

Parameters

src	pointer
dest	pointer

Returns

pointer to queue that was copied to or created.

Here is the call graph for this function:

vlQueueDelete()

VL_API void vlQueueDelete

(

vl_queue *

queue

)

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

The queue should have been initialized via vlQueueNew.

Contract

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

See also

vlQueueNew

Parameters

queue

pointer

Complexity of O(1) constant.

Here is the call graph for this function:

vlQueueFree()

VL_API void vlQueueFree

(

vl_queue *

queue

)

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

The queue should have been initialized via vlQueueInit.

Contract

• Ownership: Releases ownership of the internal node pool. Does NOT release the queue struct itself.
• Lifetime: The queue becomes invalid for use.
• Thread Safety: Not thread-safe.
• Nullability: queue 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

vlQueueFree

Parameters

queue

pointer

Complexity of O(1) constant.

Here is the call graph for this function:

Here is the caller graph for this function:

vlQueueInit()

VL_API void vlQueueInit	(	vl_queue *	queue,
		vl_uint16_t	elementSize
	)

Initializes the specified queue with a specific element size.

The queue should then later be de-initialized via vlQueueFree.

Contract

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

See also

vlQueueFree

Parameters

queue	pointer
elementSize	size of a single queue element, in bytes

Complexity of O(1) constant.

Here is the caller graph for this function:

vlQueueNew()

VL_API vl_queue * vlQueueNew

(

vl_uint16_t

elementSize

)

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

The queue should then later be deleted via vlQueueDelete.

Contract

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

See also

vlQueueDelete

Parameters

elementSize

size of a single queue element, in bytes

Complexity of O(1) constant.

Returns

pointer to queue

Here is the call graph for this function:

Here is the caller graph for this function:

vlQueuePopFront()

VL_API int vlQueuePopFront	(	vl_queue *	queue,
		void *	element
	)

Copies the first element in the queue and removes it.

This is a no-op if the queue is empty.

Contract

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

Parameters

queue	pointer
element	data pointer

Complexity of O(1) constant.

Returns

1 if an element was copied and removed, 0 otherwise.

Here is the call graph for this function:

vlQueuePushBack()

VL_API void vlQueuePushBack	(	vl_queue *	queue,
		const void *	element
	)

Adds a new element to the end of the queue.

The element data is copied into the queue's internal storage.

Contract

• Ownership: Unchanged. The queue maintains its own copy of the element.
• Lifetime: Valid until the element is popped.
• Thread Safety: Not thread-safe.
• Nullability: queue must not be NULL. element must not be NULL.
• Error Conditions: None checked (internal node allocation failure is not currently handled).
• Undefined Behavior: Passing a NULL element or an uninitialized queue.
• Memory Allocation Expectations: May trigger expansion of the underlying node pool.
• Return-value Semantics: None (void).

Parameters

queue	pointer
element	data pointer

Complexity of O(1) constant.

Here is the call graph for this function:

vlQueueReserve()

VL_API void vlQueueReserve	(	vl_queue *	queue,
		vl_dsidx_t	n
	)

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

This is done by doubling the size until the requested growth is met or exceeded. This function will always result in the reallocation of the underlying memory.

Contract

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

Parameters

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

Here is the call graph for this function: