📄 kernel-semaphores.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>Semaphores</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="Condition Variables"HREF="kernel-condition-variables.html"><LINKREL="NEXT"TITLE="Mail boxes"HREF="kernel-mail-boxes.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-condition-variables.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="80%"ALIGN="center"VALIGN="bottom"></TD><TDWIDTH="10%"ALIGN="right"VALIGN="bottom"><AHREF="kernel-mail-boxes.html"ACCESSKEY="N">Next</A></TD></TR></TABLE><HRALIGN="LEFT"WIDTH="100%"></DIV><H1><ANAME="KERNEL-SEMAPHORES">Semaphores</H1><DIVCLASS="REFNAMEDIV"><ANAME="AEN1330"></A><H2>Name</H2>cyg_semaphore_init, cyg_semaphore_destroy, cyg_semaphore_wait, cyg_semaphore_timed_wait, cyg_semaphore_post, cyg_semaphore_peek -- Synchronization primitive</DIV><DIVCLASS="REFSYNOPSISDIV"><ANAME="AEN1338"><H2>Synopsis</H2><DIVCLASS="FUNCSYNOPSIS"><ANAME="AEN1339"><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_semaphore_init</CODE>(cyg_sem_t* sem, cyg_count32 val);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void cyg_semaphore_destroy</CODE>(cyg_sem_t* sem);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_bool_t cyg_semaphore_wait</CODE>(cyg_sem_t* sem);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_bool_t cyg_semaphore_timed_wait</CODE>(cyg_sem_t* sem, cyg_tick_count_t abstime);</CODE></P><P><CODE><CODECLASS="FUNCDEF">cyg_bool_t cyg_semaphore_trywait</CODE>(cyg_sem_t* sem);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void cyg_semaphore_post</CODE>(cyg_sem_t* sem);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void cyg_semaphore_peek</CODE>(cyg_sem_t* sem, cyg_count32* val);</CODE></P><P></P></DIV></DIV><DIVCLASS="REFSECT1"><ANAME="KERNEL-SEMAPHORES-DESCRIPTION"></A><H2>Description</H2><P>Counting semaphores are a <AHREF="kernel-overview.html#KERNEL-OVERVIEW-SYNCH-PRIMITIVES">synchronizationprimitive</A> that allow threads to wait until an event hasoccurred. The event may be generated by a producer thread, or by a DSRin response to a hardware interrupt. Associated with each semaphore isan integer counter that keeps track of the number of events that havenot yet been processed. If this counter is zero, an attempt by aconsumer thread to wait on the semaphore will block until some otherthread or a DSR posts a new event to the semaphore. If the counter isgreater than zero then an attempt to wait on the semaphore willconsume one event, in other words decrement the counter, and returnimmediately. Posting to a semaphore will wake up the first thread thatis currently waiting, which will then resume inside the semaphore waitoperation and decrement the counter again. </P><P>Another use of semaphores is for certain forms of resource management.The counter would correspond to how many of a certain type of resourceare currently available, with threads waiting on the semaphore toclaim a resource and posting to release the resource again. Inpractice <AHREF="kernel-condition-variables.html">conditionvariables</A> are usually much better suited for operations likethis. </P><P><TTCLASS="FUNCTION">cyg_semaphore_init</TT> is used to initialize asemaphore. It takes two arguments, a pointer to a<SPANCLASS="STRUCTNAME">cyg_sem_t</SPAN> structure and an initial value forthe counter. Note that semaphore operations, unlike some other partsof the kernel API, use pointers to data structures rather thanhandles. This makes it easier to embed semaphores in a larger datastructure. The initial counter value can be any number, zero, positiveor negative, but typically a value of zero is used to indicate that noevents have occurred yet. </P><P><TTCLASS="FUNCTION">cyg_semaphore_wait</TT> is used by a consumer threadto wait for an event. If the current counter is greater than 0, inother words if the event has already occurred in the past, then thecounter will be decremented and the call will return immediately.Otherwise the current thread will be blocked until there is a<TTCLASS="FUNCTION">cyg_semaphore_post</TT> call. </P><P><TTCLASS="FUNCTION">cyg_semaphore_post</TT> is called when an event hasoccurs. This increments the counter and wakes up the first threadwaiting on the semaphore (if any). Usually that thread will thencontinue running inside <TTCLASS="FUNCTION">cyg_semaphore_wait</TT> anddecrement the counter again. However other scenarioes are possible.For example the thread calling <TTCLASS="FUNCTION">cyg_semaphore_post</TT>may be running at high priority, some other thread running at mediumpriority may be about to call <TTCLASS="FUNCTION">cyg_semaphore_wait</TT>when it next gets a chance to run, and a low priority thread may bewaiting on the semaphore. What will happen is that the current highpriority thread continues running until it is descheduled for somereason, then the medium priority thread runs and its call to<TTCLASS="FUNCTION">cyg_semaphore_wait</TT> succeeds immediately, andlater on the low priority thread runs again, discovers a counter valueof 0, and blocks until another event is posted. If there are multiplethreads blocked on a semaphore then the configuration option<TTCLASS="VARNAME">CYGIMP_KERNEL_SCHED_SORTED_QUEUES</TT> determines whichone will be woken up by a post operation. </P><P><TTCLASS="FUNCTION">cyg_semaphore_wait</TT> returns a boolean. Normally itwill block until it has successfully decremented the counter, retryingas necessary, and return success. However the wait operation may beaborted by a call to <AHREF="kernel-thread-control.html"><TTCLASS="FUNCTION">cyg_thread_release</TT></A>,and <TTCLASS="FUNCTION">cyg_semaphore_wait</TT> will then return false. </P><P><TTCLASS="FUNCTION">cyg_semaphore_timed_wait</TT> is a variant of<TTCLASS="FUNCTION">cyg_semaphore_wait</TT>. It can be used to wait untileither an event has occurred or a number of clock ticks have happened.The function returns success if the semaphore wait operationsucceeded, or false if the operation timed out or was aborted by<TTCLASS="FUNCTION">cyg_thread_release</TT>. If support for the real-timeclock has been removed from the current configuration then thisfunction will not be available.<TTCLASS="FUNCTION">cyg_semaphore_trywait</TT> is another variant whichwill always return immediately rather than block, again returningsuccess or failure. </P><P><TTCLASS="FUNCTION">cyg_semaphore_peek</TT> can be used to get hold of thecurrent counter value. This function is rarely useful except fordebugging purposes since the counter value may change at any time ifsome other thread or a DSR performs a semaphore operation. </P></DIV><DIVCLASS="REFSECT1"><ANAME="KERNEL-SEMAPHORES-CONTEXT"></A><H2>Valid contexts</H2><P><TTCLASS="FUNCTION">cyg_semaphore_init</TT> is normally called duringinitialization but may also be called from thread context.<TTCLASS="FUNCTION">cyg_semaphore_wait</TT> and<TTCLASS="FUNCTION">cyg_semaphore_timed_wait</TT> may only be called fromthread context because these operations may block.<TTCLASS="FUNCTION">cyg_semaphore_trywait</TT>,<TTCLASS="FUNCTION">cyg_semaphore_post</TT> and<TTCLASS="FUNCTION">cyg_semaphore_peek</TT> 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-condition-variables.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-mail-boxes.html"ACCESSKEY="N">Next</A></TD></TR><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top">Condition Variables</TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="kernel.html"ACCESSKEY="U">Up</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top">Mail boxes</TD></TR></TABLE></DIV></BODY></HTML>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -