Mailbox objects

Mailboxes are very similar to queues. They enable to exchange data between tasks and are based on FIFO (First In, First Out). The main differences between mailbox and queue are that the message size and the number of messages are not limited, so depend only on the available memory resources. Mailbox may be used to exchange large portions of data.

Mailbox creation and deletion

The function osCreateMailbox creates a mailbox object. The mailbox can be created before system start, from an interrupt handler or by a task. During mailbox creation, an optional mailbox name may be specified. It makes tasks able to open it by osOpenMailbox function. During mailbox creation and opening, its handle is returned. The handle is assigned by the system and it is used to discern the system objects. All operations performed on the mailbox except to specify its handle. The non-used mailbox should be closed with the osCloseHandle. Mailbox will be deleted when it will be closed by all tasks that opened it. More information you can find in the system objects management section.

When mailboxes are not used, the OS_USE_MAILBOX constant may be set to 0, to reduce the output code.

Using a mailbox object

The maximal size and the number of messages that can be stored by mailbox are not limited. When the message is stored in the mailbox and direct read-write is not performed, the memory block is allocated, and message is stored in this block. It will be deleted when a message is read or the mailbox cleared or deleted.

To insert the message into a mailbox the osMailboxPost function should be called. An osMailboxPend function allows to read and later to remove the first message from the mailbox. To read the message without removing it, the osMailboxPeek function should be used. Read and write operations can be performed also by system functions, such as osRead and osWrite. To delete all messages from mailbox it should be called the osClearMailbox function.

The osGetMailboxInfo function that is available when OS_MBOX_GET_INFO_FUNC is set for 1, allows the user to obtain information regarding the total number of messages stored in the mailbox and the size of the first message in the mailbox.

In case, where the OS_MBOX_PEEK_FUNC is set to 1, access to mailbox must be synchronized while data copying. It may be realized in three ways: by protecting by mutex, auto-reset event, or by interrupt disabling. The last way can be used only when small portions of data are transferred to or from a mailbox. The way of synchronization is chosen during mailbox creation by using OS_IPC_PROTECT_MUTEX, OS_IPC_PROTECT_EVENT or OS_IPC_PROTECT_INT_CTRL mode flags. Synchronization mode by mutex or auto-reset event is available only when corresponding constants OS_MBOX_PROTECT_MUTEX and OS_MBOX_PROTECT_EVENT are set to 1. In case, where the osTerminateTask is used for task performing operations on the mailbox, it is expected to use synchronization by mutex.

When read operation is performed on the empty mailbox, the operation will be finished with an error. The task may also be waiting for a read operation completion. The task is resumed when data will be successfully transferred, or specified timeout interval elapses. It is realized by the appropriate specifying mode flag OS_IPC_WAIT_IF_EMPTY during mailbox creation. This feature is available only when the OS_MBOX_ALLOW_WAIT_IF_EMPTY is set to 1.

When the wait for operation completion is enabled, the data can be sending directly from one task to another, without storing data in the mailbox. To enable this feature, it should be set OS_IPC_DIRECT_READ_WRITE mode flag. It is only available when OS_MBOX_ALLOW_DIRECT_RW is set to 1.

SpaceShadow documentation