StateOS
Loading...
Searching...
No Matches
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
box_t * box_create (unsigned limit, size_t size)
 create and initialize a new mailbox queue object
box_t * box_new (unsigned limit, size_t size)
 alias of box_create()
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()
void box_destroy (box_t *box)
 reset the mailbox queue object, wake up all waiting tasks with 'E_DELETED' event value and free allocated resource
void box_delete (box_t *box)
 alias of box_destroy()
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_takeISR (box_t *box, void *data)
 ISR 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_giveISR (box_t *box, const void *data)
 ISR alias of box_give().
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
void box_pushISR (box_t *box, const void *data)
 ISR alias of box_push().
unsigned box_count (box_t *box)
 return the amount of data contained in the mailbox queue
unsigned box_countISR (box_t *box)
 ISR alias of box_count().
unsigned box_space (box_t *box)
 return the amount of free space in the mailbox queue
unsigned box_spaceISR (box_t *box)
 ISR alias of box_space().
unsigned box_limit (box_t *box)
 return the size of the mailbox queue
unsigned box_limitISR (box_t *box)
 ISR alias of box_limit().
size_t box_size (box_t *box)
 return size of a single mail
size_t box_sizeISR (box_t *box)
 ISR alias of box_size().

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
bufname of the buffer (passed to the init function)
limitsize of a queue (max number of stored mails)
sizesize 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
boxname of a pointer to mailbox queue object
limitsize of a queue (max number of stored mails)
sizesize 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
limitsize of a queue (max number of stored mails)
sizesize 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 ) }
#define BOX_INIT(limit, size)
create and initialize a mailbox queue object
Definition osmailboxqueue.h:143

create and initialize a mailbox queue object

Parameters
limitsize of a queue (max number of stored mails)
sizesize 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
boxpointer to mailbox queue object
sizesize of a single mail (in bytes)
datamailbox queue data buffer
bufsizesize of the data buffer (in bytes)
Note
use only in thread mode

◆ box_create()

box_t * box_create ( unsigned limit,
size_t size )

create and initialize a new mailbox queue object

Parameters
limitsize of a queue (max number of stored mails)
sizesize of a single mail (in bytes)
Returns
pointer to mailbox queue object
Return values
NULLobject not created (not enough free memory)
Note
use only in thread mode

◆ 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
boxpointer to mailbox queue object
Note
use only in thread mode

◆ box_destroy()

void box_destroy ( box_t * box)

reset the mailbox queue object, wake up all waiting tasks with 'E_DELETED' event value and free allocated resource

Parameters
boxpointer 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
boxpointer to mailbox queue object
datapointer to store mailbox data
Return values
E_SUCCESSmailbox data was successfully transferred from the mailbox queue object
E_TIMEOUTmailbox queue object is empty, try again
Note
can be used in both thread and handler mode
use ISR alias in blockable interrupt handlers
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
boxpointer to mailbox queue object
datapointer to store mailbox data
delayduration 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_SUCCESSmailbox data was successfully transferred from the mailbox queue object
E_STOPPEDmailbox queue object was reseted before the specified timeout expired
E_DELETEDmailbox queue object was deleted before the specified timeout expired
E_TIMEOUTmailbox queue object is empty and was not received data before the specified timeout expired
Note
use only in thread mode

◆ 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
boxpointer to mailbox queue object
datapointer to store mailbox data
timetimepoint value
Return values
E_SUCCESSmailbox data was successfully transferred from the mailbox queue object
E_STOPPEDmailbox queue object was reseted before the specified timeout expired
E_DELETEDmailbox queue object was deleted before the specified timeout expired
E_TIMEOUTmailbox queue object is empty and was not received data before the specified timeout expired
Note
use only in thread mode

◆ 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
boxpointer to mailbox queue object
datapointer to store mailbox data
Return values
E_SUCCESSmailbox data was successfully transferred from the mailbox queue object
E_STOPPEDmailbox queue object was reseted (unavailable for async version)
E_DELETEDmailbox queue object was deleted (unavailable for async version)
Note
use only in thread mode
use Async alias for communication with unmasked interrupt handlers
the Async alias is intended for tasks of equal priority: it waits in a loop with tsk_yield, lower priority tasks do not run meanwhile

◆ 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
boxpointer to mailbox queue object
datapointer to mailbox data
Return values
E_SUCCESSmailbox data was successfully transferred to the mailbox queue object
E_TIMEOUTmailbox queue object is full, try again
Note
can be used in both thread and handler mode
use ISR alias in blockable interrupt handlers
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
boxpointer to mailbox queue object
datapointer to mailbox data
delayduration 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_SUCCESSmailbox data was successfully transferred to the mailbox queue object
E_STOPPEDmailbox queue object was reseted before the specified timeout expired
E_DELETEDmailbox queue object was deleted before the specified timeout expired
E_TIMEOUTmailbox queue object is full and was not issued data before the specified timeout expired
Note
use only in thread mode

◆ 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
boxpointer to mailbox queue object
datapointer to mailbox data
timetimepoint value
Return values
E_SUCCESSmailbox data was successfully transferred to the mailbox queue object
E_STOPPEDmailbox queue object was reseted before the specified timeout expired
E_DELETEDmailbox queue object was deleted before the specified timeout expired
E_TIMEOUTmailbox queue object is full and was not issued data before the specified timeout expired
Note
use only in thread mode

◆ 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
boxpointer to mailbox queue object
datapointer to mailbox data
Return values
E_SUCCESSmailbox data was successfully transferred to the mailbox queue object
E_STOPPEDmailbox queue object was reseted (unavailable for async version)
E_DELETEDmailbox queue object was deleted (unavailable for async version)
Note
use only in thread mode
use Async alias for communication with unmasked interrupt handlers
the Async alias is intended for tasks of equal priority: it waits in a loop with tsk_yield, lower priority tasks do not run meanwhile

◆ 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
boxpointer to mailbox queue object
datapointer to mailbox data
Note
can be used in both thread and handler mode (for blockable interrupts)
use ISR alias in blockable interrupt handlers

◆ box_count()

unsigned box_count ( box_t * box)

return the amount of data contained in the mailbox queue

Parameters
boxpointer to mailbox queue object
Returns
amount of data contained in the mailbox queue
Note
can be used in both thread and handler mode (for blockable interrupts)
use ISR alias in blockable interrupt handlers

◆ box_space()

unsigned box_space ( box_t * box)

return the amount of free space in the mailbox queue

Parameters
boxpointer to mailbox queue object
Returns
amount of free space in the mailbox queue
Note
can be used in both thread and handler mode (for blockable interrupts)
use ISR alias in blockable interrupt handlers

◆ box_limit()

unsigned box_limit ( box_t * box)

return the size of the mailbox queue

Parameters
boxpointer to mailbox queue object
Returns
size of the mailbox queue
Note
can be used in both thread and handler mode (for blockable interrupts)
use ISR alias in blockable interrupt handlers

◆ box_size()

size_t box_size ( box_t * box)
inline

return size of a single mail

Parameters
boxpointer to mailbox queue object
Returns
size of a single mail in the mailbox queue
Note
can be used in both thread and handler mode (for blockable interrupts)
use ISR alias in blockable interrupt handlers