#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);
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. -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. 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. -
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. -