📄 kernel-flags.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>Event Flags</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="Mail boxes"HREF="kernel-mail-boxes.html"><LINKREL="NEXT"TITLE="Spinlocks"HREF="kernel-spinlocks.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-mail-boxes.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="80%"ALIGN="center"VALIGN="bottom"></TD><TDWIDTH="10%"ALIGN="right"VALIGN="bottom"><AHREF="kernel-spinlocks.html"ACCESSKEY="N">Next</A></TD></TR></TABLE><HRALIGN="LEFT"WIDTH="100%"></DIV><H1><ANAME="KERNEL-FLAGS">Event Flags</H1><DIVCLASS="REFNAMEDIV"><ANAME="AEN1555"></A><H2>Name</H2>cyg_flag_init, cyg_flag_destroy, cyg_flag_setbits, cyg_flag_maskbits, cyg_flag_wait, cyg_flag_timed_wait, cyg_flag_poll, cyg_flag_peek, cyg_flag_waiting -- Synchronization primitive</DIV><DIVCLASS="REFSYNOPSISDIV"><ANAME="AEN1566"><H2>Synopsis</H2><DIVCLASS="FUNCSYNOPSIS"><ANAME="AEN1567"><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_flag_init</CODE>(cyg_flag_t* flag);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void cyg_flag_destroy</CODE>(cyg_flag_t* flag);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void cyg_flag_setbits</CODE>(cyg_flag_t* flag, cyg_flag_value_t value);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void cyg_flag_maskbits</CODE>(cyg_flag_t* flag, cyg_flag_value_t value);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_flag_value_t cyg_flag_wait</CODE>(cyg_flag_t* flag, cyg_flag_value_t pattern, cyg_flag_mode_t mode);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_flag_value_t cyg_flag_timed_wait</CODE>(cyg_flag_t* flag, cyg_flag_value_t pattern, cyg_flag_mode_t mode, cyg_tick_count_t abstime);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_flag_value_t cyg_flag_poll</CODE>(cyg_flag_t* flag, cyg_flag_value_t pattern, cyg_flag_mode_t mode);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_flag_value_t cyg_flag_peek</CODE>(cyg_flag_t* flag);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_bool_t cyg_flag_waiting</CODE>(cyg_flag_t* flag);</CODE></P><P></P></DIV></DIV><DIVCLASS="REFSECT1"><ANAME="KERNEL-FLAGS-DESCRIPTION"></A><H2>Description</H2><P>Event flags allow a consumer thread to wait for one of severaldifferent types of event to occur. Alternatively it is possible towait for some combination of events. The implementation is relativelystraightforward. Each event flag contains a 32-bit integer.Application code associates these bits with specific events, so forexample bit 0 could indicate that an I/O operation has completed anddata is available, while bit 1 could indicate that the user haspressed a start button. A producer thread or a DSR can cause one ormore of the bits to be set, and a consumer thread currently waitingfor these bits will be woken up. </P><P>Unlike semaphores no attempt is made to keep track of event counts. Itdoes not matter whether a given event occurs once or multiple timesbefore being consumed, the corresponding bit in the event flag willchange only once. However semaphores cannot easily be used to handlemultiple event sources. Event flags can often be used as analternative to condition variables, although they cannot be used forcompletely arbitrary conditions and they only support the equivalentof condition variable broadcasts, not signals. </P><P>Before an event flag can be used it must be initialized by a call to<TTCLASS="FUNCTION">cyg_flag_init</TT>. This takes a pointer to a<SPANCLASS="STRUCTNAME">cyg_flag_t</SPAN> data structure, which can be part of alarger structure. All 32 bits in the event flag will be set to 0,indicating that no events have yet occurred. If an event flag is nolonger required it can be cleaned up with a call to<TTCLASS="FUNCTION">cyg_flag_destroy</TT>, allowing the memory for the<TTCLASS="STRUCTFIELD"><I>cyg_flag_t</I></TT> structure to be re-used. </P><P>A consumer thread can wait for one or more events by calling<TTCLASS="FUNCTION">cyg_flag_wait</TT>. This takes three arguments. Thefirst identifies a particular event flag. The second is somecombination of bits, indicating which events are of interest. Thefinal argument should be one of the following: </P><P></P><DIVCLASS="VARIABLELIST"><DL><DT><TTCLASS="LITERAL">CYG_FLAG_WAITMODE_AND</TT></DT><DD><P>The call to <TTCLASS="FUNCTION">cyg_flag_wait</TT> will block until allthe specified event bits are set. The event flag is not cleared whenthe wait succeeds, in other words all the bits remain set. </P></DD><DT><TTCLASS="LITERAL">CYG_FLAG_WAITMODE_OR</TT></DT><DD><P>The call will block until at least one of the specified event bits isset. The event flag is not cleared on return. </P></DD><DT><TTCLASS="LITERAL">CYG_FLAG_WAITMODE_AND | CYG_FLAG_WAITMODE_CLR</TT></DT><DD><P>The call will block until all the specified event bits are set, andthe entire event flag is cleared when the call succeeds. Note thatif this mode of operation is used then a single event flag cannot beused to store disjoint sets of events, even though enough bits mightbe available. Instead each disjoint set of events requires its ownevent flag. </P></DD><DT><TTCLASS="LITERAL">CYG_FLAG_WAITMODE_OR | CYG_FLAG_WAITMODE_CLR</TT></DT><DD><P>The call will block until at least one of the specified event bits isset, and the entire flag is cleared when the call succeeds. </P></DD></DL></DIV><P>A call to <TTCLASS="FUNCTION">cyg_flag_wait</TT> normally blocks until therequired condition is satisfied. It will return the value of the eventflag at the point that the operation succeeded, which may be asuperset of the requested events. If<TTCLASS="FUNCTION">cyg_thread_release</TT> is used to unblock a threadthat is currently in a wait operation, the<TTCLASS="FUNCTION">cyg_flag_wait</TT> call will instead return 0. </P><P><TTCLASS="FUNCTION">cyg_flag_timed_wait</TT> is a variant of<TTCLASS="FUNCTION">cyg_flag_wait</TT> which adds a timeout: the waitoperation must succeed within the specified number of ticks, or itwill fail with a return value of 0. <TTCLASS="FUNCTION">cyg_flag_poll</TT>is a non-blocking variant: if the wait operation can succeedimmediately it acts like <TTCLASS="FUNCTION">cyg_flag_wait</TT>, otherwiseit returns immediately with a value of 0. </P><P><TTCLASS="FUNCTION">cyg_flag_setbits</TT> is called by a producer threador from inside a DSR when an event occurs. The specified bits are or'dinto the current event flag value. This may cause a waiting thread tobe woken up, if its condition is now satisfied. </P><P><TTCLASS="FUNCTION">cyg_flag_maskbits</TT> can be used to clear one ormore bits in the event flag. This can be called from a producer when aparticular condition is no longer satisfied, for example when the useris no longer pressing a particular button. It can also be used by aconsumer thread if <TTCLASS="LITERAL">CYG_FLAG_WAITMODE_CLR</TT> was notused as part of the wait operation, to indicate that some but not allof the active events have been consumed. If there are multipleconsumer threads performing wait operations without using<TTCLASS="FUNCTION">CYG_FLAG_WAITMODE_CLR</TT> then typically someadditional synchronization such as a mutex is needed to preventmultiple threads consuming the same event. </P><P>Two additional functions are provided to query the current state of anevent flag. <TTCLASS="FUNCTION">cyg_flag_peek</TT> returns the currentvalue of the event flag, and <TTCLASS="FUNCTION">cyg_flag_waiting</TT> canbe used to find out whether or not there are any threads currentlyblocked on the event flag. Both of these functions must be used withcare because other threads may be operating on the event flag. </P></DIV><DIVCLASS="REFSECT1"><ANAME="KERNEL-FLAGS-CONTEXT"></A><H2>Valid contexts</H2><P><TTCLASS="FUNCTION">cyg_flag_init</TT> is typically called during systeminitialization but may also be called in thread context. The sameapplies to <TTCLASS="FUNCTION">cyg_flag_destroy</TT>.<TTCLASS="FUNCTION">cyg_flag_wait</TT> and<TTCLASS="FUNCTION">cyg_flag_timed_wait</TT> may only be called fromthread context. The remaining functions may be called from thread orDSR context. </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-mail-boxes.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-spinlocks.html"ACCESSKEY="N">Next</A></TD></TR><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top">Mail boxes</TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="kernel.html"ACCESSKEY="U">Up</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top">Spinlocks</TD></TR></TABLE></DIV></BODY></HTML>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -