Mailboxes [Synchronization]

Collaboration diagram for Mailboxes:

---

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 as 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.
In order to use the mailboxes APIs the CH_USE_MAILBOXES option must be enabled in chconf.h.

Defines
#define	chMBSize(mbp)   ((mbp)->mb_top - (mbp)->mb_buffer)
	Returns the mailbox buffer size.
#define	chMBGetEmpty(mbp)   chSemGetCounterI(&(mbp)->mb_emptysem)
	Returns the free space into the mailbox.
#define	chMBGetFull(mbp)   chSemGetCounterI(&(mbp)->mb_fullsem)
	Returns the number of messages into the mailbox.
#define	chMBPeek(mbp)   (*(mbp)->mb_rdptr)
	Returns the next message in the queue without removing it.
#define	_MAILBOX_DATA(name, buffer, size)
	Data part of a static mailbox initializer.
#define	MAILBOX_DECL(name, buffer, size)   Mailbox name = _MAILBOX_DATA(name, buffer, size)
	Static mailbox initializer.
Functions
void	chMBInit (Mailbox *mbp, msg_t *buf, cnt_t n)
	Initializes a Mailbox object.
void	chMBReset (Mailbox *mbp)
	Resets a Mailbox object.
msg_t	chMBPost (Mailbox *mbp, msg_t msg, systime_t time)
	Posts a message into a mailbox.
msg_t	chMBPostS (Mailbox *mbp, msg_t msg, systime_t time)
	Posts a message into a mailbox.
msg_t	chMBPostAhead (Mailbox *mbp, msg_t msg, systime_t time)
	Posts an high priority message into a mailbox.
msg_t	chMBPostAheadS (Mailbox *mbp, msg_t msg, systime_t time)
	Posts an high priority message into a mailbox.
msg_t	chMBFetch (Mailbox *mbp, msg_t *msgp, systime_t time)
	Retrieves a message from a mailbox.
msg_t	chMBFetchS (Mailbox *mbp, msg_t *msgp, systime_t time)
	Retrieves a message from a mailbox.

---

Define Documentation

#define chMBSize

(

mbp

)

((mbp)->mb_top - (mbp)->mb_buffer)

Returns the mailbox buffer size.

Parameters:

[in]

mbp

the pointer to an initialized Mailbox object

Definition at line 80 of file chmboxes.h.

#define chMBGetEmpty

(

mbp

)

chSemGetCounterI(&(mbp)->mb_emptysem)

Returns the free space into the mailbox.

Note:

Can be invoked in any system state but if invoked out of a locked state then the returned value may change after reading.

The returned value can be less than zero when there are waiting threads on the internal semaphore.

Parameters:

[in]

mbp

the pointer to an initialized Mailbox object

Returns:

The number of empty message slots.

Definition at line 93 of file chmboxes.h.

#define chMBGetFull

(

mbp

)

chSemGetCounterI(&(mbp)->mb_fullsem)

Returns the number of messages into the mailbox.

Note:

Can be invoked in any system state but if invoked out of a locked state then the returned value may change after reading.

The returned value can be less than zero when there are waiting threads on the internal semaphore.

Parameters:

[in]

mbp

the pointer to an initialized Mailbox object

Returns:

The number of queued messages.

Definition at line 105 of file chmboxes.h.

#define chMBPeek

(

mbp

)

(*(mbp)->mb_rdptr)

Returns the next message in the queue without removing it.

Note:

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 chMBGetFull() and then use this macro, all within a lock state.

Definition at line 114 of file chmboxes.h.

#define _MAILBOX_DATA	(		name,
			buffer,
			size
	)

Value:

{                             \
  (msg_t *)(buffer),                                                    \
  (msg_t *)(buffer) + size,                                             \
  (msg_t *)(buffer),                                                    \
  (msg_t *)(buffer),                                                    \
  _SEMAPHORE_DATA(name.mb_fullsem, 0),                                  \
  _SEMAPHORE_DATA(name.mb_emptysem, size),                              \
}

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 area
[in]	size	size of the mailbox buffer area

Definition at line 125 of file chmboxes.h.

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

Static mailbox initializer.

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

Parameters:

[in]	name	the name of the mailbox variable
[in]	buffer	pointer to the mailbox buffer area
[in]	size	size of the mailbox buffer area

