ChibiOS/RT Architecture - Reference Manual - Guides |
Asynchronous messages.
A mailbox is an asynchronous communication mechanism.
Operations defined for mailboxes:
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 chMBSize | ( | mbp | ) | ((mbp)->mb_top - (mbp)->mb_buffer) |
Returns the mailbox buffer size.
[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.
[in] | mbp | the pointer to an initialized Mailbox object |
Definition at line 93 of file chmboxes.h.
#define chMBGetFull | ( | mbp | ) | chSemGetCounterI(&(mbp)->mb_fullsem) |
Returns the number of messages into the mailbox.
[in] | mbp | the pointer to an initialized Mailbox object |
Definition at line 105 of file chmboxes.h.
#define chMBPeek | ( | mbp | ) | (*(mbp)->mb_rdptr) |
Returns the next message in the queue without removing it.
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 | ||||
) |
{ \ (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.
[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()
.
[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.
Initializes a Mailbox object.
[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().
void chMBReset | ( | Mailbox * | mbp | ) |
Resets a Mailbox object.
All the waiting threads are resumed with status RDY_RESET
and the queued messages are lost.
[in] | mbp | the pointer to an initialized Mailbox object |
Definition at line 86 of file chmboxes.c.
References chDbgCheck, chSchRescheduleS(), chSemResetI(), chSysLock, and chSysUnlock.
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.
[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:
|
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.
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.
[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:
|
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().
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.
[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:
|
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.
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.
[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:
|
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().
Retrieves a message from a mailbox.
The invoking thread waits until a message is posted in the mailbox or the specified time runs out.
[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:
|
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.
Retrieves a message from a mailbox.
The invoking thread waits until a message is posted in the mailbox or the specified time runs out.
[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:
|
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().