The mailbox library provides functions to safely exchange messages by queuing them and reading them from the queue.

Key features include:

Protected adding to a mailbox.
Protected retrieving from a mailbox.
Two modes of overflow handling.

Creating a mailbox

You can create multiple instances of the library. To create a mailbox, use the APP_MAILBOX_DEF macro and provide the identifier, the queue size, and the maximum size of a single element that the mailbox should be able to store. The macro allocates memory for the queue and the internals of the instance.

The following example code allocates memory for a mailbox instance and a queue that can store up to 10 words (40 bytes):

APP_MAILBOX_DEF(mailbox, 10, sizeof(uint32_t));

After the mailbox is defined, call app_mailbox_create to create it:

err_code = app_mailbox_create(&mailbox);

Using the mailbox

To put an item in the mailbox, call app_mailbox_put or app_mailbox_sized_put. The item is then safely copied into the mailbox, protected by a critical region. If there is no more room available in the mailbox, the function returns an error code. Depending on the requested overflow mode, the item replaces the oldest element in the mailbox (mode APP_MAILBOX_MODE_OVERFLOW) or is not added (default mode APP_MAILBOX_MODE_NO_OVERFLOW). The overflow mode can be changed using app_mailbox_mode_set.

To safely (protected by a critical region) get an item from the mailbox, call app_mailbox_get or app_mailbox_sized_get. If the mailbox is empty, the function returns the error code NRF_ERROR_NO_MEM.

You can call app_mailbox_length_get at any time to check the number of elements in the mailbox.