OS_Q Struct Reference

Fixed-size FIFO message queue for passing void-pointer messages between tasks. More...

#include <nbrtos.h>

Inherits OS_TASK_DLY_OBJ.

Public Member Functions
	OS_Q (void **pQueueStorage, uint8_t size)
	Construct and initialize the queue with the provided storage.
uint8_t	Init (void **pQueueStorage, uint8_t size)
	Reset the queue to its initial (empty) state with the given storage.
uint8_t	Post (void *pItem)
	Post a message to the tail of the queue.
uint8_t	PostFirst (void *pItem)
	Post a message to the head of the queue (priority insertion).
uint8_t	PostUnique (void *pItem)
	Post a message to the tail, but only if it is not already in the queue.
uint8_t	PostUniqueFirst (void *msg)
	Post a message to the head, but only if it is not already in the queue.
void *	Pend (uint32_t timeoutTicks, uint8_t &result)
	Wait for a message to be posted to the queue.
void *	Pend (TickTimeout &t, uint8_t &result)
	Wait for a message to be posted to the queue, using a TickTimeout.
void *	Pend (uint32_t timeoutTicks=WAIT_FOREVER)
	Wait for a message to be posted to the queue (no result code).
void *	PendUntil (uint32_t timeoutTime, uint8_t &result)
	Wait until an absolute TimeTick value for a message to be posted.
void *	PendNoWait (uint8_t &result)
	Retrieve a message from the queue without waiting.
void *	PendNoWait ()
	Retrieve a message from the queue without waiting (no result code).

Detailed Description

Fixed-size FIFO message queue for passing void-pointer messages between tasks.

An OS_Q stores an array of void pointers in a circular buffer. Tasks write messages with Post() and read them with Pend(). The queue is thread-safe and supports blocking waits with configurable timeouts. Messages are delivered in FIFO order unless PostFirst() is used.

The void pointer can represent anything: a pointer to an object, a string, or a simple integer value cast to void *. The interpretation is defined by the posting and pending tasks.

Note

For passing entire structures (not just pointers), use OS_FIFO instead. For type-safe usage without manual casts, use TEMPL_Q.

See also

OS_MBOX, OS_FIFO, TEMPL_Q

---

Expand for Example Usage

Examples

Create and Use a Message Queue

#define Q_SIZE 10
void *qStorage[Q_SIZE];
OS_Q  myQueue(qStorage, Q_SIZE);
 
void ProducerTask(void *pd)
{
    static int value = 42;
    myQueue.Post((void *)&value);
}
 
void ConsumerTask(void *pd)
{
    uint8_t err;
    void *msg = myQueue.Pend(5 * TICKS_PER_SECOND, err);
    if (err == OS_NO_ERR)
    {
        int *pVal = (int *)msg;
        iprintf("Received: %d\r\n", *pVal);
    }
}

---

Constructor & Destructor Documentation

OS_Q()

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

inline

Construct and initialize the queue with the provided storage.

You must allocate an array of void pointers in your application to serve as the queue's backing store.

Parameters

pQueueStorage	Pointer to an array of void pointers for message storage.
size	Number of entries the storage array can hold.

See also

Init()

Member Function Documentation

Init()

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

Reset the queue to its initial (empty) state with the given storage.

Parameters

pQueueStorage	Pointer to an array of void pointers for message storage.
size	Number of entries the storage array can hold.

Return values

OS_NO_ERR

If successful.

See also

NBRTOS Error Codes

Pend() [1/3]

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

Wait for a message to be posted to the queue, using a TickTimeout.

Parameters

t	TickTimeout controlling the maximum wait duration.
result	Receives OS_NO_ERR on success or OS_TIMEOUT on timeout.

Returns

The message pointer, or NULL on timeout.

See also

PendNoWait(), PendUntil(), NBRTOS Error Codes

Pend() [2/3]

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

inline

Wait for a message to be posted to the queue.

Parameters

timeoutTicks	Maximum system ticks to wait. A value of 0 waits forever.
result	Receives OS_NO_ERR on success or OS_TIMEOUT on timeout.

Returns

The message pointer, or NULL on timeout.

See also

PendNoWait(), PendUntil(), NBRTOS Error Codes

Pend() [3/3]

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

inline

Wait for a message to be posted to the queue (no result code).

Parameters

timeoutTicks

Maximum system ticks to wait. A value of 0 (default) waits forever.

Returns

The message pointer, or NULL on timeout.

See also

PendNoWait(), PendUntil(), NBRTOS Error Codes

PendNoWait() [1/2]

void * OS_Q::PendNoWait ( )

inline

Retrieve a message from the queue without waiting (no result code).

Returns

The message pointer, or NULL if the queue was empty.

See also

Pend(), PendUntil()

PendNoWait() [2/2]

void * OS_Q::PendNoWait

(

uint8_t &

result

)

Retrieve a message from the queue without waiting.

Parameters

result

Receives OS_NO_ERR if a message was available, or OS_TIMEOUT if empty.

Returns

The message pointer, or NULL if the queue was empty.

See also

Pend(), PendUntil(), NBRTOS Error Codes

PendUntil()

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

inline

Wait until an absolute TimeTick value for a message to be posted.

Parameters

timeoutTime	Absolute system TimeTick value at which to stop waiting.
result	Receives OS_NO_ERR on success or OS_TIMEOUT on timeout.

Returns

The message pointer, or NULL on timeout.

See also

Pend(), PendNoWait(), NBRTOS Error Codes

Post()

uint8_t OS_Q::Post

(

void *

pItem

)

Post a message to the tail of the queue.

If a higher-priority task is pending on this queue, it will be released.

Parameters

pItem

The void-pointer message to post.

Return values

OS_NO_ERR	If successful.
OS_Q_FULL	If the queue has no room.

See also

PostFirst(), PostUnique(), Pend(), NBRTOS Error Codes

PostFirst()

uint8_t OS_Q::PostFirst

(

void *

pItem

)

Post a message to the head of the queue (priority insertion).

Parameters

pItem

The void-pointer message to post at the head.

Return values

OS_NO_ERR	If successful.
OS_Q_FULL	If the queue has no room.

See also

Post(), PostUniqueFirst(), Pend(), NBRTOS Error Codes

PostUnique()

uint8_t OS_Q::PostUnique

(

void *

pItem

)

Post a message to the tail, but only if it is not already in the queue.

Performs a linear scan of the queue to verify uniqueness before posting.

Parameters

pItem

The void-pointer message to post.

Return values

OS_NO_ERR	If the message was posted.
OS_Q_EXISTS	If the message is already present in the queue.
OS_Q_FULL	If the queue has no room.

See also

Post(), PostFirst(), NBRTOS Error Codes

PostUniqueFirst()

uint8_t OS_Q::PostUniqueFirst

(

void *

msg

)

Post a message to the head, but only if it is not already in the queue.

Parameters

msg	The void-pointer message to post at the head.

Return values

OS_NO_ERR	If the message was posted.
OS_Q_EXISTS	If the message is already present in the queue.
OS_Q_FULL	If the queue has no room.

See also

Post(), PostFirst(), NBRTOS Error Codes

---

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

• nbrtos.h