os_mbx_wait

#include <rtl.h>

OS_RESULT os_mbx_wait (
    OS_ID  mailbox,      /* The mailbox to get message from */
    void** message,      /* Location to store the message pointer */
    U16    timeout );    /* Wait time for message to become available */

The os_mbx_wait function gets a pointer to a message from the mailbox if the mailbox is not empty. The function puts the message pointer from the mailbox into the location pointed by the message argument.

If the mailbox is empty, the RTX kernel puts the calling task to sleep. The timeout specifies the length of time the task can wait for a message. The kernel wakes up the task either when the timeout expires or when a message becomes available in the mailbox.

You can set the timeout to any value between 0 and 0xFFFE. You can set the timeout to 0xFFFF for an indefinite timeout. If you specify the timeout to 0, the calling task continues immediately even if there are higher priority tasks in the ready list, irrespective of whether a message is present in the mailbox or not.

The os_mbx_wait function is in the RL-RTX library. The prototype is defined in rtl.h.

Note

• You must declare and initialize the mailbox object before you perform any operation on it.
• The unit of measure of the timeout argument is numbers of system intervals.
• When you get the message from the mailbox, you must free the memory block containing the message to avoid running out of memory.
• When you get the message from the mailbox, space is created in the mailbox for a new message.

The os_mbx_wait function returns a completion value:

isr_mbx_receive, os_mbx_check, os_mbx_declare, os_mbx_init, os_mbx_send

#include <rtl.h>

os_mbx_declare (mailbox1, 20);

__task void task1 (void){
  void *msg;
   ..
  if (os_mbx_wait (&mailbox1, &msg, 10) == OS_R_TMO) {
    printf ("Wait message timeout!\n");
    }
  else {
    /* process message here */
    free (msg);
  }
   ..
}