Mailbox library

nRF5 SDK v12.1.0
Modules | Data Structures | Macros | Enumerations | Functions

Mailbox for safely queuing items. More...

Modules

Thread safe mailbox configuration

Data Structures

struct app_mailbox_t
Mailbox definition structure. More...

Macros

#define APP_MAILBOX_DEF (name, QUEUE_SZ, ITEM_SZ)
Macro to statically allocate memory for a given mailbox queue. More...

Enumerations

enum app_mailbox_overflow_mode_t {
APP_MAILBOX_MODE_NO_OVERFLOW ,
APP_MAILBOX_MODE_OVERFLOW
}
Supported overflow modes. More...

Functions

ret_code_t app_mailbox_create (const app_mailbox_t *p_mailbox)
Function for creating a mailbox queue. More...
ret_code_t app_mailbox_put (const app_mailbox_t *p_mailbox, void *p_item)
Function for putting an item in the mailbox queue. More...
ret_code_t app_mailbox_sized_put (const app_mailbox_t *p_mailbox, void *p_item, uint16_t size)
Function for putting an item with a specified size in the mailbox queue. More...
ret_code_t app_mailbox_get (const app_mailbox_t *p_mailbox, void *p_item)
Function for getting an item from the mailbox queue. More...
ret_code_t app_mailbox_sized_get (const app_mailbox_t *p_mailbox, void *p_item, uint16_t *p_size)
Function for getting an item and its size from the mailbox queue. More...
uint32_t app_mailbox_length_get (const app_mailbox_t *p_mailbox)
Function for getting the current length of the mailbox queue. More...
void app_mailbox_mode_set (const app_mailbox_t *p_mailbox, app_mailbox_overflow_mode_t mode)
Function for changing the mode of overflow handling. More...

Detailed Description

Mailbox for safely queuing items.

Macro Definition Documentation

#define APP_MAILBOX_DEF ( name,
QUEUE_SZ,
ITEM_SZ
)
Value:
static uint32_t STRING_CONCATENATE (mailbox_items_,name)[(1 + CEIL_DIV ((ITEM_SZ),4)) * (QUEUE_SZ)];\
static app_mailbox_cb_t STRING_CONCATENATE (mailbox_cb_,name); \
const app_mailbox_t name = \
{ \
. p_pool = STRING_CONCATENATE (mailbox_items_,name), \
.p_cb = STRING_CONCATENATE (&mailbox_cb_,name), \
.queue_sz = (uint8_t)(QUEUE_SZ), \
.item_sz = (uint16_t)(ITEM_SZ), \
}

Macro to statically allocate memory for a given mailbox queue.

Enumeration Type Documentation

enum app_mailbox_overflow_mode_t

Supported overflow modes.

Enumerator
APP_MAILBOX_MODE_NO_OVERFLOW

If the mailbox is full, app_mailbox_put does not add a new element.

APP_MAILBOX_MODE_OVERFLOW

If the mailbox is full, the oldest element is lost and a new one is added.

Function Documentation

ret_code_t app_mailbox_create ( const app_mailbox_t * p_mailbox )

Function for creating a mailbox queue.

This function creates and initializes a mailbox queue.

Parameters
[in] p_mailbox Pointer to the mailbox.
Return values
NRF_SUCCESS If the queue was successfully created.
ret_code_t app_mailbox_get ( const app_mailbox_t * p_mailbox ,
void * p_item
)

Function for getting an item from the mailbox queue.

Parameters
[in] p_mailbox Pointer to the mailbox.
[out] p_item Pointer to the output location for the dequeued item.
Return values
NRF_SUCCESS If the item was retrieved successfully.
NRF_ERROR_NO_MEM If the queue is empty.
uint32_t app_mailbox_length_get ( const app_mailbox_t * p_mailbox )

Function for getting the current length of the mailbox queue.

Parameters
[in] p_mailbox Pointer to the mailbox.
Returns
Current number of elements in the queue.
void app_mailbox_mode_set ( const app_mailbox_t * p_mailbox ,
app_mailbox_overflow_mode_t mode
)

Function for changing the mode of overflow handling.

Parameters
[in] p_mailbox Pointer to the mailbox.
mode New mode to set.
ret_code_t app_mailbox_put ( const app_mailbox_t * p_mailbox ,
void * p_item
)

Function for putting an item in the mailbox queue.

Parameters
[in] p_mailbox Pointer to the mailbox.
[in] p_item Pointer to the item to be queued.
Return values
NRF_SUCCESS If the item was enqueued.
NRF_ERROR_NO_MEM If the queue is full.
ret_code_t app_mailbox_sized_get ( const app_mailbox_t * p_mailbox ,
void * p_item ,
uint16_t * p_size
)

Function for getting an item and its size from the mailbox queue.

Parameters
[in] p_mailbox Pointer to the mailbox.
[out] p_item Pointer to the output location for the dequeued item.
[out] p_size Pointer to the item size.
Return values
NRF_SUCCESS If the item was retrieved successfully.
NRF_ERROR_NO_MEM If the queue is empty.
ret_code_t app_mailbox_sized_put ( const app_mailbox_t * p_mailbox ,
void * p_item ,
uint16_t size
)

Function for putting an item with a specified size in the mailbox queue.

Parameters
[in] p_mailbox Pointer to the mailbox.
[in] p_item Pointer to the item to be queued.
[in] size Size of the item.
Return values
NRF_SUCCESS If the item was enqueued.
NRF_ERROR_NO_MEM If the queue is full.