URL
https://opencores.org/ocsvn/or1k_old/or1k_old/trunk
Subversion Repositories or1k_old
[/] [or1k_old/] [trunk/] [ecos-2.0/] [doc/] [html/] [ref/] [kernel-mail-boxes.html] - Rev 1782
Compare with Previous | Blame | View Log
<!-- Copyright (C) 2003 Red Hat, Inc. -->
<!-- This material may be distributed only subject to the terms -->
<!-- and conditions set forth in the Open Publication License, v1.0 -->
<!-- or later (the latest version is presently available at -->
<!-- http://www.opencontent.org/openpub/). -->
<!-- Distribution of the work or derivative of the work in any -->
<!-- standard (paper) book form is prohibited unless prior -->
<!-- permission is obtained from the copyright holder. -->
<HTML
><HEAD
><TITLE
>Mail boxes</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="eCos Reference Manual"
HREF="ecos-ref.html"><LINK
REL="UP"
TITLE="The eCos Kernel"
HREF="kernel.html"><LINK
REL="PREVIOUS"
TITLE="Semaphores"
HREF="kernel-semaphores.html"><LINK
REL="NEXT"
TITLE="Event Flags"
HREF="kernel-flags.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>eCos Reference Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="kernel-semaphores.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="kernel-flags.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="KERNEL-MAIL-BOXES">Mail boxes</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN1425"
></A
><H2
>Name</H2
>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</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN1439"><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN1440"><P
></P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <cyg/kernel/kapi.h>
</PRE
></TD
></TR
></TABLE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void cyg_mbox_create</CODE
>(cyg_handle_t* handle, cyg_mbox* mbox);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void cyg_mbox_delete</CODE
>(cyg_handle_t mbox);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void* cyg_mbox_get</CODE
>(cyg_handle_t mbox);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void* cyg_mbox_timed_get</CODE
>(cyg_handle_t mbox, cyg_tick_count_t abstime);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void* cyg_mbox_tryget</CODE
>(cyg_handle_t mbox);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>cyg_count32 cyg_mbox_peek</CODE
>(cyg_handle_t mbox);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void* cyg_mbox_peek_item</CODE
>(cyg_handle_t mbox);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>cyg_bool_t cyg_mbox_put</CODE
>(cyg_handle_t mbox, void* item);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>cyg_bool_t cyg_mbox_timed_put</CODE
>(cyg_handle_t mbox, void* item, cyg_tick_count_t abstime);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>cyg_bool_t cyg_mbox_tryput</CODE
>(cyg_handle_t mbox, void* item);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>cyg_bool_t cyg_mbox_waiting_to_get</CODE
>(cyg_handle_t mbox);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>cyg_bool_t cyg_mbox_waiting_to_put</CODE
>(cyg_handle_t mbox);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="KERNEL-MAIL-BOXES-DESCRIPTION"
></A
><H2
>Description</H2
><P
>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.
</P
><P
>Before a mail box can be used it must be created with a call to
<TT
CLASS="FUNCTION"
>cyg_mbox_create</TT
>. Each mail box has a unique
handle which will be returned via the first argument and which should
be used for subsequent operations.
<TT
CLASS="FUNCTION"
>cyg_mbox_create</TT
> also requires an area of memory
for the kernel structure, which is provided by the
<SPAN
CLASS="STRUCTNAME"
>cyg_mbox</SPAN
> second argument. If a mail box is
no longer required then <TT
CLASS="FUNCTION"
>cyg_mbox_delete</TT
> can be
used. This will simply discard any messages that remain posted.
</P
><P
>The main function for waiting on a mail box is
<TT
CLASS="FUNCTION"
>cyg_mbox_get</TT
>. If there is a pending message
because of a call to <TT
CLASS="FUNCTION"
>cyg_mbox_put</TT
> then
<TT
CLASS="FUNCTION"
>cyg_mbox_get</TT
> 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
<TT
CLASS="FUNCTION"
>cyg_thread_release</TT
>, in which case
<TT
CLASS="FUNCTION"
>cyg_mbox_get</TT
> will return a null pointer. It is
assumed that there will never be a call to
<TT
CLASS="FUNCTION"
>cyg_mbox_put</TT
> 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.
</P
><P
>There are two variants of <TT
CLASS="FUNCTION"
>cyg_mbox_get</TT
>. The
first, <TT
CLASS="FUNCTION"
>cyg_mbox_timed_get</TT
> 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. <TT
CLASS="FUNCTION"
>cyg_mbox_tryget</TT
> is a non-blocking
operation which will either return a message if one is available or a
null pointer.
</P
><P
>New messages are placed in the mail box by calling
<TT
CLASS="FUNCTION"
>cyg_mbox_put</TT
> 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
<TT
CLASS="FUNCTION"
>cyg_mbox_put</TT
> will block until there has been a
get operation and a slot is available. The
<TT
CLASS="FUNCTION"
>cyg_mbox_timed_put</TT
> 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
<TT
CLASS="FUNCTION"
>cyg_mbox_tryput</TT
> variant is non-blocking,
returning false if there are no free slots available and the message
cannot be posted without blocking.
</P
><P
>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.
<TT
CLASS="FUNCTION"
>cyg_mbox_peek</TT
> returns a count of the number of
messages currently stored in the mail box.
<TT
CLASS="FUNCTION"
>cyg_mbox_peek_item</TT
> retrieves the first message,
but it remains in the mail box until a get operation is performed.
<TT
CLASS="FUNCTION"
>cyg_mbox_waiting_to_get</TT
> and
<TT
CLASS="FUNCTION"
>cyg_mbox_waiting_to_put</TT
> indicate whether or not
there are currently threads blocked in a get or a put operation on a
given mail box.
</P
><P
>The number of slots in each mail box is controlled by a
configuration option
<TT
CLASS="VARNAME"
>CYGNUM_KERNEL_SYNCH_MBOX_QUEUE_SIZE</TT
>, with a default
value of 10. All mail boxes are the same size.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="KERNEL-MAIL-BOXES-CONTEXT"
></A
><H2
>Valid contexts</H2
><P
><TT
CLASS="FUNCTION"
>cyg_mbox_create</TT
> 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 <TT
CLASS="FUNCTION"
>cyg_mbox_put</TT
> 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 <TT
CLASS="FUNCTION"
>cyg_mbox_tryput</TT
>,
<TT
CLASS="FUNCTION"
>cyg_mbox_tryget</TT
>, and the information functions
from DSR context but this is rarely useful.
</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="kernel-semaphores.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ecos-ref.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="kernel-flags.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Semaphores</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="kernel.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Event Flags</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>