📄 kernel-mail-boxes.html
字号:
<!-- 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"><METANAME="GENERATOR"CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+"><LINKREL="HOME"TITLE="eCos Reference Manual"HREF="ecos-ref.html"><LINKREL="UP"TITLE="The eCos Kernel"HREF="kernel.html"><LINKREL="PREVIOUS"TITLE="Semaphores"HREF="kernel-semaphores.html"><LINKREL="NEXT"TITLE="Event Flags"HREF="kernel-flags.html"></HEAD><BODYCLASS="REFENTRY"BGCOLOR="#FFFFFF"TEXT="#000000"LINK="#0000FF"VLINK="#840084"ALINK="#0000FF"><DIVCLASS="NAVHEADER"><TABLESUMMARY="Header navigation table"WIDTH="100%"BORDER="0"CELLPADDING="0"CELLSPACING="0"><TR><THCOLSPAN="3"ALIGN="center">eCos Reference Manual</TH></TR><TR><TDWIDTH="10%"ALIGN="left"VALIGN="bottom"><AHREF="kernel-semaphores.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="80%"ALIGN="center"VALIGN="bottom"></TD><TDWIDTH="10%"ALIGN="right"VALIGN="bottom"><AHREF="kernel-flags.html"ACCESSKEY="N">Next</A></TD></TR></TABLE><HRALIGN="LEFT"WIDTH="100%"></DIV><H1><ANAME="KERNEL-MAIL-BOXES">Mail boxes</H1><DIVCLASS="REFNAMEDIV"><ANAME="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><DIVCLASS="REFSYNOPSISDIV"><ANAME="AEN1439"><H2>Synopsis</H2><DIVCLASS="FUNCSYNOPSIS"><ANAME="AEN1440"><P></P><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="FUNCSYNOPSISINFO">#include <cyg/kernel/kapi.h> </PRE></TD></TR></TABLE><P><CODE><CODECLASS="FUNCDEF">void cyg_mbox_create</CODE>(cyg_handle_t* handle, cyg_mbox* mbox);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void cyg_mbox_delete</CODE>(cyg_handle_t mbox);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void* cyg_mbox_get</CODE>(cyg_handle_t mbox);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void* cyg_mbox_timed_get</CODE>(cyg_handle_t mbox, cyg_tick_count_t abstime);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void* cyg_mbox_tryget</CODE>(cyg_handle_t mbox);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_count32 cyg_mbox_peek</CODE>(cyg_handle_t mbox);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void* cyg_mbox_peek_item</CODE>(cyg_handle_t mbox);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_bool_t cyg_mbox_put</CODE>(cyg_handle_t mbox, void* item);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_bool_t cyg_mbox_timed_put</CODE>(cyg_handle_t mbox, void* item, cyg_tick_count_t abstime);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_bool_t cyg_mbox_tryput</CODE>(cyg_handle_t mbox, void* item);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_bool_t cyg_mbox_waiting_to_get</CODE>(cyg_handle_t mbox);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_bool_t cyg_mbox_waiting_to_put</CODE>(cyg_handle_t mbox);</CODE></P><P></P></DIV></DIV><DIVCLASS="REFSECT1"><ANAME="KERNEL-MAIL-BOXES-DESCRIPTION"></A><H2>Description</H2><P>Mail boxes are a synchronization primitive. Like semaphores theycan be used by a consumer thread to wait until a certain event hasoccurred, but the producer also has the ability to transmit some dataalong with each event. This data, the message, is normally a pointerto some data structure. It is stored in the mail box itself, so theproducer thread that generates the event and provides the data usuallydoes not have to block until some consumer thread is ready to receivethe event. However a mail box will only have a finite capacity,typically ten slots. Even if the system is balanced and events aretypically consumed at least as fast as they are generated, a burst ofevents can cause the mail box to fill up and the generating threadwill block until space is available again. This behaviour is verydifferent from semaphores, where it is only necessary to maintain acounter and hence an overflow is unlikely. </P><P>Before a mail box can be used it must be created with a call to<TTCLASS="FUNCTION">cyg_mbox_create</TT>. Each mail box has a uniquehandle which will be returned via the first argument and which shouldbe used for subsequent operations.<TTCLASS="FUNCTION">cyg_mbox_create</TT> also requires an area of memoryfor the kernel structure, which is provided by the<SPANCLASS="STRUCTNAME">cyg_mbox</SPAN> second argument. If a mail box isno longer required then <TTCLASS="FUNCTION">cyg_mbox_delete</TT> can beused. This will simply discard any messages that remain posted. </P><P>The main function for waiting on a mail box is<TTCLASS="FUNCTION">cyg_mbox_get</TT>. If there is a pending messagebecause of a call to <TTCLASS="FUNCTION">cyg_mbox_put</TT> then<TTCLASS="FUNCTION">cyg_mbox_get</TT> will return immediately with themessage that was put into the mail box. Otherwise this functionwill block until there is a put operation. Exceptionally the threadcan instead be unblocked by a call to<TTCLASS="FUNCTION">cyg_thread_release</TT>, in which case<TTCLASS="FUNCTION">cyg_mbox_get</TT> will return a null pointer. It isassumed that there will never be a call to<TTCLASS="FUNCTION">cyg_mbox_put</TT> with a null pointer, because itwould not be possible to distinguish between that and a releaseoperation. Messages are always retrieved in the order in which theywere put into the mail box, and there is no support for messageswith different priorities. </P><P>There are two variants of <TTCLASS="FUNCTION">cyg_mbox_get</TT>. Thefirst, <TTCLASS="FUNCTION">cyg_mbox_timed_get</TT> will wait until eithera 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 bereturned. <TTCLASS="FUNCTION">cyg_mbox_tryget</TT> is a non-blockingoperation which will either return a message if one is available or anull pointer. </P><P>New messages are placed in the mail box by calling<TTCLASS="FUNCTION">cyg_mbox_put</TT> or one of its variants. The main putfunction takes two arguments, a handle to the mail box and apointer for the message itself. If there is a spare slot in themail box then the new message can be placed there immediately, andif there is a waiting thread it will be woken up so that it canreceive the message. If the mail box is currently full then<TTCLASS="FUNCTION">cyg_mbox_put</TT> will block until there has been aget operation and a slot is available. The<TTCLASS="FUNCTION">cyg_mbox_timed_put</TT> variant imposes a time limiton the put operation, returning false if the operation cannot becompleted within the specified number of clock ticks. The<TTCLASS="FUNCTION">cyg_mbox_tryput</TT> variant is non-blocking,returning false if there are no free slots available and the messagecannot be posted without blocking. </P><P>There are a further four functions available for examining the currentstate of a mailbox. The results of these functions must be used withcare because usually the state can change at any time as a result ofactivity within other threads, but they may prove occasionally usefulduring debugging or in special situations.<TTCLASS="FUNCTION">cyg_mbox_peek</TT> returns a count of the number ofmessages currently stored in the mail box.<TTCLASS="FUNCTION">cyg_mbox_peek_item</TT> retrieves the first message,but it remains in the mail box until a get operation is performed.<TTCLASS="FUNCTION">cyg_mbox_waiting_to_get</TT> and<TTCLASS="FUNCTION">cyg_mbox_waiting_to_put</TT> indicate whether or notthere are currently threads blocked in a get or a put operation on agiven mail box. </P><P>The number of slots in each mail box is controlled by aconfiguration option<TTCLASS="VARNAME">CYGNUM_KERNEL_SYNCH_MBOX_QUEUE_SIZE</TT>, with a defaultvalue of 10. All mail boxes are the same size. </P></DIV><DIVCLASS="REFSECT1"><ANAME="KERNEL-MAIL-BOXES-CONTEXT"></A><H2>Valid contexts</H2><P><TTCLASS="FUNCTION">cyg_mbox_create</TT> is typically called duringsystem initialization but may also be called in thread context.The remaining functions are normally called only during threadcontext. Of special note is <TTCLASS="FUNCTION">cyg_mbox_put</TT> whichcan be a blocking operation when the mail box is full, and whichtherefore must never be called from DSR context. It is permitted tocall <TTCLASS="FUNCTION">cyg_mbox_tryput</TT>,<TTCLASS="FUNCTION">cyg_mbox_tryget</TT>, and the information functionsfrom DSR context but this is rarely useful. </P></DIV><DIVCLASS="NAVFOOTER"><HRALIGN="LEFT"WIDTH="100%"><TABLESUMMARY="Footer navigation table"WIDTH="100%"BORDER="0"CELLPADDING="0"CELLSPACING="0"><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top"><AHREF="kernel-semaphores.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="ecos-ref.html"ACCESSKEY="H">Home</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top"><AHREF="kernel-flags.html"ACCESSKEY="N">Next</A></TD></TR><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top">Semaphores</TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="kernel.html"ACCESSKEY="U">Up</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top">Event Flags</TD></TR></TABLE></DIV></BODY></HTML>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -