osCreateMailbox function
Declaration:
HANDLE osCreateMailbox(
  SYSNAME Name,
  UINT8 Mode
);
Parameters:
Name

Name of the object (may be NULL).

Mode

Mode flags (see the description section below).

Return value:

The return value is a handle to the created mailbox object when success or NULL_HANDLE on failure. Use osGetLastError function to obtain extended error information.

Description:

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.

During mailbox creation, an optional mailbox name may be specified. It makes tasks able to open it by osOpenMailbox function. The non-used mailbox should be closed with the osCloseHandle. Mailbox will be deleted when it is closed by all tasks that opened it. More information you can find in the system objects managementsection.

If all of the osOpen* functions are not used, the system ignores an object name and the code used to name management will be removed. It will reduce final size of the output code. For more information about the names and object opening see the system objects managementsection.

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 and it is only available when OS_MBOX_ALLOW_DIRECT_RW is set to 1.

For more information about the mailbox see the mailbox objects section.

Function is available only, when the value of OS_USE_MAILBOX constant is set to 1.

SpaceShadow documentation