Definition at line 143 of file chmboxes.h.

---

Function Documentation

void chMBInit	(	Mailbox *	mbp,
		msg_t *	buf,
		cnt_t	n
	)

Initializes a Mailbox object.

Parameters:

[out]	mbp	the pointer to the Mailbox structure to be initialized
[in]	buf	the circular messages buffer
[in]	n	the buffer size as number of msg_t

Definition at line 69 of file chmboxes.c.

References chDbgCheck, and chSemInit().

Here is the call graph for this function:

void chMBReset

(

Mailbox *

mbp

)

Resets a Mailbox object.

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

Parameters:

[in]

mbp

the pointer to an initialized Mailbox object

Definition at line 86 of file chmboxes.c.

References chDbgCheck, chSchRescheduleS(), chSemResetI(), chSysLock, and chSysUnlock.

Here is the call graph for this function:

msg_t chMBPost	(	Mailbox *	mbp,
		msg_t	msg,
		systime_t	time
	)

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 object
[in]	msg	the message to be posted on the mailbox
[in]	time	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:

	RDY_OK	if the message was correctly posted.
	RDY_RESET	if the mailbox was reset while waiting.
	RDY_TIMEOUT	if the operation timed out.

Definition at line 115 of file chmboxes.c.

References chMBPostS(), chSysLock, and chSysUnlock.

Here is the call graph for this function:

msg_t chMBPostS	(	Mailbox *	mbp,
		msg_t	msg,
		systime_t	time
	)

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 object
[in]	msg	the message to be posted on the mailbox
[in]	time	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:

	RDY_OK	if the message was correctly posted.
	RDY_RESET	if the mailbox was reset while waiting.
	RDY_TIMEOUT	if the operation timed out.

Definition at line 141 of file chmboxes.c.

References chDbgCheck, chSchRescheduleS(), chSemSignalI(), chSemWaitTimeoutS(), and RDY_OK.

Referenced by chMBPost().

Here is the call graph for this function:

msg_t chMBPostAhead	(	Mailbox *	mbp,
		msg_t	msg,
		systime_t	time
	)

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 object
[in]	msg	the message to be posted on the mailbox
[in]	time	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:

	RDY_OK	if the message was correctly posted.
	RDY_RESET	if the mailbox was reset while waiting.
	RDY_TIMEOUT	if the operation timed out.

Definition at line 174 of file chmboxes.c.

References chMBPostAheadS(), chSysLock, and chSysUnlock.

Here is the call graph for this function:

msg_t chMBPostAheadS	(	Mailbox *	mbp,
		msg_t	msg,
		systime_t	time
	)

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 object
[in]	msg	the message to be posted on the mailbox
[in]	time	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:

	RDY_OK	if the message was correctly posted.
	RDY_RESET	if the mailbox was reset while waiting.
	RDY_TIMEOUT	if the operation timed out.

Definition at line 200 of file chmboxes.c.

References chDbgCheck, chSchRescheduleS(), chSemSignalI(), chSemWaitTimeoutS(), and RDY_OK.

Referenced by chMBPostAhead().

Here is the call graph for this function:

msg_t chMBFetch	(	Mailbox *	mbp,
		msg_t *	msgp,
		systime_t	time
	)

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 object
[out]	msgp	pointer to a message variable for the received message
[in]	time	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:

	RDY_OK	if a message was correctly fetched.
	RDY_RESET	if the mailbox was reset while waiting.
	RDY_TIMEOUT	if the operation timed out.

Definition at line 233 of file chmboxes.c.

References chMBFetchS(), chSysLock, and chSysUnlock.

Here is the call graph for this function:

msg_t chMBFetchS	(	Mailbox *	mbp,
		msg_t *	msgp,
		systime_t	time
	)

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 object
[out]	msgp	pointer to a message variable for the received message
[in]	time	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:

	RDY_OK	if a message was correctly fetched.
	RDY_RESET	if the mailbox was reset while waiting.
	RDY_TIMEOUT	if the operation timed out.

Definition at line 259 of file chmboxes.c.

References chDbgCheck, chSchRescheduleS(), chSemSignalI(), chSemWaitTimeoutS(), and RDY_OK.

Referenced by chMBFetch().

Here is the call graph for this function: