This file contains definitions and implementation for a queue that allows a reader thread to use CdiQueuePop() and a writer thread to use CdiQuenePush(). No resource locks are used, so the functions are not reetrant. Blocking CdiQueuePopWait() and CdiQueuePushWait() queue API functions can be used if enabled using the signal_mode parameter of the CdiQueueCreate() API fucntion. NOTE: The API functions only support a single-producer/single-consumer. More...

#include "cdi_queue_api.h"
#include <assert.h>
#include <inttypes.h>
#include <stddef.h>
#include "cdi_logger_api.h"
#include "singly_linked_list_api.h"
#include "utilities_api.h"

Data Structures
struct	QueueItem
	This structure represents a single queue item. More...

struct	QueueState
	Structure used to hold state data for a single queue. More...

Macros
#define	MAX_QUEUE_NAME_LENGTH (64)
	Maximum length of the queue name that is stored internally in queue.c.

Functions
static QueueItem *	GetQueueItemFromItemDataPointer (const void *item_data_ptr)
	Get pointer to the item's parent object (QueueItem).

static uint8_t *	GetDataItemFromListEntry (CdiSinglyLinkedListEntry *entry_item_ptr)
	Get pointer to the data buffer related to the linked list entry of the item.

static void	AddEntriesToBuffers (QueueState state_ptr, uint8_t queue_item_array, int item_count)
	Adds queue item array to allocated buffer and insert into the circular item list at the current write pointer location.

static bool	QueueIncrease (CdiQueueHandle handle_ptr)
	Increases the size of a queue, if it is growable.

static bool	WaitForSignals (CdiSinglyLinkedListEntry volatile entry_change_ptr, CdiSinglyLinkedListEntry entry_static_ptr, CdiSignalType wait_signal, int timeout_ms, CdiSignalType cancel_wait_signal_array, int num_signals, uint32_t *ret_signal_index_ptr)

bool	CdiQueueCreate (const char name_str, uint32_t item_count, uint32_t grow_count, uint32_t max_grow_count, uint32_t item_byte_size, CdiQueueSignalMode signal_mode, CdiQueueHandle ret_handle)
	Creates a queue. Memory is allocated by this function.

bool	CdiQueuePop (CdiQueueHandle handle, void *item_dest_ptr)

bool	CdiQueuePopWait (CdiQueueHandle handle, int timeout_ms, CdiSignalType abort_wait_signal, void *item_dest_ptr)

bool	CdiQueuePopWaitMultiple (CdiQueueHandle handle, int timeout_ms, CdiSignalType abort_wait_signal_array, int num_signals, uint32_t ret_signal_index_ptr, void *item_dest_ptr)

bool	CdiQueuePush (CdiQueueHandle handle, const void *data_ptr)

bool	CdiQueuePushWait (CdiQueueHandle handle, int timeout_ms, CdiSignalType abort_wait_signal, const void *item_ptr)

bool	CdiQueuePushWaitMultiple (CdiQueueHandle handle, int timeout_ms, CdiSignalType signal_array, int num_signals, uint32_t ret_signal_index_ptr, const void *item_ptr)

void	CdiQueueFlush (CdiQueueHandle handle)

bool	CdiQueueIsEmpty (CdiQueueHandle handle)

CdiSignalType	CdiQueueGetPushWaitSignal (CdiQueueHandle handle)

CdiSignalType	CdiQueueGetPopWaitSignal (CdiQueueHandle handle)

const char *	CdiQueueGetName (CdiQueueHandle handle)

void	CdiQueueDestroy (CdiQueueHandle handle)

Detailed Description

This file contains definitions and implementation for a queue that allows a reader thread to use CdiQueuePop() and a writer thread to use CdiQuenePush(). No resource locks are used, so the functions are not reetrant. Blocking CdiQueuePopWait() and CdiQueuePushWait() queue API functions can be used if enabled using the signal_mode parameter of the CdiQueueCreate() API fucntion. NOTE: The API functions only support a single-producer/single-consumer.

Function Documentation

◆ AddEntriesToBuffers()

static void AddEntriesToBuffers	(	QueueState *	state_ptr,
		uint8_t *	queue_item_array,
		int	item_count )

inlinestatic

Adds queue item array to allocated buffer and insert into the circular item list at the current write pointer location.

Parameters

state_ptr	Queue state information.
queue_item_array	The array being attached.
item_count	Number of items in array to be attached.

◆ CdiQueueCreate()

bool CdiQueueCreate	(	const char *	name_str,
		uint32_t	item_count,
		uint32_t	grow_count,
		uint32_t	max_grow_count,
		uint32_t	item_byte_size,
		CdiQueueSignalMode	signal_mode,
		CdiQueueHandle *	ret_handle_ptr )

Creates a queue. Memory is allocated by this function.

Parameters

name_str	Name of queue.
item_count	Number of items in the queue.
grow_count	Number of items that a queue may be increased by if the initial size requested is inadequate.
max_grow_count	Maximum number of times a queue may be increased before an error occurs.
item_byte_size	Size of each item in bytes.
signal_mode	Sets type of signals and optional locking, if any, to use.
ret_handle_ptr	Pointer to returned handle of the new queue.

Returns: true if successful, otherwise false is returned.

◆ CdiQueueDestroy()

void CdiQueueDestroy ( CdiQueueHandle handle )

Destroy a queue.

Parameters

handle Queue handle.

◆ CdiQueueFlush()

void CdiQueueFlush ( CdiQueueHandle handle )

Drain all items in the queue. NOTE: The caller must ensure that other threads cannot use either of the CdiQueuePop() or CdiQueuePush() API functions while using this API function.

Parameters

handle Queue handle.

◆ CdiQueueGetName()

const char * CdiQueueGetName ( CdiQueueHandle handle )

Get name of the queue that was defined when it was created.

Parameters

handle Queue handle.

◆ CdiQueueGetPopWaitSignal()

CdiSignalType CdiQueueGetPopWaitSignal ( CdiQueueHandle handle )

If kQueueSignalPopWait or kQueueSignalBoth was specified when the queue was created, this function returns the signal that got set whenever an item is pushed on the queue. It is used to wait in CdiQueuePopWait(). Otherwise, NULL is returned.

Parameters

handle Queue handle.

◆ CdiQueueGetPushWaitSignal()

CdiSignalType CdiQueueGetPushWaitSignal ( CdiQueueHandle handle )

If kQueueSignalPushWait or kQueueSignalBoth was specified when the queue was created, this function returns the signal that got set whenever an item is popped off the queue. It is used to wait in CdiQueuePushWait(). Otherwise, NULL is returned.

Parameters

handle Queue handle.

◆ CdiQueueIsEmpty()

bool CdiQueueIsEmpty ( CdiQueueHandle handle )

Check if queue is empty.

Parameters

handle Queue handle.

Returns: Returns true if the queue is empty, otherwise false is returned.

◆ CdiQueuePop()

bool CdiQueuePop	(	CdiQueueHandle	handle,
		void *	item_dest_ptr )

Pop an item from the queue buffer and copy to item_dest_ptr. If the queue is empty, false is returned.

Parameters

handle	Queue handle.
item_dest_ptr	Pointer to buffer where to copy the item to. Size of buffer must be large enough to hold the data. Data size was set when the queue was created (see item_byte_size). This is an optional parameter, you can pass NULL if you don't care.

Returns: true if successful, otherwise false (queue is empty).

◆ CdiQueuePopWait()

bool CdiQueuePopWait	(	CdiQueueHandle	handle,
		int	timeout_ms,
		CdiSignalType	abort_wait_signal,
		void *	item_dest_ptr )

Pop an item from the queue buffer and copy to the address item_dest_ptr. If the queue is empty, wait until the specified timeout expires or the optional signal gets set.

Parameters

handle	Queue handle.
timeout_ms	Timeout in mSec can be CDI_INFINITE to wait indefinitely
abort_wait_signal	Signal used to abort waiting.
item_dest_ptr	Pointer to buffer where to copy the item to. Size of buffer must be large enough to hold the data. Data size was set when the queue was created (see item_byte_size). This is an optional parameter. Pass NULL if you don't care.

Returns: true if successful, otherwise false (queue is empty and timeout expired or signal got set).

◆ CdiQueuePopWaitMultiple()

bool CdiQueuePopWaitMultiple	(	CdiQueueHandle	handle,
		int	timeout_ms,
		CdiSignalType *	abort_wait_signal_array,
		int	num_signals,
		uint32_t *	ret_signal_index_ptr,
		void *	item_dest_ptr )

Pop an item from the queue buffer and copy to the address item_dest_ptr. If the queue is empty, wait until the specified timeout expires or one of the signals in the signal array gets set.

Parameters

handle	Queue handle.
timeout_ms	Timeout in mSec can be CDI_INFINITE to wait indefinitely.
abort_wait_signal_array	Array of signals used to abort waiting.
num_signals	Number of signals in the array.
ret_signal_index_ptr	Pointer to the returned signal index that caused the wait to abort. If a timeout occurred, CDI_OS_SIG_TIMEOUT is returned. This is an optional parameter. Pass NULL if you don't care.
item_dest_ptr	Pointer to buffer where to copy the item to. Size of buffer must be large enough to hold the data. Data size was set when the queue was created (see item_byte_size). This is an optional parameter. Pass NULL if you don't care.

Returns: true if successful, otherwise false (queue is empty and timeout expired or signal got set).

◆ CdiQueuePush()

bool CdiQueuePush	(	CdiQueueHandle	handle,
		const void *	item_ptr )

Push an item on the queue. If the queue is full, false is returned.

Parameters

handle	Queue handle.
item_ptr	Pointer where to copy the item from.

Returns: true if successful, otherwise false (queue is full).

◆ CdiQueuePushWait()

bool CdiQueuePushWait	(	CdiQueueHandle	handle,
		int	timeout_ms,
		CdiSignalType	abort_wait_signal,
		const void *	item_ptr )

Push an item on the queue. If the queue is full, wait until the specified timeout expires or the optional signal gets set.

Parameters

handle	Queue handle.
timeout_ms	Timeout in mSec can be CDI_INFINITE to wait indefinitely.
abort_wait_signal	Signal used to abort waiting.
item_ptr	Address where to copy the item from.

Returns: true if successful, otherwise false (queue is full and timeout expired or signal got set).

◆ CdiQueuePushWaitMultiple()

bool CdiQueuePushWaitMultiple	(	CdiQueueHandle	handle,
		int	timeout_ms,
		CdiSignalType *	abort_wait_signal_array,
		int	num_signals,
		uint32_t *	ret_signal_index_ptr,
		const void *	item_ptr )

Push an item on the queue. If the queue is full, wait until the specified timeout expires or one of the signals in the signal array gets set.

Parameters

handle	Queue handle.
timeout_ms	Timeout in mSec can be CDI_INFINITE to wait indefinitely.
abort_wait_signal_array	Array of signals used to abort waiting.
num_signals	Number of signals in the array.
ret_signal_index_ptr	Pointer to the returned signal index that caused the wait to abort. If a timeout occurred, CDI_OS_SIG_TIMEOUT is returned. This is an optional parameter. Pass NULL if you don't care.
item_ptr	Address where to copy the item from.

Returns: true if successful, otherwise false (queue is full and timeout expired or signal got set).

◆ GetDataItemFromListEntry()

static uint8_t * GetDataItemFromListEntry ( CdiSinglyLinkedListEntry * entry_item_ptr )

inlinestatic

Get pointer to the data buffer related to the linked list entry of the item.

Parameters

entry_item_ptr Pointer to queue item.

Returns: Pointer to item's data buffer.

◆ GetQueueItemFromItemDataPointer()

static QueueItem * GetQueueItemFromItemDataPointer ( const void * item_data_ptr )

inlinestatic

Get pointer to the item's parent object (QueueItem).

Parameters

item_data_ptr Pointer to object being queried.

Returns: Pointer to parent of object.

◆ QueueIncrease()

static bool QueueIncrease ( CdiQueueHandle handle_ptr )

static

Increases the size of a queue, if it is growable.

Parameters

handle_ptr Pointer to queue handle.

Returns: If successful true is returned, otherwise false is returned.

◆ WaitForSignals()

static bool WaitForSignals	(	CdiSinglyLinkedListEntry volatile	entry_change_ptr,
		CdiSinglyLinkedListEntry *	entry_static_ptr,
		CdiSignalType	wait_signal,
		int	timeout_ms,
		CdiSignalType *	cancel_wait_signal_array,
		int	num_signals,
		uint32_t *	ret_signal_index_ptr )

inlinestatic

Wait on either an empty or full queue. This is done by using the specified signal to wait for one of the queue read/write pointers to change. The wait can be aborted if any of the signals in the specified signal array get set.

Parameters

entry_change_ptr	Pointer to either the read or write pointer that is going to be changed outside the scope of this function. The contents of this pointer is made a volatile pointer to prevent the compiler from caching it in a register. It must be re-read from memory each time it is used in this function.
entry_static_ptr	Pointer to the read or write pointer that is not being changed.
wait_signal	Signal that is set when the address pointed to by entry_change_ptr changes.
timeout_ms	Maximume time to wait, in milliseconds.
cancel_wait_signal_array	Array of wait cancel signals.
num_signals	Number of signals in the signal array.
ret_signal_index_ptr	Address where to write the returned index value of the signal that was set.

Returns: Returns true if the wait_signal was set and the contents of the address pointed to by entry_change_ptr changed.

Data Structures

Macros

Functions

Detailed Description

Function Documentation

◆ AddEntriesToBuffers()

◆ CdiQueueCreate()

◆ CdiQueueDestroy()

◆ CdiQueueFlush()

◆ CdiQueueGetName()

◆ CdiQueueGetPopWaitSignal()

◆ CdiQueueGetPushWaitSignal()

◆ CdiQueueIsEmpty()

◆ CdiQueuePop()

◆ CdiQueuePopWait()

◆ CdiQueuePopWaitMultiple()

◆ CdiQueuePush()

◆ CdiQueuePushWait()

◆ CdiQueuePushWaitMultiple()

◆ GetDataItemFromListEntry()

◆ GetQueueItemFromItemDataPointer()

◆ QueueIncrease()

◆ WaitForSignals()