Mailbox queue

mailbox queues (messages of a fixed size) More...

Macros
#define	OS_BOX_BUFFER(buf, limit, size)
	define mailbox queue data buffer
#define	OS_BOX(box, limit, size)
	define and initialize a mailbox queue object
#define	static_BOX(box, limit, size)
	static alias of OS_BOX()
#define	BOX_INIT(limit, size)
	create and initialize a mailbox queue object
#define	BOX_CREATE(limit, size)
	create and initialize a mailbox queue object
#define	BOX_NEW   BOX_CREATE
	alias of BOX_CREATE()

Functions
void	box_init (box_t *box, size_t size, void *data, size_t bufsize)
	initialize a mailbox queue object
void	box_reset (box_t *box)
	reset the mailbox queue object and wake up all waiting tasks with 'E_STOPPED' event value
void	box_kill (box_t *box)
	alias of box_reset()
int	box_take (box_t *box, void *data)
	try to transfer mailbox data from the mailbox queue object, don't wait if the mailbox queue object is empty
int	box_tryWait (box_t *box, void *data)
	alias of box_take()
int	box_takeAsync (box_t *box, void *data)
	Async alias of box_take().
int	box_waitFor (box_t *box, void *data, cnt_t delay)
	try to transfer mailbox data from the mailbox queue object, wait for given duration of time while the mailbox queue object is empty
int	box_waitUntil (box_t *box, void *data, cnt_t time)
	try to transfer mailbox data from the mailbox queue object, wait until given timepoint while the mailbox queue object is empty
int	box_wait (box_t *box, void *data)
	try to transfer mailbox data from the mailbox queue object, wait indefinitely while the mailbox queue object is empty
int	box_waitAsync (box_t *box, void *data)
	Async alias of box_wait().
int	box_give (box_t *box, const void *data)
	try to transfer mailbox data to the mailbox queue object, don't wait if the mailbox queue object is full
int	box_giveAsync (box_t *box, const void *data)
	Async alias of box_give().
int	box_sendFor (box_t *box, const void *data, cnt_t delay)
	try to transfer mailbox data to the mailbox queue object, wait for given duration of time while the mailbox queue object is full
int	box_sendUntil (box_t *box, const void *data, cnt_t time)
	try to transfer mailbox data to the mailbox queue object, wait until given timepoint while the mailbox queue object is full
int	box_send (box_t *box, const void *data)
	try to transfer mailbox data to the mailbox queue object, wait indefinitely while the mailbox queue object is full
int	box_sendAsync (box_t *box, const void *data)
	Async alias of box_send().
void	box_push (box_t *box, const void *data)
	transfer mailbox data to the mailbox queue object, remove the oldest mailbox data if the mailbox queue object is full
unsigned	box_count (box_t *box)
	return the amount of data contained in the mailbox queue
unsigned	box_space (box_t *box)
	return the amount of free space in the mailbox queue
unsigned	box_limit (box_t *box)
	return the size of the mailbox queue
size_t	box_size (box_t *box)
	return size of a single mail

Detailed Description

mailbox queues (messages of a fixed size)

Macro Definition Documentation

OS_BOX_BUFFER

#define OS_BOX_BUFFER	(		buf,
			limit,
			size )

Value:

char buf[limit * size]

define mailbox queue data buffer

Parameters

buf	name of the buffer (passed to the init function)
limit	size of a queue (max number of stored mails)
size	size of a single mail (in bytes)

OS_BOX

#define OS_BOX	(		box,
			limit,
			size )

Value:

