Collaboration diagram for Mailboxes:

Detailed Description

Asynchronous messages.

Operation mode

A mailbox is an asynchronous communication mechanism.
Operations defined for mailboxes:

Post: Posts a message on the mailbox in FIFO order.
Post Ahead: Posts a message on the mailbox with urgent priority.
Fetch: A message is fetched from the mailbox and removed from the queue.
Reset: The mailbox is emptied and all the stored messages are lost.

A message is a variable of type msg_t that is guaranteed to have the same size of and be compatible with (data) pointers (anyway an explicit cast is needed). If larger messages need to be exchanged then a pointer to a structure can be posted in the mailbox but the posting side has no predefined way to know when the message has been processed. A possible approach is to allocate memory (from a memory pool for example) from the posting side and free it on the fetching side. Another approach is to set a "done" flag into the structure pointed by the message.

Precondition: In order to use the mailboxes APIs the CH_CFG_USE_MAILBOXES option must be enabled in chconf.h.

Note: Compatible with RT and NIL.

Macros
#define	_MAILBOX_DATA(name, buffer, size)
	Data part of a static mailbox initializer. More...

#define	MAILBOX_DECL(name, buffer, size) mailbox_t name = _MAILBOX_DATA(name, buffer, size)
	Static mailbox initializer. More...

Data Structures
struct	mailbox_t
	Structure representing a mailbox object. More...

Functions
void	chMBObjectInit (mailbox_t mbp, msg_t buf, size_t n)
	Initializes a `mailbox_t` object. More...

void	chMBReset (mailbox_t *mbp)
	Resets a `mailbox_t` object. More...

void	chMBResetI (mailbox_t *mbp)
	Resets a `mailbox_t` object. More...

msg_t	chMBPostTimeout (mailbox_t *mbp, msg_t msg, sysinterval_t timeout)
	Posts a message into a mailbox. More...

msg_t	chMBPostTimeoutS (mailbox_t *mbp, msg_t msg, sysinterval_t timeout)
	Posts a message into a mailbox. More...

msg_t	chMBPostI (mailbox_t *mbp, msg_t msg)
	Posts a message into a mailbox. More...

msg_t	chMBPostAheadTimeout (mailbox_t *mbp, msg_t msg, sysinterval_t timeout)
	Posts an high priority message into a mailbox. More...

msg_t	chMBPostAheadTimeoutS (mailbox_t *mbp, msg_t msg, sysinterval_t timeout)
	Posts an high priority message into a mailbox. More...

msg_t	chMBPostAheadI (mailbox_t *mbp, msg_t msg)
	Posts an high priority message into a mailbox. More...

msg_t	chMBFetchTimeout (mailbox_t mbp, msg_t msgp, sysinterval_t timeout)
	Retrieves a message from a mailbox. More...

msg_t	chMBFetchTimeoutS (mailbox_t mbp, msg_t msgp, sysinterval_t timeout)
	Retrieves a message from a mailbox. More...

msg_t	chMBFetchI (mailbox_t mbp, msg_t msgp)
	Retrieves a message from a mailbox. More...

static size_t	chMBGetSizeI (const mailbox_t *mbp)
	Returns the mailbox buffer size as number of messages. More...

static size_t	chMBGetUsedCountI (const mailbox_t *mbp)
	Returns the number of used message slots into a mailbox. More...

static size_t	chMBGetFreeCountI (const mailbox_t *mbp)
	Returns the number of free message slots into a mailbox. More...

static msg_t	chMBPeekI (const mailbox_t *mbp)
	Returns the next message in the queue without removing it. More...

static void	chMBResumeX (mailbox_t *mbp)
	Terminates the reset state. More...

Macro Definition Documentation

#define _MAILBOX_DATA	(	name,
		buffer,
		size
	)

Value:

{                                 \
  (msg_t *)(buffer),                                                        \
  (msg_t *)(buffer) + size,                                                 \
  (msg_t *)(buffer),                                                        \
  (msg_t *)(buffer),                                                        \
  (size_t)0,                                                                \
  false,                                                                    \
  _THREADS_QUEUE_DATA(name.qw),                                             \
  _THREADS_QUEUE_DATA(name.qr),                                             \
}

Data part of a static mailbox initializer.

This macro should be used when statically initializing a mailbox that is part of a bigger structure.

Parameters

[in]	name	the name of the mailbox variable
[in]	buffer	pointer to the mailbox buffer array of `msg_t`
[in]	size	number of `msg_t` elements in the buffer array

