Queue

Fixed-capacity FIFO queue of non-owning object pointers. More...

Functions
sgl_queue_t *	sgl_queue_create (sgl_size_t capacity)
	Creates an empty queue.
void	sgl_queue_destroy (sgl_queue_t **queue)
	Destroys a queue and clears the caller's handle.
sgl_result_t	sgl_queue_copy (sgl_queue_t *dst, const sgl_queue_t *src)
	Copies queue state and entries without transferring object ownership.
sgl_result_t	sgl_queue_unsafe_enqueue (sgl_queue_t *queue, const void *data)
	Enqueues an object pointer without locking the queue.
sgl_result_t	sgl_queue_enqueue (sgl_queue_t *queue, const void *data)
	Enqueues an object pointer while holding the queue lock.
void *	sgl_queue_dequeue (sgl_queue_t *queue)
	Removes and returns the oldest queue entry.
void *	sgl_queue_peek (sgl_queue_t *queue)
	Returns the oldest queue entry without removing it.
sgl_result_t	sgl_queue_is_empty (const sgl_queue_t *queue)
	Tests whether a valid queue is empty.
sgl_result_t	sgl_queue_is_full (const sgl_queue_t *queue)
	Tests whether a valid queue is full.
sgl_size_t	sgl_queue_get_capacity (const sgl_queue_t *queue)
	Returns queue capacity.
sgl_size_t	sgl_queue_get_count (const sgl_queue_t *queue)
	Returns the current entry count.

Detailed Description

Fixed-capacity FIFO queue of non-owning object pointers.

The queue owns only its pointer ring. Enqueued objects remain owned by the caller. Public enqueue, dequeue, and peek operations synchronize access; status and count accessors are snapshots and do not acquire the queue lock.

Function Documentation

sgl_queue_copy()

sgl_result_t sgl_queue_copy	(	sgl_queue_t *	dst,
		const sgl_queue_t *	src
	)

Copies queue state and entries without transferring object ownership.

Parameters

[out]	dst	Destination queue.
[in]	src	Source queue.

Return values

SGL_SUCCESS	Queue state copied.
SGL_ERROR_MISSMATCHED_CAPACITY	Destination capacity is too small.
SGL_ERROR_INVALID_ARGUMENTS	A queue pointer is SGL_NULL.

Warning

The caller must exclude concurrent access to both queues.

sgl_queue_create()

sgl_queue_t * sgl_queue_create

(

sgl_size_t

capacity

)

Creates an empty queue.

Parameters

[in]

capacity

Positive maximum number of entries.

Returns

New queue, or SGL_NULL for invalid capacity or allocation failure.

sgl_queue_dequeue()

void * sgl_queue_dequeue

(

sgl_queue_t *

queue

)

Removes and returns the oldest queue entry.

Parameters

[in,out]

queue

Queue to modify.

Returns

Dequeued object pointer, or SGL_NULL for a NULL or empty queue.

sgl_queue_destroy()

void sgl_queue_destroy

(

sgl_queue_t **

queue

)

Destroys a queue and clears the caller's handle.

Parameters

[in,out]

queue

Address of a queue handle; either pointer may be SGL_NULL.

sgl_queue_enqueue()

sgl_result_t sgl_queue_enqueue	(	sgl_queue_t *	queue,
		const void *	data
	)

Enqueues an object pointer while holding the queue lock.

Parameters

[in,out]	queue	Destination queue.
[in]	data	Non-NULL object pointer; ownership is retained by the caller.

Return values

SGL_SUCCESS	Entry enqueued.
SGL_QUEUE_IS_FULL	Queue has no free slot.
SGL_ERROR_INVALID_ARGUMENTS	A pointer is SGL_NULL.

sgl_queue_get_capacity()

sgl_size_t sgl_queue_get_capacity

(

const sgl_queue_t *

queue

)

Returns queue capacity.

Parameters

[in]

queue

Queue or SGL_NULL.

Returns

Capacity, or 0 for SGL_NULL.

sgl_queue_get_count()

sgl_size_t sgl_queue_get_count

(

const sgl_queue_t *

queue

)

Returns the current entry count.

Parameters

[in]

queue

Queue or SGL_NULL.

Returns

Entry count, or 0 for SGL_NULL.

sgl_queue_is_empty()

sgl_result_t sgl_queue_is_empty

(

const sgl_queue_t *

queue

)

Tests whether a valid queue is empty.

Parameters

[in]

queue

Queue to inspect; must not be SGL_NULL.

Return values

SGL_QUEUE_IS_EMPTY	Queue contains no entries.
SGL_QUEUE_IS_NOT_EMPTY	Queue contains entries.

sgl_queue_is_full()

sgl_result_t sgl_queue_is_full

(

const sgl_queue_t *

queue

)

Tests whether a valid queue is full.

Parameters

[in]

queue

Queue to inspect; must not be SGL_NULL.

Return values

SGL_QUEUE_IS_FULL	Queue reached capacity.
SGL_QUEUE_IS_NOT_FULL	Queue has a free slot.

sgl_queue_peek()

void * sgl_queue_peek

(

sgl_queue_t *

queue

)

Returns the oldest queue entry without removing it.

Parameters

[in]

queue

Queue to inspect.

Returns

Oldest object pointer, or SGL_NULL for a NULL or empty queue.

sgl_queue_unsafe_enqueue()

sgl_result_t sgl_queue_unsafe_enqueue	(	sgl_queue_t *	queue,
		const void *	data
	)

Enqueues an object pointer without locking the queue.

Parameters

[in,out]	queue	Destination queue.
[in]	data	Non-NULL object pointer; ownership is retained by the caller.

Return values

SGL_SUCCESS	Entry enqueued.
SGL_QUEUE_IS_FULL	Queue has no free slot.
SGL_ERROR_INVALID_ARGUMENTS	A pointer is SGL_NULL.

Warning

Use only while the caller has exclusive access to queue.