Mailboxes

Functions

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)

Function Documentation

mbox_t* mbox_create ( size_t  size  ) 

Allocates and 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.

Parameters:
size The maximum number of messages in the mailbox
Returns:
The mailbox handle to be used in all subsequent operations on the mailbox.
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).

Parameters:
mbox Mailbox handle
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:
mbox Mailbox handle
msg Pointer to message
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:
mbox Mailbox handle
msg Pointer to message
time Number of ticks to wait
Returns:
0 if a message was fetched successfully, 1 if the service timed out.
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:
mbox Mailbox handle
msg Pointer to message
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.

Parameters:
mbox Mailbox handle
msg Pointer to message
time Number of ticks to wait
Returns:
0 if a message was posted successfully, 1 if the service timed out.
rt-kernel