Description

A blocking queue for inter-thread messaging.

Collaboration diagram for Ar::Queue:

Public Member Functions
	Queue ()
	Default constructor.

	Queue (const char name, void storage, unsigned elementSize, unsigned capacity)
	Constructor.

	~Queue ()
	Queue cleanup.

unsigned	getCount () const
	Returns the current number of elements in the queue.

const char *	getName () const
	Get the queue's name.

ar_status_t	init (const char name, void storage, unsigned elementSize, unsigned capacity)
	Queue initialiser. More...

bool	isEmpty () const
	Returns whether the queue is currently empty.

ar_status_t	receive (void *element, uint32_t timeout=kArInfiniteTimeout)
	Remove an item from the queue. More...

ar_status_t	send (const void *element, uint32_t timeout=kArInfiniteTimeout)
	Add an item to the queue. More...

Additional Inherited Members
Public Attributes inherited from ar_queue_t
unsigned	m_capacity
	Maximum number of elements the queue can hold.

unsigned	m_count
	Current number of elements in the queue.

uint8_t *	m_elements
	Pointer to element storage.

unsigned	m_elementSize
	Number of bytes occupied by each element.

unsigned	m_head
	Index of queue head.

const char *	m_name
	Name of the queue.

ar_list_t	m_receiveBlockedList
	List of threads blocked waiting to receive data.

ar_runloop_t *	m_runLoop
	Runloop the queue is bound to.

ar_runloop_queue_handler_t	m_runLoopHandler
	Handler function.

void *	m_runLoopHandlerParam
	User parameter for handler function.

ar_list_node_t	m_runLoopNode
	List node for the runloop's queue list.

ar_list_t	m_sendBlockedList
	List of threads blocked waiting to send.

unsigned	m_tail
	Index of queue tail.

Member Function Documentation

inline

Queue initialiser.

Parameters

name	The new queue's name.
storage	Pointer to a buffer used to store queue elements. The buffer must be at least elementSize * capacity bytes big.
elementSize	Size in bytes of each element in the queue.
capacity	The number of elements that the buffer pointed to by storage will hold.

Return values

kArSuccess The queue was initialised.

ar_status_t Ar::Queue::receive	(	void *	element,
		uint32_t	timeout = `kArInfiniteTimeout`
	)

inline

Remove an item from the queue.

Parameters

[out]	element
	timeout	The maximum number of milliseconds that the caller is willing to wait in a blocked state before an element is received. If this value is 0, or kArNoTimeout, then this method will return immediately if the queue is empty. Setting the timeout to kArInfiniteTimeout will cause the thread to wait forever for receive an element.

Return values

kArSuccess
kArQueueEmptyError

ar_status_t Ar::Queue::send	(	const void *	element,
		uint32_t	timeout = `kArInfiniteTimeout`
	)

inline

Add an item to the queue.

The caller will block if the queue is full.

Parameters

element	Pointer to the element to post to the queue. The element size was specified in the init() call.
timeout	The maximum number of milliseconds that the caller is willing to wait in a blocked state before the element can be sent. If this value is 0, or kArNoTimeout, then this method will return immediately if the queue is full. Setting the timeout to kArInfiniteTimeout will cause the thread to wait forever for a chance to send.

Return values

kArSuccess
kArQueueFullError