Mailboxes

Functions

void mbox_init (mbox_t *mbox, size_t size)
 
void mbox_deinit (mbox_t *mbox)
 
mbox_t * mbox_create (size_t size)
 
void mbox_destroy (mbox_t *mbox)
 
void mbox_fetch (mbox_t *mbox, void **msg)
 
int mbox_fetch_tmo (mbox_t *mbox, void **msg, tick_t time)
 
void mbox_post (mbox_t *mbox, void *msg)
 
int mbox_post_tmo (mbox_t *mbox, void *msg, tick_t time)
 
void mbox_set_name (mbox_t *mbox, const char *name)
 
void mbox_show (void)
 
void mbox_show_with_fmt_fn (fmt_fn_t fn)
 

Detailed Description

Function Documentation

◆ mbox_create()

mbox_t* mbox_create ( size_t  size)

Allocates and initialises a mailbox handle. See mbox_init() for further details.

Parameters
sizeThe maximum number of messages in the mailbox
Returns
The mailbox handle to be used in all subsequent operations on the mailbox.

◆ mbox_deinit()

void mbox_deinit ( mbox_t *  mbox)

Deinitialises a mailbox handle. The mailbox must not be in use when this function is called (no task can be waiting to post to or fetch from the mailbox, nor can they do so at any time after calling this function).

This function must not be called with a handle that was returned by mbox_create(). See mbox_destroy().

Parameters
mboxMailbox handle

◆ mbox_destroy()

void mbox_destroy ( mbox_t *  mbox)

Frees the resources allocated by the mailbox. The mailbox must not be in use when this function is called (no task can be waiting to post to or fetch from the mailbox, nor can they do so at any time after calling this function).

This function must only be called with a handle that was returned by mbox_create().

Parameters
mboxMailbox handle

◆ mbox_fetch()

void mbox_fetch ( mbox_t *  mbox,
void **  msg 
)

Fetches the next message from the mailbox. If there are no more messages in the mailbox, the calling task will be put in the WAITING state until a message arrives. If there is at least one message in the mailbox, the function will return immediately.

The caller provides a pointer, msg, that is modified to point to the new message.

void myTaskEntry (void * arg)
{
mbox_t myMbox = (mbox_t *)arg;
uint32_t * myMsg;
for (;;)
{
// Wait for next message
mbox_fetch (myMbox, (void **)&myMsg);
// Do work according to message
switch (*myMsg)
{
case 0:
...
break;
case 1:
...
break;
...
}
// Free message
free (myMsg);
}
}

rt-kernel does not interpret the message in any way. It can be any structure, as long as the posting and fetching tasks agree on the representation.

Messages are not copied. The pointer is passed unmodified from the poster to the fetcher. If the posting task allocated memory for the message then it is good programming practice to let the fetching task free the memory.

Note that mailboxes can be used to pass integer values between tasks without using pointers. This can be useful in a static system, as it does not require the use of dynamic memory.

void foo()
{
mbox_t * myMbox;
void * myMsg;
mbox_post (myMbox, (void *)1);
mbox_fetch (myMbox, &myMsg);
ASSERT ((int)myMsg == 1);
}
Parameters
mboxMailbox handle
msgPointer to message

◆ mbox_fetch_tmo()

int mbox_fetch_tmo ( mbox_t *  mbox,
void **  msg,
tick_t  time 
)

Analogous to mbox_fetch(), but a maximum time to wait can be specified. If the mailbox is empty, the calling task will wait until a new message arrives, or the number of ticks given by time expires.

Parameters
mboxMailbox handle
msgPointer to message
timeNumber of ticks to wait
Returns
0 if a message was fetched successfully, 1 if the service timed out.

◆ mbox_init()

void mbox_init ( mbox_t *  mbox,
size_t  size 
)

Initialises a mailbox handle. The size parameter specifies the maximum number of messages in the mailbox. When the limit is reached, tasks trying to post to the mailbox will be blocked until another task fetches one or more messages.

This function must not be called with a handle that was returned by mbox_create().

Parameters
mboxMailbox handle
sizeThe maximum number of messages in the mailbox

◆ mbox_post()

void mbox_post ( mbox_t *  mbox,
void *  msg 
)

Posts a message to the mailbox. The calling task is put in the WAITING state if the mailbox is full. If the mailbox is not full, the function will return immediately.

void myTaskEntry (void * arg)
{
mbox_t myMbox = (mbox_t *)arg;
uint32_t * myMsg;
for (;;)
{
// Wait for event
...
// Post message to mailbox
myMsg = malloc (sizeof (uint32_t));
*myMsg = 1;
mbox_post (myMbox, (void *)&myMsg);
}
}

rt-kernel does not interpret the message in any way. It can be any structure, as long as the posting and fetching tasks agree on the representation.

Messages are not copied. The pointer is passed unmodified from the poster to the fetcher. If the posting task allocated memory for the message then it is good programming practice to let the fetching task free the memory.

Parameters
mboxMailbox handle
msgPointer to message

◆ mbox_post_tmo()

int mbox_post_tmo ( mbox_t *  mbox,
void *  msg,
tick_t  time 
)

Analogous to mbox_post(), but a maximum time to wait can be specified. If the mailbox is full, the calling task will wait until there is space in the mailbox, or the number of ticks given by time expires.

This function may be called from an ISR if and only if time is 0.

Parameters
mboxMailbox handle
msgPointer to message
timeNumber of ticks to wait
Returns
0 if a message was posted successfully, 1 if the service timed out.

◆ mbox_set_name()

void mbox_set_name ( mbox_t *  mbox,
const char *  name 
)

Sets the name of the mailbox.

This function is only used for debugging purposes, where a kernel-aware debugger may present this name to the user.

The name will be stored in a separate table for kernel objects. If the name could not be set, the error is silently ignored.

Parameters
mboxMailbox handle
nameString describing mailbox

◆ mbox_show()

void mbox_show ( void  )

Prints all registered mailboxes to stdout using rprintp(). This may prove useful for debugging purposes. This function should not be called from application code, but may be called from e.g. uerror() or an exception handler.

◆ mbox_show_with_fmt_fn()

void mbox_show_with_fmt_fn ( fmt_fn_t  fn)

Same as mbox_show(), but using supplied function for formatted output.

Parameters
fnFunction for formatted output