Message boxes are a primitive mechanism for exchanging messages between threads, inspired by the µITRON specification. A message box can be created with cyg_mbox_create() before the scheduler is started, and two threads in a typical producer/consumer relationship can access it. One thread, the producer, will use cyg_mbox_put() to make data available to the consumer thread which uses cyg_mbox_get() to access the data.
The size of the internal message queue is configured by the CYGNUM_KERNEL_SYNCH_MBOX_QUEUE_SIZE parameter (see the section called Option: Message box queue size in Chapter 14). The default value is 10.
Blocking, non-blocking and "blocking with timeout" versions of these calls are provided.
void cyg_mbox_create(cyg_handle_t *handle, cyg_mbox *mbox);Creates a message box using the space provided in the mbox parameter, and returns a handle for future access to that message box.
void cyg_mbox_delete(cyg_handle_t mbox);Deletes the given message box.
void *cyg_mbox_get(cyg_handle_t mbox);Waits for a message to be available, then retrieves it and returns the address of the data.
void *cyg_mbox_timed_get(cyg_handle_t mbox, cyg_tick_count_t timeout);Waits for a message to be available, but times out if timeout time passes. This version of the function is only available if the configuration option CYGFUN_KERNEL_THREADS_TIMER is turned on (see the section called Option: Allow per-thread timers in Chapter 14).
void *cyg_mbox_tryget(cyg_handle_t mbox);Checks to see if a message is ready. If no message is available it returns immediately with a return value of NULL. If a message is available it retrieves it and returns the address of the data.
void
*cyg_mbox_peek_item(cyg_handle_t mbox);Checks to see if a message is ready, and if one is available returns the address of the data without removing the message from the queue. If no message is available it returns NULL.
cyg_bool_t
cyg_mbox_put(cyg_handle_t mbox, void *item);Places a message in the given message box. If the queue is full it will block until the message can be sent. It returns true if the message was successfully sent, and false if the message was not sent and its sleep was awakened by the kernel before the message could be sent.
The cyg_mbox_put() function is only available if the CYGMTH_MBOXT_PUT_CAN_WAIT configuration has been selected (see the section called Option: Message box blocking put support in Chapter 14).
cyg_bool_t
cyg_mbox_timed_put(cyg_handle_t mbox, void *item, cyg_tick_count_t
abstime);A timeout version of cyg_mbox_put(). This will try to place the message in the given message box. If the queue is full, it will wait until abstime before giving up and returning false.
The cyg_mbox_timed_put() function is only available if the both the CYGMFN_KERNEL_SYNCH_MBOXT_PUT_CAN_WAIT and CYGFUN_KERNEL_THREADS_TIMER configuration have been selected (see the section called Option: Message box blocking put support in Chapter 14 and the section called Option: Allow per-thread timers in Chapter 14).
cyg_bool_t
cyg_mbox_tryput(cyg_handle_t mbox, void *item);Tries to place a message in the given message box. It returns true if the message was successfully sent, and false if the message could not be sent immediately, usually because the queue was full.
cyg_count32
cyg_mbox_peek(cyg_handle_t mbox);Takes a peek at the queue and returns the number of messages waiting in it.
cyg_bool_t
cyg_mbox_waiting_to_get(cyg_handle_t mbox);Queries the kernel to see if other processes are waiting to receive a message in the given message box. Returns true if other processes are waiting, false otherwise.
cyg_bool_t
cyg_mbox_waiting_to_put(cyg_handle_t mbox);Queries the kernel to see if other processes are waiting to send a message in the given message box. Returns true if other processes are waiting, false otherwise.