OS_MBOX Struct Reference

Single-message mailbox for passing one void-pointer value between tasks. More...

#include <nbrtos.h>

Inherits OS_TASK_DLY_OBJ.

Public Member Functions
	OS_MBOX ()
	Construct an empty mailbox (no initial message).
	OS_MBOX (void *msg)
	Construct a mailbox initialized with the specified message.
uint8_t	Init (void *msg=NULL)
	Reset the mailbox to its initial state with an optional message.
uint8_t	Post (void *msg)
	Post a message to the mailbox.
void *	Pend (uint32_t timeoutTicks, uint8_t &result)
	Wait for a message to be posted to the mailbox.
void *	Pend (TickTimeout &t, uint8_t &result)
	Wait for a message to be posted to the mailbox, using a TickTimeout.
void *	Pend (uint32_t timeoutTicks=WAIT_FOREVER)
	Wait for a message to be posted to the mailbox (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 the message from the mailbox without waiting.
void *	PendNoWait ()
	Retrieve the message from the mailbox without waiting (no result code).

Detailed Description

Single-message mailbox for passing one void-pointer value between tasks.

A mailbox holds exactly one void-pointer message. When a task posts a message the mailbox becomes full; no further posts are accepted until another task pends (reads) the message, or the mailbox is re-initialized.

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

Note

For multiple messages, use OS_Q. For type safety, use TEMPL_MBOX.

See also

OS_Q, OS_SEM, TEMPL_MBOX

---

Expand for Example Usage

Examples

Signal Data Availability

OS_MBOX gMbox;
int gData;
 
void ProducerTask(void *pd)
{
    gData = 100;
    gMbox.Post((void *)&gData);
}
 
void ConsumerTask(void *pd)
{
    uint8_t err;
    int *pVal = (int *)gMbox.Pend(5 * TICKS_PER_SECOND, err);
    if (err == OS_NO_ERR) { iprintf("Got %d\r\n", *pVal); }
}

---

Constructor & Destructor Documentation

OS_MBOX() [1/2]

OS_MBOX::OS_MBOX ( )

inline

Construct an empty mailbox (no initial message).

See also

Init()

OS_MBOX() [2/2]

OS_MBOX::OS_MBOX ( void * msg )

inline

Construct a mailbox initialized with the specified message.

Parameters

msg	Initial message to store in the mailbox.

See also

Init()

Member Function Documentation

Init()

uint8_t OS_MBOX::Init

(

void *

msg = NULL

)

Reset the mailbox to its initial state with an optional message.

Parameters

msg	Initial message to store, or NULL (default) for an empty mailbox.

Return values

OS_NO_ERR

If successful.

See also

NBRTOS Error Codes

Pend() [1/3]

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

Wait for a message to be posted to the mailbox, 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_MBOX::Pend ( uint32_t timeoutTicks, uint8_t & result )

inline

Wait for a message to be posted to the mailbox.

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_MBOX::Pend ( uint32_t timeoutTicks = WAIT_FOREVER )

inline

Wait for a message to be posted to the mailbox (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_MBOX::PendNoWait ( )

inline

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

Returns

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

See also

Pend(), PendUntil()

PendNoWait() [2/2]

void * OS_MBOX::PendNoWait

(

uint8_t &

result

)

Retrieve the message from the mailbox 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 mailbox was empty.

See also

Pend(), PendUntil(), NBRTOS Error Codes

PendUntil()

void * OS_MBOX::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_MBOX::Post

(

void *

msg

)

Post a message to the mailbox.

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

Parameters

msg	The message pointer to store.

Return values

OS_NO_ERR	If the message was posted.
OS_MBOX_FULL	If the mailbox already contains a message.

See also

Pend(), PendNoWait(), NBRTOS Error Codes

---

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

• nbrtos.h