static char box##__buf[limit * size]; \
       box_t box[] = { _BOX_INIT( limit, size, box##__buf ) }

define and initialize a mailbox queue object

Parameters

box	name of a pointer to mailbox queue object
limit	size of a queue (max number of stored mails)
size	size of a single mail (in bytes)

static_BOX

#define static_BOX	(		box,
			limit,
			size )

Value:

static char box##__buf[limit * size]; \
static box_t box[] = { _BOX_INIT( limit, size, box##__buf ) }

static alias of OS_BOX()

BOX_INIT

#define BOX_INIT	(		limit,
			size )

Value:

_BOX_INIT( limit, size, _BOX_DATA( limit, size ) )

create and initialize a mailbox queue object

Parameters

limit	size of a queue (max number of stored mails)
size	size of a single mail (in bytes)

Returns

mailbox queue object

Note

use only in 'C' code

BOX_CREATE

#define BOX_CREATE	(		limit,
			size )

Value:

{ BOX_INIT  ( limit, size ) }

create and initialize a mailbox queue object

Parameters

limit	size of a queue (max number of stored mails)
size	size of a single mail (in bytes)

Returns

mailbox queue object as array (id)

Note

use only in 'C' code

Function Documentation

box_init()

void box_init	(	box_t *	box,
		size_t	size,
		void *	data,
		size_t	bufsize )

initialize a mailbox queue object

Parameters

box	pointer to mailbox queue object
size	size of a single mail (in bytes)
data	mailbox queue data buffer
bufsize	size of the data buffer (in bytes)

box_reset()

void box_reset

(

box_t *

box

)

reset the mailbox queue object and wake up all waiting tasks with 'E_STOPPED' event value

Parameters

box	pointer to mailbox queue object

Note

use only in thread mode

box_take()

int box_take	(	box_t *	box,
		void *	data )

try to transfer mailbox data from the mailbox queue object, don't wait if the mailbox queue object is empty

Parameters

box	pointer to mailbox queue object
data	pointer to store mailbox data

Return values

E_SUCCESS	mailbox data was successfully transferred from the mailbox queue object
E_TIMEOUT	mailbox queue object is empty, try again

Note

use Async alias for communication with unmasked interrupt handlers

box_waitFor()

int box_waitFor	(	box_t *	box,
		void *	data,
		cnt_t	delay )

try to transfer mailbox data from the mailbox queue object, wait for given duration of time while the mailbox queue object is empty

Parameters

box	pointer to mailbox queue object
data	pointer to store mailbox data
delay	duration of time (maximum number of ticks to wait while the mailbox queue object is empty) IMMEDIATE: don't wait if the mailbox queue object is empty INFINITE: wait indefinitely while the mailbox queue object is empty

Return values

E_SUCCESS	mailbox data was successfully transferred from the mailbox queue object
E_STOPPED	mailbox queue object was reseted before the specified timeout expired
E_TIMEOUT	mailbox queue object is empty and was not received data before the specified timeout expired

box_waitUntil()

int box_waitUntil	(	box_t *	box,
		void *	data,
		cnt_t	time )

try to transfer mailbox data from the mailbox queue object, wait until given timepoint while the mailbox queue object is empty

Parameters

box	pointer to mailbox queue object
data	pointer to store mailbox data
time	timepoint value

Return values

E_SUCCESS	mailbox data was successfully transferred from the mailbox queue object
E_STOPPED	mailbox queue object was reseted before the specified timeout expired
E_TIMEOUT	mailbox queue object is empty and was not received data before the specified timeout expired

box_wait()

int box_wait ( box_t * box, void * data )

inline

try to transfer mailbox data from the mailbox queue object, wait indefinitely while the mailbox queue object is empty

Parameters

box	pointer to mailbox queue object
data	pointer to store mailbox data

Return values

E_SUCCESS	mailbox data was successfully transferred from the mailbox queue object
E_STOPPED	mailbox queue object was reseted (unavailable for async version)

Note

use Async alias for communication with unmasked interrupt handlers

box_give()

int box_give	(	box_t *	box,
		const void *	data )

try to transfer mailbox data to the mailbox queue object, don't wait if the mailbox queue object is full

Parameters

box	pointer to mailbox queue object
data	pointer to mailbox data

Return values

E_SUCCESS	mailbox data was successfully transferred to the mailbox queue object
E_TIMEOUT	mailbox queue object is full, try again

Note

use Async alias for communication with unmasked interrupt handlers

box_sendFor()

int box_sendFor	(	box_t *	box,
		const void *	data,
		cnt_t	delay )

try to transfer mailbox data to the mailbox queue object, wait for given duration of time while the mailbox queue object is full

Parameters

box	pointer to mailbox queue object
data	pointer to mailbox data
delay	duration of time (maximum number of ticks to wait while the mailbox queue object is full) IMMEDIATE: don't wait if the mailbox queue object is full INFINITE: wait indefinitely while the mailbox queue object is full

Return values

E_SUCCESS	mailbox data was successfully transferred to the mailbox queue object
E_STOPPED	mailbox queue object was reseted before the specified timeout expired
E_TIMEOUT	mailbox queue object is full and was not issued data before the specified timeout expired

box_sendUntil()

int box_sendUntil	(	box_t *	box,
		const void *	data,
		cnt_t	time )

try to transfer mailbox data to the mailbox queue object, wait until given timepoint while the mailbox queue object is full

Parameters

box	pointer to mailbox queue object
data	pointer to mailbox data
time	timepoint value

Return values

E_SUCCESS	mailbox data was successfully transferred to the mailbox queue object
E_STOPPED	mailbox queue object was reseted before the specified timeout expired
E_TIMEOUT	mailbox queue object is full and was not issued data before the specified timeout expired

box_send()

int box_send ( box_t * box, const void * data )

inline

try to transfer mailbox data to the mailbox queue object, wait indefinitely while the mailbox queue object is full

Parameters

box	pointer to mailbox queue object
data	pointer to mailbox data

Return values

E_SUCCESS	mailbox data was successfully transferred to the mailbox queue object
E_STOPPED	mailbox queue object was reseted (unavailable for async version)

Note

use Async alias for communication with unmasked interrupt handlers

box_push()

void box_push	(	box_t *	box,
		const void *	data )

transfer mailbox data to the mailbox queue object, remove the oldest mailbox data if the mailbox queue object is full

Parameters

box	pointer to mailbox queue object
data	pointer to mailbox data

box_count()

unsigned box_count

(

box_t *

box

)

return the amount of data contained in the mailbox queue

Parameters

box	pointer to mailbox queue object

Returns

amount of data contained in the mailbox queue

box_space()

unsigned box_space

(

box_t *

box

)

return the amount of free space in the mailbox queue

Parameters

box	pointer to mailbox queue object

Returns

amount of free space in the mailbox queue

box_limit()

unsigned box_limit

(

box_t *

box

)

return the size of the mailbox queue

Parameters

box	pointer to mailbox queue object

Returns

size of the mailbox queue

box_size()

size_t box_size ( box_t * box )

inline

return size of a single mail

Parameters

box	pointer to mailbox queue object

Returns

size of a single mail in the mailbox queue