OS_Q Struct Reference

A message queue is an object that enables tasks and interrupt service routines to pend and post pointer sized messages. The pointer values typically point to some type of object or structure that contains the actual message or data. A queue functions as a fixed size First In First Out (FIFO) storage for 32-bit void pointers that can be used for communication between tasks. More...

#include <nbrtos.h>

Inherits OS_TASK_DLY_OBJ.

Public Member Functions
	OS_Q (void **pQueueStorage, uint8_t size)
	Create and initialize a queue object.
uint8_t	Init (void **pQueueStorage, uint8_t size)
	Set the queue object to its initial state.
uint8_t	Post (void *pItem)
	Post a message to the next available location in the queue.
uint8_t	PostFirst (void *pItem)
	Post a message to the head of the queue.
uint8_t	PostUnique (void *pItem)
	Post the specified message to the next available location in the queue, but only if the message is unique and does not exist anywhere else in the queue.
uint8_t	PostUniqueFirst (void *msg)
	Post the specified message to the first location in the queue, but only if the message is unique and does not exist anywhere else in the queue.
void *	Pend (uint32_t timeoutTicks, uint8_t &result)
	Wait the specified number of time ticks for some other task to post to the queue.
void *	Pend (TickTimeout &t, uint8_t &result)
	Wait the specified number of TickTimeout ticks for some other task to post to the queue.
void *	Pend (uint32_t timeoutTicks=WAIT_FOREVER)
	Wait the specified number of time ticks for some other task to post to the queue.
void *	PendUntil (uint32_t timeoutTime, uint8_t &result)
	Wait the specified TimeTicks value for some other task to post to the queue.
void *	PendNoWait (uint8_t &result)
	Checks if a message is available in the queue and returns immediately.
void *	PendNoWait ()
	Checks if a message is available in the queue and returns immediately.

Detailed Description

A message queue is an object that enables tasks and interrupt service routines to pend and post pointer sized messages. The pointer values typically point to some type of object or structure that contains the actual message or data. A queue functions as a fixed size First In First Out (FIFO) storage for 32-bit void pointers that can be used for communication between tasks.

A queue can be thought of as an array of void pointers, unlike a mailbox which can store only one void pointer. Access is controlled so that the queue can be safely utilized by multiple tasks. Tasks write to the queue using a Post function, and read from the queue using a Pend function.

The void pointer can represent anything, such as a pointer to a variable, object, string, or just used as a 32-bit value. How it is used is defined by the tasks that post and pend to it.

Note

If you need to store more than a simple value as with this OS_Q class, please refer to the OS_FIFO class which can store structures.

Constructor & Destructor Documentation

OS_Q()

OS_Q::OS_Q ( void ** pQueueStorage, uint8_t size )

inline

Create and initialize a queue object.

The queue storage must be allocated in your application. A pointer to the storage area is then passed to the queue constructor. For example,

#define MY_QUEUE_SIZE (20)           // Number of storage locations (void pointers) in the queue.
                                     //   In this case, 20.
void *myQueueData[MY_QUEUE_SIZE];    // Declare the array of void pointers and a pointer to the array
OS_Q myQ(myQueueData,MY_QUEUE_SIZE); // Create an instance of the queue

Parameters

pQueueStorage	A pointer to an array of (void *) pointers to hold queue messages.
size	The number of pointers the queue can store.

Member Function Documentation

Init()

uint8_t OS_Q::Init	(	void **	pQueueStorage,
		uint8_t	size )

Set the queue object to its initial state.

Parameters

pQueueStorage	A pointer to an array of (void *) pointers to hold queue messages.
size	The number of pointers the queue can store.

Returns

OS_NO_ERR on success, otherwise NBRTOS Error Codes

Pend() [1/3]

void * OS_Q::Pend	(	TickTimeout &	t,
		uint8_t &	result )

Wait the specified number of TickTimeout ticks for some other task to post to the queue.

Parameters

t	The number of system ticks to wait. A value of 0 will wait forever.
result	Reference to store the status of the function call, NBRTOS Error Codes. OS_NO_ERR if successful, OS_TIMEOUT if it timed out.