Definition at line 78 of file chmboxes.h.

#define MAILBOX_DECL	(	name,
		buffer,
		size
	)	mailbox_t name = _MAILBOX_DATA(name, buffer, size)

Static mailbox initializer.

Statically initialized mailboxes require no explicit initialization using chMBObjectInit().

Parameters

[in]	name	the name of the mailbox variable
[in]	buffer	pointer to the mailbox buffer array of `msg_t`
[in]	size	number of `msg_t` elements in the buffer array

Definition at line 98 of file chmboxes.h.

Function Documentation

void chMBObjectInit	(	mailbox_t *	mbp,
		msg_t *	buf,
		size_t	n
	)

Initializes a mailbox_t object.

Parameters

[out]	mbp	the pointer to the `mailbox_t` structure to be initialized
[in]	buf	pointer to the messages buffer as an array of `msg_t`
[in]	n	number of elements in the buffer array

Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 87 of file chmboxes.c.

References mailbox_t::buffer, chDbgCheck, chThdQueueObjectInit, mailbox_t::cnt, mailbox_t::qr, mailbox_t::qw, mailbox_t::rdptr, mailbox_t::reset, mailbox_t::top, and mailbox_t::wrptr.

Referenced by chFactoryCreateMailbox(), and chFifoObjectInitAligned().

void chMBReset ( mailbox_t * mbp )

Resets a mailbox_t object.

All the waiting threads are resumed with status MSG_RESET and the queued messages are lost.

Postcondition: The mailbox is in reset state, all operations will fail and return MSG_RESET until the mailbox is enabled again using chMBResumeX().

Parameters

[in] mbp the pointer to an initialized mailbox_t object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 113 of file chmboxes.c.

References chMBResetI(), chSchRescheduleS(), chSysLock, and chSysUnlock.

Here is the call graph for this function:

void chMBResetI ( mailbox_t * mbp )

Resets a mailbox_t object.

All the waiting threads are resumed with status MSG_RESET and the queued messages are lost.

Postcondition: The mailbox is in reset state, all operations will fail and return MSG_RESET until the mailbox is enabled again using chMBResumeX().

Parameters

[in] mbp the pointer to an initialized mailbox_t object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 133 of file chmboxes.c.

References mailbox_t::buffer, chDbgCheck, chThdDequeueAllI(), mailbox_t::cnt, MSG_RESET, mailbox_t::qr, mailbox_t::qw, mailbox_t::rdptr, mailbox_t::reset, and mailbox_t::wrptr.

Referenced by chMBReset().

Here is the call graph for this function:

msg_t chMBPostTimeout	(	mailbox_t *	mbp,
		msg_t	msg,
		sysinterval_t	timeout
	)

Posts a message into a mailbox.

The invoking thread waits until a empty slot in the mailbox becomes available or the specified time runs out.

Parameters

[in]	mbp	the pointer to an initialized `mailbox_t` object
[in]	msg	the message to be posted on the mailbox
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: The operation status.

Return values

MSG_OK	if a message has been correctly posted.
MSG_RESET	if the mailbox has been reset.
MSG_TIMEOUT	if the operation has timed out.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 165 of file chmboxes.c.

References chMBPostTimeoutS(), chSysLock, and chSysUnlock.

Referenced by chFifoSendObject().

Here is the call graph for this function:

msg_t chMBPostTimeoutS	(	mailbox_t *	mbp,
		msg_t	msg,
		sysinterval_t	timeout
	)

Posts a message into a mailbox.

The invoking thread waits until a empty slot in the mailbox becomes available or the specified time runs out.

Parameters

[in]	mbp	the pointer to an initialized `mailbox_t` object
[in]	msg	the message to be posted on the mailbox
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: The operation status.

Return values

MSG_OK	if a message has been correctly posted.
MSG_RESET	if the mailbox has been reset.
MSG_TIMEOUT	if the operation has timed out.

Function Class:This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 194 of file chmboxes.c.

References mailbox_t::buffer, chDbgCheck, chMBGetFreeCountI(), chSchRescheduleS(), chThdDequeueNextI(), chThdEnqueueTimeoutS(), mailbox_t::cnt, MSG_OK, MSG_RESET, mailbox_t::qr, mailbox_t::qw, mailbox_t::reset, mailbox_t::top, and mailbox_t::wrptr.

Referenced by chFifoSendObjectS(), and chMBPostTimeout().

Here is the call graph for this function:

