Circular Queue
Utilities > Thread-Safe Objects

Circular Queue. More...

Modules

Types
Circular Queue data types.
 

Functions

gos_result_t gos_safe_circular_queue_init (gos_safe_circular_queue_t *queue, void *buffer, uint16_t entry_size, uint16_t max_entry_count)
 
gos_result_t gos_safe_circular_queue_push (gos_safe_circular_queue_t *queue, void *entry)
 
gos_result_t gos_safe_circular_queue_pop (gos_safe_circular_queue_t *queue, void *entry)
 
void gos_safe_circular_queue_flush (gos_safe_circular_queue_t *queue, gos_safe_circular_queue_flush_callback_t callback)
 
bool gos_safe_circular_queue_is_empty (const gos_safe_circular_queue_t *queue)
 
bool gos_safe_circular_queue_is_full (const gos_safe_circular_queue_t *queue)
 
bool gos_safe_circular_queue_tail_is_last_entry (gos_safe_circular_queue_t *queue)
 
uint16_t gos_safe_circular_queue_get_count (const gos_safe_circular_queue_t *queue)
 
uint16_t gos_safe_circular_queue_get_free_space_count (const gos_safe_circular_queue_t *queue)
 
void * gos_safe_circular_queue_get_tail (gos_safe_circular_queue_t *queue)
 
void * gos_safe_circular_queue_get_head (gos_safe_circular_queue_t *queue)
 

Detailed Description

Circular Queue.

A circular queue is a First In, First Out (FIFO) data structure that will 'wrap' to the beginning once the end of the list is reached.

This circular queue implementation stores the contents of each entry internally. This means an entry's memory does NOT need to persist after the entry is added to the queue.

Function Documentation

◆ gos_safe_circular_queue_flush()

void gos_safe_circular_queue_flush ( gos_safe_circular_queue_t *  queue,
gos_safe_circular_queue_flush_callback_t  callback 
)

Remove all entries from queue

This removes all entries from the queue, optionally calling the given callback for each entry.

Parameters
[in]queueThread-safe, circular queue
[in]callbackCallback to be invoked for each entry in queue, leave NULL if unused
Returns
gos_result_t, result of API

◆ gos_safe_circular_queue_get_count()

uint16_t gos_safe_circular_queue_get_count ( const gos_safe_circular_queue_t *  queue)

Return number of entries in queue

Parameters
[in]queueThread-safe, circular queue
Returns
Number of entries in queue

◆ gos_safe_circular_queue_get_free_space_count()

uint16_t gos_safe_circular_queue_get_free_space_count ( const gos_safe_circular_queue_t *  queue)

Return available slots in queue

Parameters
[in]queueThread-safe, circular queue
Returns
Number of unused/free slots in queue (i.e. free space)

◆ gos_safe_circular_queue_get_head()

void* gos_safe_circular_queue_get_head ( gos_safe_circular_queue_t *  queue)

Return pointer to head (i.e. oldest entry) of queue

Note
WARN: The returned pointer is NOT thread-safe!
Parameters
[in]queueThread-safe, circular queue
Returns
Pointer to head of queue

◆ gos_safe_circular_queue_get_tail()

void* gos_safe_circular_queue_get_tail ( gos_safe_circular_queue_t *  queue)

Return pointer to tail (i.e. next available slot) of queue

Note
WARN: The returned pointer is NOT thread-safe!
Parameters
[in]queueThread-safe, circular queue
Returns
Pointer to tail of queue

◆ gos_safe_circular_queue_init()

gos_result_t gos_safe_circular_queue_init ( gos_safe_circular_queue_t *  queue,
void *  buffer,
uint16_t  entry_size,
uint16_t  max_entry_count 
)

Initialize a thread-safe circular queue (aka FIFO)

This initialize a gos_safe_circular_queue_t context.

Note
The given buffer must be pre-allocated and large enough to hold entry_size X max_entry_count bytes of data.
Parameters
[in]queueThread-safe, circular queue to initialize
[in]bufferPre-allocated buffer to hold queue entries
[in]entry_sizeSize in bytes of each queue entry
[in]max_entry_countMaximum number of entries the queue can hold
Returns
gos_result_t, result of API

◆ gos_safe_circular_queue_is_empty()

bool gos_safe_circular_queue_is_empty ( const gos_safe_circular_queue_t *  queue)

Return if queue is empty

Parameters
[in]queueThread-safe, circular queue
Returns
true if empty, false else

◆ gos_safe_circular_queue_is_full()

bool gos_safe_circular_queue_is_full ( const gos_safe_circular_queue_t *  queue)

Return if queue is full

Parameters
[in]queueThread-safe, circular queue
Returns
true if full, false else

◆ gos_safe_circular_queue_pop()

gos_result_t gos_safe_circular_queue_pop ( gos_safe_circular_queue_t *  queue,
void *  entry 
)

Remove oldest entry from queue

This removes the oldest entry from the beginning of the queue (aka FIFO).

Note
This API does NOT block, if the queue is empty then this fails immediately.
Parameters
[in]queueThread-safe, circular queue
[out]entryBuffer to hold removed entry, leave NULL if unused
Returns
gos_result_t, result of API

◆ gos_safe_circular_queue_push()

gos_result_t gos_safe_circular_queue_push ( gos_safe_circular_queue_t *  queue,
void *  entry 
)

Add an entry to the end of the queue

This pushes an entry to the end of the queue (aka FIFO).

Note
After calling this API, the given entry may be discarded as the entry's data is memcpy'd into the queue buffer.
This API does NOT block, if there is no room in the queue then it fails immediately.
Parameters
[in]queueThread-safe, circular queue
[in]entryEntry to memcpy to end of FIFO
Returns
gos_result_t, result of API

◆ gos_safe_circular_queue_tail_is_last_entry()

bool gos_safe_circular_queue_tail_is_last_entry ( gos_safe_circular_queue_t *  queue)

Return if the tail is at end of buffer

This returns if the tail entry is also the last slot of the queue buffer. This is useful to determine if the queue is about to wrap to the beginning of the buffer.

Parameters
[in]queueThread-safe, circular queue
Returns
true if tail is at end of buffer, false else