eCosTM Reference Manual
Prev | Chapter 5. Native kernel C language API | Next

# Message boxes

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 17). The default value is 10.

Blocking, non-blocking and “blocking with time-out” 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 17).

`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 17).

`cyg_bool_t cyg_mbox_timed_put`(cyg_handle_t mbox, void *item, cyg_tick_count_t abstime);

A time-out 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 17 and the section called Option: Allow per-thread timers in Chapter 17).

`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.

Prev | Home | Next
Memory pools | Up | Flags