msg_t chMBPostI	(	mailbox_t *	mbp,
		msg_t	msg
	)

Posts a message into a mailbox.

This variant is non-blocking, the function returns a timeout condition if the queue is full.

Parameters

[in]	mbp	the pointer to an initialized `mailbox_t` object
[in]	msg	the message to be posted on the mailbox

Returns: The operation status.

Return values

MSG_OK	if a message has been correctly posted.
MSG_RESET	if the mailbox has been reset.
MSG_TIMEOUT	if the mailbox is full and the message cannot be posted.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 243 of file chmboxes.c.

References mailbox_t::buffer, chDbgCheck, chMBGetFreeCountI(), chThdDequeueNextI(), mailbox_t::cnt, MSG_OK, MSG_RESET, MSG_TIMEOUT, mailbox_t::qr, mailbox_t::reset, mailbox_t::top, and mailbox_t::wrptr.

Referenced by chFifoSendObjectI().

Here is the call graph for this function:

msg_t chMBPostAheadTimeout	(	mailbox_t *	mbp,
		msg_t	msg,
		sysinterval_t	timeout
	)

Posts an high priority message into a mailbox.

The invoking thread waits until a empty slot in the mailbox becomes available or the specified time runs out.

Parameters

[in]	mbp	the pointer to an initialized `mailbox_t` object
[in]	msg	the message to be posted on the mailbox
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: The operation status.

Return values

MSG_OK	if a message has been correctly posted.
MSG_RESET	if the mailbox has been reset.
MSG_TIMEOUT	if the operation has timed out.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 290 of file chmboxes.c.

References chMBPostAheadTimeoutS(), chSysLock, and chSysUnlock.

Referenced by chFifoSendObjectAhead().

Here is the call graph for this function:

msg_t chMBPostAheadTimeoutS	(	mailbox_t *	mbp,
		msg_t	msg,
		sysinterval_t	timeout
	)

Posts an high priority message into a mailbox.

The invoking thread waits until a empty slot in the mailbox becomes available or the specified time runs out.

Parameters

[in]	mbp	the pointer to an initialized `mailbox_t` object
[in]	msg	the message to be posted on the mailbox
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: The operation status.

Return values

MSG_OK	if a message has been correctly posted.
MSG_RESET	if the mailbox has been reset.
MSG_TIMEOUT	if the operation has timed out.

Function Class:This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 319 of file chmboxes.c.

References mailbox_t::buffer, chDbgCheck, chMBGetFreeCountI(), chSchRescheduleS(), chThdDequeueNextI(), chThdEnqueueTimeoutS(), mailbox_t::cnt, MSG_OK, MSG_RESET, mailbox_t::qr, mailbox_t::qw, mailbox_t::rdptr, mailbox_t::reset, and mailbox_t::top.

Referenced by chFifoSendObjectAheadS(), and chMBPostAheadTimeout().

Here is the call graph for this function:

msg_t chMBPostAheadI	(	mailbox_t *	mbp,
		msg_t	msg
	)

Posts an high priority message into a mailbox.

This variant is non-blocking, the function returns a timeout condition if the queue is full.

Parameters

[in]	mbp	the pointer to an initialized `mailbox_t` object
[in]	msg	the message to be posted on the mailbox

Returns: The operation status.

Return values

MSG_OK	if a message has been correctly posted.
MSG_RESET	if the mailbox has been reset.
MSG_TIMEOUT	if the mailbox is full and the message cannot be posted.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 368 of file chmboxes.c.

References mailbox_t::buffer, chDbgCheck, chMBGetFreeCountI(), chThdDequeueNextI(), mailbox_t::cnt, MSG_OK, MSG_RESET, MSG_TIMEOUT, mailbox_t::qr, mailbox_t::rdptr, mailbox_t::reset, and mailbox_t::top.

Referenced by chFifoSendObjectAheadI().

Here is the call graph for this function:

msg_t chMBFetchTimeout	(	mailbox_t *	mbp,
		msg_t *	msgp,
		sysinterval_t	timeout
	)

Retrieves a message from a mailbox.

The invoking thread waits until a message is posted in the mailbox or the specified time runs out.

Parameters

[in]	mbp	the pointer to an initialized `mailbox_t` object
[out]	msgp	pointer to a message variable for the received message
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: The operation status.

Return values

MSG_OK	if a message has been correctly fetched.
MSG_RESET	if the mailbox has been reset.
MSG_TIMEOUT	if the operation has timed out.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 415 of file chmboxes.c.