Return values

Message	If successful
NULL	If it timed out

See also

NBRTOS Error Codes, PendNoWait(), PendUntil()

Pend() [2/3]

void * OS_Q::Pend ( uint32_t timeoutTicks, uint8_t & result )

inline

Wait the specified number of time ticks for some other task to post to the queue.

Parameters

timeoutTicks	The number of system ticks to wait. A value of 0 will wait forever.
result	Reference to store the status of the function call, NBRTOS Error Codes. OS_NO_ERR if successful, OS_TIMEOUT if it timed out.

Return values

Message	If successful
NULL	If it timed out

See also

NBRTOS Error Codes, PendNoWait(), PendUntil()

Pend() [3/3]

void * OS_Q::Pend ( uint32_t timeoutTicks = WAIT_FOREVER )

inline

Wait the specified number of time ticks for some other task to post to the queue.

Parameters

timeoutTicks

The number of system ticks to wait. If no value is specified, it will wait forever.

Return values

Message	If successful
NULL	If it timed out

See also

NBRTOS Error Codes, PendNoWait(), PendUntil()

PendNoWait() [1/2]

void * OS_Q::PendNoWait ( )

inline

Checks if a message is available in the queue and returns immediately.

Return values

Message	If successful
NULL	If it timed out

See also

Pend(), PendUntil()

PendNoWait() [2/2]

void * OS_Q::PendNoWait

(

uint8_t &

result

)

Checks if a message is available in the queue and returns immediately.

Parameters

result

Reference to store the status of the function call, NBRTOS Error Codes. OS_NO_ERR if successful, OS_TIMEOUT if it timed out.

Return values

Message	If successful
NULL	If it timed out

See also

NBRTOS Error Codes, Pend(), PendUntil()

PendUntil()

void * OS_Q::PendUntil ( uint32_t timeoutTime, uint8_t & result )

inline

Wait the specified TimeTicks value for some other task to post to the queue.

Parameters

timeoutTime	The value of system TimeTicks to wait for
result	Reference to store the status of the function call, NBRTOS Error Codes. OS_NO_ERR if successful, OS_TIMEOUT if it timed out.

Return values

Message	If successful
NULL	If it timed out

See also

NBRTOS Error Codes, PendNoWait(), Pend()

Post()

uint8_t OS_Q::Post

(

void *

pItem

)

Post a message to the next available location in the queue.

Parameters

pItem

Message (void pointer) to post

Return values

OS_NO_ERR	If successful
OS_Q_FULL	If the queue is full, NBRTOS Error Codes

See also

PostFirst(), PostUnique(), Pend()

PostFirst()

uint8_t OS_Q::PostFirst

(

void *

pItem

)

Post a message to the head of the queue.

Parameters

pItem

Message (void pointer) to post

Return values

OS_NO_ERR	If successful
OS_Q_FULL	If the queue is full, NBRTOS Error Codes

See also

Post(), PostUniqueFirst(), Pend()

PostUnique()

uint8_t OS_Q::PostUnique

(

void *

pItem

)

Post the specified message to the next available location in the queue, but only if the message is unique and does not exist anywhere else in the queue.

Parameters

pItem

Message (void pointer) to post

Return values

OS_NO_ERR	If successful
OS_Q_EXISTS	If the message already exists in the queue NBRTOS Error Codes
OS_Q_FULL	If the queue is full NBRTOS Error Codes

See also

Post(), PostFirst(), Pend()

PostUniqueFirst()

uint8_t OS_Q::PostUniqueFirst

(

void *

msg

)

Post the specified message to the first location in the queue, but only if the message is unique and does not exist anywhere else in the queue.

Parameters

msg	Message (void pointer) to post

Return values

OS_NO_ERR	If successful
OS_Q_EXISTS	If the message already exists in the queue NBRTOS Error Codes
OS_Q_FULL	If the queue is full NBRTOS Error Codes

See also

Post(), PostFirst(), Pend()

---

The documentation for this struct was generated from the following file:

• nbrtos.h