1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="The eCos Kernel"
23 HREF="kernel.html"><LINK
25 TITLE="Condition Variables"
26 HREF="kernel-condition-variables.html"><LINK
29 HREF="kernel-mail-boxes.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="kernel-condition-variables.html"
71 HREF="kernel-mail-boxes.html"
82 NAME="KERNEL-SEMAPHORES">Semaphores</H1
90 >cyg_semaphore_init, cyg_semaphore_destroy, cyg_semaphore_wait, cyg_semaphore_timed_wait, cyg_semaphore_post, cyg_semaphore_peek -- Synchronization primitive</DIV
92 CLASS="REFSYNOPSISDIV"
108 CLASS="FUNCSYNOPSISINFO"
109 >#include <cyg/kernel/kapi.h>
118 >void cyg_semaphore_init</CODE
119 >(cyg_sem_t* sem, cyg_count32 val);</CODE
125 >void cyg_semaphore_destroy</CODE
126 >(cyg_sem_t* sem);</CODE
132 >cyg_bool_t cyg_semaphore_wait</CODE
133 >(cyg_sem_t* sem);</CODE
139 >cyg_bool_t cyg_semaphore_timed_wait</CODE
140 >(cyg_sem_t* sem, cyg_tick_count_t abstime);</CODE
146 >cyg_bool_t cyg_semaphore_trywait</CODE
147 >(cyg_sem_t* sem);</CODE
153 >void cyg_semaphore_post</CODE
154 >(cyg_sem_t* sem);</CODE
160 >void cyg_semaphore_peek</CODE
161 >(cyg_sem_t* sem, cyg_count32* val);</CODE
170 NAME="KERNEL-SEMAPHORES-DESCRIPTION"
175 >Counting semaphores are a <A
176 HREF="kernel-overview.html#KERNEL-OVERVIEW-SYNCH-PRIMITIVES"
179 > that allow threads to wait until an event has
180 occurred. The event may be generated by a producer thread, or by a DSR
181 in response to a hardware interrupt. Associated with each semaphore is
182 an integer counter that keeps track of the number of events that have
183 not yet been processed. If this counter is zero, an attempt by a
184 consumer thread to wait on the semaphore will block until some other
185 thread or a DSR posts a new event to the semaphore. If the counter is
186 greater than zero then an attempt to wait on the semaphore will
187 consume one event, in other words decrement the counter, and return
188 immediately. Posting to a semaphore will wake up the first thread that
189 is currently waiting, which will then resume inside the semaphore wait
190 operation and decrement the counter again.
193 >Another use of semaphores is for certain forms of resource management.
194 The counter would correspond to how many of a certain type of resource
195 are currently available, with threads waiting on the semaphore to
196 claim a resource and posting to release the resource again. In
198 HREF="kernel-condition-variables.html"
201 > are usually much better suited for operations like
207 >cyg_semaphore_init</TT
208 > is used to initialize a
209 semaphore. It takes two arguments, a pointer to a
213 > structure and an initial value for
214 the counter. Note that semaphore operations, unlike some other parts
215 of the kernel API, use pointers to data structures rather than
216 handles. This makes it easier to embed semaphores in a larger data
217 structure. The initial counter value can be any number, zero, positive
218 or negative, but typically a value of zero is used to indicate that no
219 events have occurred yet.
224 >cyg_semaphore_wait</TT
225 > is used by a consumer thread
226 to wait for an event. If the current counter is greater than 0, in
227 other words if the event has already occurred in the past, then the
228 counter will be decremented and the call will return immediately.
229 Otherwise the current thread will be blocked until there is a
232 >cyg_semaphore_post</TT
238 >cyg_semaphore_post</TT
239 > is called when an event has
240 occurs. This increments the counter and wakes up the first thread
241 waiting on the semaphore (if any). Usually that thread will then
242 continue running inside <TT
244 >cyg_semaphore_wait</TT
246 decrement the counter again. However other scenarioes are possible.
247 For example the thread calling <TT
249 >cyg_semaphore_post</TT
251 may be running at high priority, some other thread running at medium
252 priority may be about to call <TT
254 >cyg_semaphore_wait</TT
256 when it next gets a chance to run, and a low priority thread may be
257 waiting on the semaphore. What will happen is that the current high
258 priority thread continues running until it is descheduled for some
259 reason, then the medium priority thread runs and its call to
262 >cyg_semaphore_wait</TT
263 > succeeds immediately, and
264 later on the low priority thread runs again, discovers a counter value
265 of 0, and blocks until another event is posted. If there are multiple
266 threads blocked on a semaphore then the configuration option
269 >CYGIMP_KERNEL_SCHED_SORTED_QUEUES</TT
271 one will be woken up by a post operation.
276 >cyg_semaphore_wait</TT
277 > returns a boolean. Normally it
278 will block until it has successfully decremented the counter, retrying
279 as necessary, and return success. However the wait operation may be
280 aborted by a call to <A
281 HREF="kernel-thread-control.html"
284 >cyg_thread_release</TT
289 >cyg_semaphore_wait</TT
290 > will then return false.
295 >cyg_semaphore_timed_wait</TT
299 >cyg_semaphore_wait</TT
300 >. It can be used to wait until
301 either an event has occurred or a number of clock ticks have happened.
302 The function returns success if the semaphore wait operation
303 succeeded, or false if the operation timed out or was aborted by
306 >cyg_thread_release</TT
307 >. If support for the real-time
308 clock has been removed from the current configuration then this
309 function will not be available.
312 >cyg_semaphore_trywait</TT
313 > is another variant which
314 will always return immediately rather than block, again returning
320 >cyg_semaphore_peek</TT
321 > can be used to get hold of the
322 current counter value. This function is rarely useful except for
323 debugging purposes since the counter value may change at any time if
324 some other thread or a DSR performs a semaphore operation.
330 NAME="KERNEL-SEMAPHORES-CONTEXT"
337 >cyg_semaphore_init</TT
338 > is normally called during
339 initialization but may also be called from thread context.
342 >cyg_semaphore_wait</TT
346 >cyg_semaphore_timed_wait</TT
347 > may only be called from
348 thread context because these operations may block.
351 >cyg_semaphore_trywait</TT
355 >cyg_semaphore_post</TT
359 >cyg_semaphore_peek</TT
360 > may be called from thread or
369 SUMMARY="Footer navigation table"
380 HREF="kernel-condition-variables.html"
398 HREF="kernel-mail-boxes.html"
408 >Condition Variables</TD