ChibiOS/NIL  3.2.2
Collaboration diagram for Mailboxes:

Detailed Description

Asynchronous messages.

Operation mode

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 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, \
}
#define _THREADS_QUEUE_DATA(name)
Data part of a static threads queue object initializer.
Definition: ch.h:1045

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]namethe name of the mailbox variable
[in]bufferpointer to the mailbox buffer array of msg_t
[in]sizenumber 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]namethe name of the mailbox variable
[in]bufferpointer to the mailbox buffer array of msg_t
[in]sizenumber 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]mbpthe pointer to the mailbox_t structure to be initialized
[in]bufpointer to the messages buffer as an array of msg_t
[in]nnumber 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]mbpthe 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]mbpthe 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, chDbgCheckClassI(), 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]mbpthe pointer to an initialized mailbox_t object
[in]msgthe message to be posted on the mailbox
[in]timeoutthe 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_OKif a message has been correctly posted.
MSG_RESETif the mailbox has been reset.
MSG_TIMEOUTif 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]mbpthe pointer to an initialized mailbox_t object
[in]msgthe message to be posted on the mailbox
[in]timeoutthe 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_OKif a message has been correctly posted.
MSG_RESETif the mailbox has been reset.
MSG_TIMEOUTif 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, chDbgCheckClassS(), 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]mbpthe pointer to an initialized mailbox_t object
[in]msgthe message to be posted on the mailbox
Returns
The operation status.
Return values
MSG_OKif a message has been correctly posted.
MSG_RESETif the mailbox has been reset.
MSG_TIMEOUTif 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, chDbgCheckClassI(), 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]mbpthe pointer to an initialized mailbox_t object
[in]msgthe message to be posted on the mailbox
[in]timeoutthe 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_OKif a message has been correctly posted.
MSG_RESETif the mailbox has been reset.
MSG_TIMEOUTif 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]mbpthe pointer to an initialized mailbox_t object
[in]msgthe message to be posted on the mailbox
[in]timeoutthe 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_OKif a message has been correctly posted.
MSG_RESETif the mailbox has been reset.
MSG_TIMEOUTif 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, chDbgCheckClassS(), 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]mbpthe pointer to an initialized mailbox_t object
[in]msgthe message to be posted on the mailbox
Returns
The operation status.
Return values
MSG_OKif a message has been correctly posted.
MSG_RESETif the mailbox has been reset.
MSG_TIMEOUTif 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, chDbgCheckClassI(), 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]mbpthe pointer to an initialized mailbox_t object
[out]msgppointer to a message variable for the received message
[in]timeoutthe 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_OKif a message has been correctly fetched.
MSG_RESETif the mailbox has been reset.
MSG_TIMEOUTif 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]mbpthe pointer to an initialized mailbox_t object
[out]msgppointer to a message variable for the received message
[in]timeoutthe 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_OKif a message has been correctly fetched.
MSG_RESETif the mailbox has been reset.
MSG_TIMEOUTif 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, chDbgCheckClassS(), 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]mbpthe pointer to an initialized mailbox_t object
[out]msgppointer to a message variable for the received message
Returns
The operation status.
Return values
MSG_OKif a message has been correctly fetched.
MSG_RESETif the mailbox has been reset.
MSG_TIMEOUTif 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, chDbgCheckClassI(), 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]mbpthe 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]mbpthe 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 chDbgCheckClassI(), and mailbox_t::cnt.

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

Here is the call graph for this function:

static size_t chMBGetFreeCountI ( const mailbox_t mbp)
inlinestatic

Returns the number of free message slots into a mailbox.

Parameters
[in]mbpthe 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 chDbgCheckClassI(), 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]mbpthe 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 chDbgCheckClassI(), and mailbox_t::rdptr.

Here is the call graph for this function:

static void chMBResumeX ( mailbox_t mbp)
inlinestatic

Terminates the reset state.

Parameters
[in]mbpthe 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.