References chMBFetchTimeoutS(), chSysLock, and chSysUnlock.

Referenced by chFifoReceiveObjectTimeout().

Here is the call graph for this function:

msg_t chMBFetchTimeoutS	(	mailbox_t *	mbp,
		msg_t *	msgp,
		sysinterval_t	timeout
	)

Retrieves a message from a mailbox.

The invoking thread waits until a message is posted in the mailbox or the specified time runs out.

Parameters

[in]	mbp	the pointer to an initialized `mailbox_t` object
[out]	msgp	pointer to a message variable for the received message
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: The operation status.

Return values

MSG_OK	if a message has been correctly fetched.
MSG_RESET	if the mailbox has been reset.
MSG_TIMEOUT	if the operation has timed out.

Function Class:This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 444 of file chmboxes.c.

References mailbox_t::buffer, chDbgCheck, chMBGetUsedCountI(), chSchRescheduleS(), chThdDequeueNextI(), chThdEnqueueTimeoutS(), mailbox_t::cnt, MSG_OK, MSG_RESET, mailbox_t::qr, mailbox_t::qw, mailbox_t::rdptr, mailbox_t::reset, and mailbox_t::top.

Referenced by chFifoReceiveObjectTimeoutS(), and chMBFetchTimeout().

Here is the call graph for this function:

msg_t chMBFetchI	(	mailbox_t *	mbp,
		msg_t *	msgp
	)

Retrieves a message from a mailbox.

This variant is non-blocking, the function returns a timeout condition if the queue is empty.

Parameters

[in]	mbp	the pointer to an initialized `mailbox_t` object
[out]	msgp	pointer to a message variable for the received message

Returns: The operation status.

Return values

MSG_OK	if a message has been correctly fetched.
MSG_RESET	if the mailbox has been reset.
MSG_TIMEOUT	if the mailbox is empty and a message cannot be fetched.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 493 of file chmboxes.c.

References mailbox_t::buffer, chDbgCheck, chMBGetUsedCountI(), chThdDequeueNextI(), mailbox_t::cnt, MSG_OK, MSG_RESET, MSG_TIMEOUT, mailbox_t::qw, mailbox_t::rdptr, mailbox_t::reset, and mailbox_t::top.

Referenced by chFifoReceiveObjectI().

Here is the call graph for this function:

static size_t chMBGetSizeI ( const mailbox_t * mbp )

inlinestatic

Returns the mailbox buffer size as number of messages.

Parameters

[in] mbp the pointer to an initialized mailbox_t object

Returns: The size of the mailbox.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 136 of file chmboxes.h.

References mailbox_t::buffer, and mailbox_t::top.

Referenced by chMBGetFreeCountI().

static size_t chMBGetUsedCountI ( const mailbox_t * mbp )

inlinestatic

Returns the number of used message slots into a mailbox.

Parameters

[in] mbp the pointer to an initialized mailbox_t object

Returns: The number of queued messages.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 152 of file chmboxes.h.

References mailbox_t::cnt.

Referenced by chMBFetchI(), chMBFetchTimeoutS(), and chMBGetFreeCountI().

static size_t chMBGetFreeCountI ( const mailbox_t * mbp )

inlinestatic

Returns the number of free message slots into a mailbox.

Parameters

[in] mbp the pointer to an initialized mailbox_t object

Returns: The number of empty message slots.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 167 of file chmboxes.h.

References chMBGetSizeI(), and chMBGetUsedCountI().

Referenced by chMBPostAheadI(), chMBPostAheadTimeoutS(), chMBPostI(), and chMBPostTimeoutS().

Here is the call graph for this function:

static msg_t chMBPeekI ( const mailbox_t * mbp )

inlinestatic

Returns the next message in the queue without removing it.

Precondition: A message must be waiting in the queue for this function to work or it would return garbage. The correct way to use this macro is to use chMBGetUsedCountI() and then use this macro, all within a lock state.

Parameters

[in] mbp the pointer to an initialized mailbox_t object

Returns: The next message in queue.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 186 of file chmboxes.h.

References mailbox_t::rdptr.

static void chMBResumeX ( mailbox_t * mbp )

inlinestatic

Terminates the reset state.

Parameters

[in] mbp the pointer to an initialized mailbox_t object

Function Class:This is an X-Class API, this function can be invoked from any context.

Definition at line 200 of file chmboxes.h.

References mailbox_t::reset.

Detailed Description

Operation mode

Macros

Data Structures

Functions

Macro Definition Documentation

Function Documentation