Mailbox library

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.