eCos Reference Manual
Prev |  | Next

# Mail boxes

## Name

cyg_mbox_create, cyg_mbox_delete, cyg_mbox_get, cyg_mbox_timed_get, cyg_mbox_tryget, cyg_mbox_peek_item, cyg_mbox_put, cyg_mbox_timed_put, cyg_mbox_tryput, cyg_mbox_peek, cyg_mbox_waiting_to_get, cyg_mbox_waiting_to_put -- Synchronization primitive

## Synopsis

    #include <cyg/kernel/kapi.h>

``void cyg_mbox_create`(cyg_handle_t* handle, cyg_mbox* mbox);`

``void cyg_mbox_delete`(cyg_handle_t mbox);`

``void* cyg_mbox_get`(cyg_handle_t mbox);`

``void* cyg_mbox_timed_get`(cyg_handle_t mbox, cyg_tick_count_t abstime);`

``void* cyg_mbox_tryget`(cyg_handle_t mbox);`

``cyg_count32 cyg_mbox_peek`(cyg_handle_t mbox);`

``void* cyg_mbox_peek_item`(cyg_handle_t mbox);`

``cyg_bool_t cyg_mbox_put`(cyg_handle_t mbox, void* item);`

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

``cyg_bool_t cyg_mbox_tryput`(cyg_handle_t mbox, void* item);`

``cyg_bool_t cyg_mbox_waiting_to_get`(cyg_handle_t mbox);`

``cyg_bool_t cyg_mbox_waiting_to_put`(cyg_handle_t mbox);`

## Description

Mail boxes are a synchronization primitive. Like semaphores they can be used by a consumer thread to wait until a certain event has occurred, but the producer also has the ability to transmit some data along with each event. This data, the message, is normally a pointer to some data structure. It is stored in the mail box itself, so the producer thread that generates the event and provides the data usually does not have to block until some consumer thread is ready to receive the event. However a mail box will only have a finite capacity, typically ten slots. Even if the system is balanced and events are typically consumed at least as fast as they are generated, a burst of events can cause the mail box to fill up and the generating thread will block until space is available again. This behaviour is very different from semaphores, where it is only necessary to maintain a counter and hence an overflow is unlikely.

Before a mail box can be used it must be created with a call to `cyg_mbox_create`. Each mail box has a unique handle which will be returned via the first argument and which should be used for subsequent operations. `cyg_mbox_create` also requires an area of memory for the kernel structure, which is provided by the `cyg_mbox` second argument. If a mail box is no longer required then `cyg_mbox_delete` can be used. This will simply discard any messages that remain posted.

The main function for waiting on a mail box is `cyg_mbox_get`. If there is a pending message because of a call to `cyg_mbox_put` then `cyg_mbox_get` will return immediately with the message that was put into the mail box. Otherwise this function will block until there is a put operation. Exceptionally the thread can instead be unblocked by a call to `cyg_thread_release`, in which case `cyg_mbox_get` will return a null pointer. It is assumed that there will never be a call to `cyg_mbox_put` with a null pointer, because it would not be possible to distinguish between that and a release operation. Messages are always retrieved in the order in which they were put into the mail box, and there is no support for messages with different priorities.

There are two variants of `cyg_mbox_get`. The first, `cyg_mbox_timed_get` will wait until either a message is available or until a number of clock ticks have occurred. The number of ticks is specified as an absolute, not relative tick count, and so in order to wait for a relative number of ticks, the return value of the `cyg_current_time()` function should be added to determine the absolute number of ticks. If no message is posted within the timeout then a null pointer will be returned. `cyg_mbox_tryget` is a non-blocking operation which will either return a message if one is available or a null pointer.

New messages are placed in the mail box by calling `cyg_mbox_put` or one of its variants. The main put function takes two arguments, a handle to the mail box and a pointer for the message itself. If there is a spare slot in the mail box then the new message can be placed there immediately, and if there is a waiting thread it will be woken up so that it can receive the message. If the mail box is currently full then `cyg_mbox_put` will block until there has been a get operation and a slot is available. The `cyg_mbox_timed_put` variant imposes a time limit on the put operation, returning false if the operation cannot be completed within the specified number of clock ticks and as for `cyg_mbox_timed_get` this is an absolute tick count. The `cyg_mbox_tryput` variant is non-blocking, returning false if there are no free slots available and the message cannot be posted without blocking.

There are a further four functions available for examining the current state of a mailbox. The results of these functions must be used with care because usually the state can change at any time as a result of activity within other threads, but they may prove occasionally useful during debugging or in special situations. `cyg_mbox_peek` returns a count of the number of messages currently stored in the mail box. `cyg_mbox_peek_item` retrieves the first message, but it remains in the mail box until a get operation is performed. `cyg_mbox_waiting_to_get` and `cyg_mbox_waiting_to_put` indicate whether or not there are currently threads blocked in a get or a put operation on a given mail box.

The number of slots in each mail box is controlled by a configuration option CYGNUM_KERNEL_SYNCH_MBOX_QUEUE_SIZE, with a default value of 10. All mail boxes are the same size.

## Valid contexts

`cyg_mbox_create` is typically called during system initialization but may also be called in thread context. The remaining functions are normally called only during thread context. Of special note is `cyg_mbox_put` which can be a blocking operation when the mail box is full, and which therefore must never be called from DSR context. It is permitted to call `cyg_mbox_tryput`, `cyg_mbox_tryget`, and the information functions from DSR context but this is rarely useful.

Prev | Home | Next
Semaphores | Up | Event Flags