VirtualBox

source: vbox/trunk/include/iprt/semaphore.h@ 2225

Last change on this file since 2225 was 204, checked in by vboxsync, 18 years ago

runtime.h now includes everything. Created a new header, initterm.h, which includes the RT*Init/Term() prototypes.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 12.8 KB
Line 
1/** @file
2 * InnoTek Portable Runtime - Semaphore.
3 */
4
5/*
6 * Copyright (C) 2006 InnoTek Systemberatung GmbH
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License as published by the Free Software Foundation,
12 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
13 * distribution. VirtualBox OSE is distributed in the hope that it will
14 * be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * If you received this file as part of a commercial VirtualBox
17 * distribution, then only the terms of your commercial VirtualBox
18 * license agreement apply instead of the previous paragraph.
19 */
20
21#ifndef __iprt_semaphore_h__
22#define __iprt_semaphore_h__
23
24#include <iprt/cdefs.h>
25#include <iprt/types.h>
26
27
28__BEGIN_DECLS
29
30/** @defgroup grp_rt_sems RTSem - Semaphores
31 * @ingroup grp_rt
32 * @{
33 */
34
35
36/**
37 * Create a event semaphore.
38 *
39 * @returns iprt status code.
40 * @param pEventSem Where to store the event semaphore handle.
41 */
42RTDECL(int) RTSemEventCreate(PRTSEMEVENT pEventSem);
43
44/**
45 * Destroy an event semaphore.
46 *
47 * @returns iprt status code.
48 * @param EventSem Handle of the
49 */
50RTDECL(int) RTSemEventDestroy(RTSEMEVENT EventSem);
51
52/**
53 * Signal an event semaphore.
54 *
55 * The event semaphore will be signaled and automatically reset
56 * after exactly one thread have successfully returned from
57 * RTSemEventWait() after waiting/polling on that semaphore.
58 *
59 * @returns iprt status code.
60 * @param EventSem The event semaphore to signal.
61 */
62RTDECL(int) RTSemEventSignal(RTSEMEVENT EventSem);
63
64/**
65 * Wait for the event semaphore to be signaled, resume on interruption.
66 *
67 * This function will resume if the wait is interrupted by an async
68 * system event (like a unix signal) or similar.
69 *
70 * @returns iprt status code.
71 * Will not return VERR_INTERRUPTED.
72 * @param EventSem The event semaphore to wait on.
73 * @param cMillies Number of milliseconds to wait.
74 */
75RTDECL(int) RTSemEventWait(RTSEMEVENT EventSem, unsigned cMillies);
76
77/**
78 * Wait for the event semaphore to be signaled, return on interruption.
79 *
80 * This function will not resume the wait if interrupted.
81 *
82 * @returns iprt status code.
83 * @param EventSem The event semaphore to wait on.
84 * @param cMillies Number of milliseconds to wait.
85 */
86RTDECL(int) RTSemEventWaitNoResume(RTSEMEVENT EventSem, unsigned cMillies);
87
88
89
90/**
91 * Create a event multi semaphore.
92 *
93 * @returns iprt status code.
94 * @param pEventMultiSem Where to store the event multi semaphore handle.
95 */
96RTDECL(int) RTSemEventMultiCreate(PRTSEMEVENTMULTI pEventMultiSem);
97
98/**
99 * Destroy an event multi semaphore.
100 *
101 * @returns iprt status code.
102 * @param EventMultiSem The event multi sempahore to destroy.
103 */
104RTDECL(int) RTSemEventMultiDestroy(RTSEMEVENTMULTI EventMultiSem);
105
106/**
107 * Signal an event multi semaphore.
108 *
109 * @returns iprt status code.
110 * @param EventMultiSem The event multi semaphore to signal.
111 */
112RTDECL(int) RTSemEventMultiSignal(RTSEMEVENTMULTI EventMultiSem);
113
114/**
115 * Resets an event multi semaphore to non-signaled state.
116 *
117 * @returns iprt status code.
118 * @param EventMultiSem The event multi semaphore to reset.
119 */
120RTDECL(int) RTSemEventMultiReset(RTSEMEVENTMULTI EventMultiSem);
121
122/**
123 * Wait for the event multi semaphore to be signaled, resume on interruption.
124 *
125 * This function will resume if the wait is interrupted by an async
126 * system event (like a unix signal) or similar.
127 *
128 * @returns iprt status code.
129 * Will not return VERR_INTERRUPTED.
130 * @param EventMultiSem The event multi semaphore to wait on.
131 * @param cMillies Number of milliseconds to wait.
132 */
133RTDECL(int) RTSemEventMultiWait(RTSEMEVENTMULTI EventMultiSem, unsigned cMillies);
134
135
136/**
137 * Wait for the event multi semaphore to be signaled, return on interruption.
138 *
139 * This function will not resume the wait if interrupted.
140 *
141 * @returns iprt status code.
142 * @param EventMultiSem The event multi semaphore to wait on.
143 * @param cMillies Number of milliseconds to wait.
144 */
145RTDECL(int) RTSemEventMultiWaitNoResume(RTSEMEVENTMULTI EventMultiSem, unsigned cMillies);
146
147
148
149/**
150 * Create a mutex semaphore.
151 *
152 * @returns iprt status code.
153 * @param pMutexSem Where to store the mutex semaphore handle.
154 */
155RTDECL(int) RTSemMutexCreate(PRTSEMMUTEX pMutexSem);
156
157/**
158 * Destroy a mutex semaphore.
159 *
160 * @returns iprt status code.
161 * @param MutexSem The mutex semaphore to destroy.
162 */
163RTDECL(int) RTSemMutexDestroy(RTSEMMUTEX MutexSem);
164
165/**
166 * Request ownership of a mutex semaphore, resume on interruption.
167 *
168 * This function will resume if the wait is interrupted by an async
169 * system event (like a unix signal) or similar.
170 *
171 * The same thread may request a mutex semaphore multiple times,
172 * a nested counter is kept to make sure it's released on the right
173 * RTSemMutexRelease() call.
174 *
175 * @returns iprt status code.
176 * Will not return VERR_INTERRUPTED.
177 * @param MutexSem The mutex semaphore to request ownership over.
178 * @param cMillies The number of milliseconds to wait.
179 */
180RTDECL(int) RTSemMutexRequest(RTSEMMUTEX MutexSem, unsigned cMillies);
181
182/**
183 * Request ownership of a mutex semaphore, return on interruption.
184 *
185 * This function will not resume the wait if interrupted.
186 *
187 * The same thread may request a mutex semaphore multiple times,
188 * a nested counter is kept to make sure it's released on the right
189 * RTSemMutexRelease() call.
190 *
191 * @returns iprt status code.
192 * @param MutexSem The mutex semaphore to request ownership over.
193 * @param cMillies The number of milliseconds to wait.
194 */
195RTDECL(int) RTSemMutexRequestNoResume(RTSEMMUTEX MutexSem, unsigned cMillies);
196
197/**
198 * Release the ownership of a mutex semaphore.
199 *
200 * @returns iprt status code.
201 * @param MutexSem The mutex to release the ownership of.
202 * It goes without saying the the calling thread must own it.
203 */
204RTDECL(int) RTSemMutexRelease(RTSEMMUTEX MutexSem);
205
206
207/**
208 * Create a fast mutex semaphore.
209 *
210 * @returns iprt status code.
211 * @param pMutexSem Where to store the mutex semaphore handle.
212 */
213RTDECL(int) RTSemFastMutexCreate(PRTSEMFASTMUTEX pMutexSem);
214
215/**
216 * Destroy a fast mutex semaphore.
217 *
218 * @returns iprt status code.
219 * @param MutexSem The mutex semaphore to destroy.
220 */
221RTDECL(int) RTSemFastMutexDestroy(RTSEMFASTMUTEX MutexSem);
222
223/**
224 * Request ownership of a fast mutex semaphore.
225 *
226 * The same thread may request a mutex semaphore multiple times,
227 * a nested counter is kept to make sure it's released on the right
228 * RTSemMutexRelease() call.
229 *
230 * @returns iprt status code.
231 * @param MutexSem The mutex semaphore to request ownership over.
232 */
233RTDECL(int) RTSemFastMutexRequest(RTSEMFASTMUTEX MutexSem);
234
235/**
236 * Release the ownership of a fast mutex semaphore.
237 *
238 * @returns iprt status code.
239 * @param MutexSem The mutex to release the ownership of.
240 * It goes without saying the the calling thread must own it.
241 */
242RTDECL(int) RTSemFastMutexRelease(RTSEMFASTMUTEX MutexSem);
243
244
245/**
246 * Creates a read/write semaphore.
247 *
248 * @returns iprt status code.
249 * @param pRWSem Where to store the handle to the created RW semaphore.
250 */
251RTDECL(int) RTSemRWCreate(PRTSEMRW pRWSem);
252
253/**
254 * Destroys a read/write semaphore.
255 *
256 * @returns iprt status code.
257 * @param RWSem The Read/Write semaphore to destroy.
258 */
259RTDECL(int) RTSemRWDestroy(RTSEMRW RWSem);
260
261/**
262 * Request read access to a read/write semaphore, resume on interruption
263 *
264 * Read requests cannot be nested. A deadlock error will be returned
265 * on such attempts.
266 *
267 * @returns iprt status code.
268 * Will not return VERR_INTERRUPTED.
269 * @param RWSem The Read/Write semaphore to request read access to.
270 * @param cMillies The number of milliseconds to wait.
271 */
272RTDECL(int) RTSemRWRequestRead(RTSEMRW RWSem, unsigned cMillies);
273
274/**
275 * Request read access to a read/write semaphore, return on interruption
276 *
277 * Read requests cannot be nested. A deadlock error will be returned
278 * on such attempts.
279 *
280 * @returns iprt status code.
281 * @param RWSem The Read/Write semaphore to request read access to.
282 * @param cMillies The number of milliseconds to wait.
283 */
284RTDECL(int) RTSemRWRequestReadNoResume(RTSEMRW RWSem, unsigned cMillies);
285
286/**
287 * Release read access to a read/write semaphore.
288 *
289 * @returns iprt status code.
290 * @param RWSem The Read/Write sempahore to release read access to.
291 * Goes without saying that caller must have read access to the sem.
292 */
293RTDECL(int) RTSemRWReleaseRead(RTSEMRW RWSem);
294
295/**
296 * Request write access to a read/write semaphore, resume on interruption.
297 *
298 * Write requests cannot be nested. If called by the thread currently owning
299 * the write lock the function returns an error code indicating deadlock.
300 *
301 * @returns iprt status code.
302 * Will not return VERR_INTERRUPTED.
303 * @param RWSem The Read/Write semaphore to request write access to.
304 * @param cMillies The number of milliseconds to wait.
305 */
306RTDECL(int) RTSemRWRequestWrite(RTSEMRW RWSem, unsigned cMillies);
307
308/**
309 * Request write access to a read/write semaphore, return on interruption.
310 *
311 * Write requests cannot be nested. If called by the thread currently owning
312 * the write lock the function returns an error code indicating deadlock.
313 *
314 * @returns iprt status code.
315 * @param RWSem The Read/Write semaphore to request write access to.
316 * @param cMillies The number of milliseconds to wait.
317 */
318RTDECL(int) RTSemRWRequestWriteNoResume(RTSEMRW RWSem, unsigned cMillies);
319
320/**
321 * Release write access to a read/write semaphore.
322 *
323 * @returns iprt status code.
324 * @param RWSem The Read/Write sempahore to release read access to.
325 * Goes without saying that caller must have write access to the sem.
326 */
327RTDECL(int) RTSemRWReleaseWrite(RTSEMRW RWSem);
328
329
330
331/**
332 * Ping-pong speaker
333 */
334typedef enum RTPINGPONGSPEAKER
335{
336 /** Not initialized. */
337 RTPINGPONGSPEAKER_UNINITIALIZE = 0,
338 /** Ping is speaking, Pong is waiting. */
339 RTPINGPONGSPEAKER_PING,
340 /** Pong is signaled, Ping is waiting. */
341 RTPINGPONGSPEAKER_PONG_SIGNALED,
342 /** Pong is speaking, Ping is waiting. */
343 RTPINGPONGSPEAKER_PONG,
344 /** Ping is signaled, Pong is waiting. */
345 RTPINGPONGSPEAKER_PING_SIGNALED,
346 /** Hack to ensure that it's at least 32-bits wide. */
347 RTPINGPONGSPEAKER_HACK = 0x7fffffff
348} RTPINGPONGSPEAKER;
349
350/**
351 * Ping-Pong construct.
352 *
353 * Two threads, one saying Ping and the other saying Pong. The construct
354 * makes sure they don't speak out of turn and that they can wait and poll
355 * on the conversation.
356 */
357typedef struct RTPINGPONG
358{
359 /** The semaphore the Ping thread waits on. */
360 RTSEMEVENT Ping;
361 /** The semaphore the Pong thread waits on. */
362 RTSEMEVENT Pong;
363 /** The current speaker. */
364 volatile RTPINGPONGSPEAKER enmSpeaker;
365#if HC_ARCH_BITS == 64
366 /** Padding the structure to become a multiple of sizeof(RTHCPTR). */
367 uint32_t u32Padding;
368#endif
369} RTPINGPONG;
370/** Pointer to Ping-Pong construct. */
371typedef RTPINGPONG *PRTPINGPONG;
372
373/**
374 * Init a Ping-Pong construct.
375 *
376 * @returns iprt status code.
377 * @param pPP Pointer to the ping-pong structure which needs initialization.
378 */
379RTDECL(int) RTSemPingPongInit(PRTPINGPONG pPP);
380
381/**
382 * Destroys a Ping-Pong construct.
383 *
384 * @returns iprt status code.
385 * @param pPP Pointer to the ping-pong structure which is to be destroyed.
386 * (I.e. put into uninitialized state.)
387 */
388RTDECL(int) RTSemPingPongDestroy(PRTPINGPONG pPP);
389
390/**
391 * Signals the pong thread in a ping-pong construct. (I.e. sends ping.)
392 * This is called by the ping thread.
393 *
394 * @returns iprt status code.
395 * @param pPP Pointer to the ping-pong structure to ping.
396 */
397RTDECL(int) RTSemPing(PRTPINGPONG pPP);
398
399/**
400 * Signals the ping thread in a ping-pong construct. (I.e. sends pong.)
401 * This is called by the pong thread.
402 *
403 * @returns iprt status code.
404 * @param pPP Pointer to the ping-pong structure to pong.
405 */
406RTDECL(int) RTSemPong(PRTPINGPONG pPP);
407
408/**
409 * Wait function for the ping thread.
410 *
411 * @returns iprt status code.
412 * Will not return VERR_INTERRUPTED.
413 * @param pPP Pointer to the ping-pong structure to wait on.
414 * @param cMillies Number of milliseconds to wait.
415 */
416RTDECL(int) RTSemPingWait(PRTPINGPONG pPP, unsigned cMillies);
417
418/**
419 * Wait function for the pong thread.
420 *
421 * @returns iprt status code.
422 * Will not return VERR_INTERRUPTED.
423 * @param pPP Pointer to the ping-pong structure to wait on.
424 * @param cMillies Number of milliseconds to wait.
425 */
426RTDECL(int) RTSemPongWait(PRTPINGPONG pPP, unsigned cMillies);
427
428/** @} */
429
430__END_DECLS
431
432#endif
433
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette