+++ /dev/null
-<!-- 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
->
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff