cdi_queue_api.h File Reference

The declarations in this header file correspond to the definitions in queue.c. More...

#include <stdbool.h>
#include <stdint.h>
#include "cdi_os_api.h"

Go to the source code of this file.

Data Structures
struct	CdiQueueCbData
	A structure of this type is passed as the parameter to CdiQueueCallback(). It contains the state of a single queue read or write operation. More...

Macros
#define	CDI_FIXED_QUEUE_SIZE   (0)
	Queue cannot dynamically grow.

Typedefs
typedef struct CdiQueueState *	CdiQueueHandle
	Type used as the handle (pointer to an opaque structure) for a queue. Each handle represents a instance of a queue.
typedef struct CdiSinglyLinkedListEntry	CdiSinglyLinkedListEntry
	Forward declaration of CdiSinglyLinkedListEntry defined in singly_linked_list_api.h.
typedef void(*	CdiQueueCallback) (const CdiQueueCbData *data_ptr)

Enumerations
enum	CdiQueueSignalMode {   kQueueSignalNone , kQueueSignalPopWait , kQueueSignalPushWait , kQueueSignalPopPushWait ,   kQueueSignalModeMask = 0x7 , kQueueMultipleWritersFlag = 0x08 }
	This enumeration is used in the internal queue structure to indicate the type of OS signals, if any, to use in the queue. More...

Functions
CDI_INTERFACE 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.
CDI_INTERFACE bool	CdiQueuePop (CdiQueueHandle handle, void *item_dest_ptr)
CDI_INTERFACE bool	CdiQueuePopWait (CdiQueueHandle handle, int timeout_ms, CdiSignalType abort_wait_signal, void *item_dest_ptr)
CDI_INTERFACE 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)
CDI_INTERFACE bool	CdiQueuePush (CdiQueueHandle handle, const void *item_ptr)
CDI_INTERFACE bool	CdiQueuePushWait (CdiQueueHandle handle, int timeout_ms, CdiSignalType abort_wait_signal, const void *item_ptr)
CDI_INTERFACE 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)
CDI_INTERFACE bool	CdiQueueIsEmpty (CdiQueueHandle handle)
CDI_INTERFACE void	CdiQueueFlush (CdiQueueHandle handle)
CDI_INTERFACE CdiSignalType	CdiQueueGetPopWaitSignal (CdiQueueHandle handle)
CDI_INTERFACE CdiSignalType	CdiQueueGetPushWaitSignal (CdiQueueHandle handle)
CDI_INTERFACE const char *	CdiQueueGetName (CdiQueueHandle handle)
CDI_INTERFACE void	CdiQueueDestroy (CdiQueueHandle handle)

Detailed Description

The declarations in this header file correspond to the definitions in queue.c.

Typedef Documentation

CdiQueueCallback

typedef void(* CdiQueueCallback) (const CdiQueueCbData *data_ptr)

Prototype of the queue debug callback function.

This callback function is invoked whenever an item is written to or read from the queue.

Parameters

data_ptr

A pointer to an CdiQueueCbData structure.

Enumeration Type Documentation

CdiQueueSignalMode

enum CdiQueueSignalMode

This enumeration is used in the internal queue structure to indicate the type of OS signals, if any, to use in the queue.

Enumerator
kQueueSignalNone	In this mode signals are not used.
kQueueSignalPopWait	In this mode, use CdiQueuePopWait() to block and wait on an empty queue. Use CdiQueueGetPopWaitSignal() to directly get the signal.
kQueueSignalPushWait	In this mode, use CdiQueuePushWait() to block and wait on a full queue. Use CdiQueueGetPushWaitSignal() to directly get the signal.
kQueueSignalPopPushWait	In this mode, signals are enabled for both push and pop operations (see above).
kQueueSignalModeMask	Mask that only includes the main mode options. Used for ignoring option flags.
kQueueMultipleWritersFlag	Optional flag to add locking for thread safe pushing into the queue.

Function Documentation

CdiQueueCreate()

CDI_INTERFACE 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()

CDI_INTERFACE void CdiQueueDestroy

(

CdiQueueHandle

handle

)

Destroy a queue.

Parameters

handle

Queue handle.

CdiQueueFlush()

CDI_INTERFACE 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()

CDI_INTERFACE const char * CdiQueueGetName

(

CdiQueueHandle

handle

)

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

Parameters

handle

Queue handle.

CdiQueueGetPopWaitSignal()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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).