Valid contexts – Comtrol eCos User Manual
Page 78
Mail boxes
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
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.
78