Asynchronous Message Passing / Mailbox API

Mailbox is a kernel object that contains multiple mail slots. Tasks can post a message to a mailbox (which takes up a mail slot) and a task can fetch a message from the mailbox (which removes the message from the mail slot). A message is an opaque pointer (“void *” in C) whose meaning and format are defined by the user. By using a void pointer as a message, a message can be a byte array or an arbitrary data structure. Mailboxes do not copy the content of a message, so mailbox calls are very fast and efficient.

 

If there are multiple pending messages in a mailbox, they are ordered by the original senders’ priorities and not by message posting times, so a message from the highest priority sender will be retrieved first.

 

There are three message-posting API functions:

 

·         REXIS_MailboxPost posts a message and will block the sender task if the mailbox is full, until the mailbox can accept its message.

·         REXIS_MailboxTryPost does not wait but instead returns an error code if the mailbox is full.

·         REXIS_MailboxPostFromISR does the same job as REXIS_MailboxPost but is called from an ISR.

 

Note that REXIS_MailboxPostFromISR does not return a value, as the actual operation would be carried out after the ISR exits. The message will be posted to the mailbox next time the system tick happens. If the mailbox is full, the operation will be retried at each system tick interrupt until the message is posted. This is true with other FromISR kernel API calls as well.

 

There are two message fetching API:

·         REXIS_MailboxFetch fetches a message and will block the task if the mailbox is empty, until either a message arrives or the timeout value expires.

·         REXIS_MailboxTryFetch does not wait but instead returns an error code if the mailbox is empty.

 

Note that the task fetching a message will receive the actual pointer value sent by the posting task. In particular, if you call REXIS_MailboxPostFromISR, make sure the pointer object you pass as a message is still valid when the message is retrieved. For example, passing a pointer to a local variable from within an ISR will result in an error, as by the time the message is retrieved, the execution context for the ISR is no longer valid. See the example above. This is normally not an issue with tasks calling REXIS_MailboxPost, as a task usually runs forever and the execution context would still be valid when the message is retrieved.