nsprpub/pr/include/prcvar.h@44a2da4a2ab2 (annotated)
nsprpub/pr/include/prcvar.h
Fri, 16 Jan 2015 04:50:19 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Fri, 16 Jan 2015 04:50:19 +0100
- branch
- TOR_BUG_9701
- changeset 13
- 44a2da4a2ab2
- permissions
- -rw-r--r--
Replace accessor implementation with direct member state manipulation, by
request https://trac.torproject.org/projects/tor/ticket/9701#comment:32
| michael@0 | 1 | /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ |
| michael@0 | 2 | /* This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 3 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 4 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 5 | |
| michael@0 | 6 | #ifndef prcvar_h___ |
| michael@0 | 7 | #define prcvar_h___ |
| michael@0 | 8 | |
| michael@0 | 9 | #include "prlock.h" |
| michael@0 | 10 | #include "prinrval.h" |
| michael@0 | 11 | |
| michael@0 | 12 | PR_BEGIN_EXTERN_C |
| michael@0 | 13 | |
| michael@0 | 14 | typedef struct PRCondVar PRCondVar; |
| michael@0 | 15 | |
| michael@0 | 16 | /* |
| michael@0 | 17 | ** Create a new condition variable. |
| michael@0 | 18 | ** |
| michael@0 | 19 | ** "lock" is the lock used to protect the condition variable. |
| michael@0 | 20 | ** |
| michael@0 | 21 | ** Condition variables are synchronization objects that threads can use |
| michael@0 | 22 | ** to wait for some condition to occur. |
| michael@0 | 23 | ** |
| michael@0 | 24 | ** This may fail if memory is tight or if some operating system resource |
| michael@0 | 25 | ** is low. In such cases, a NULL will be returned. |
| michael@0 | 26 | */ |
| michael@0 | 27 | NSPR_API(PRCondVar*) PR_NewCondVar(PRLock *lock); |
| michael@0 | 28 | |
| michael@0 | 29 | /* |
| michael@0 | 30 | ** Destroy a condition variable. There must be no thread |
| michael@0 | 31 | ** waiting on the condvar. The caller is responsible for guaranteeing |
| michael@0 | 32 | ** that the condvar is no longer in use. |
| michael@0 | 33 | ** |
| michael@0 | 34 | */ |
| michael@0 | 35 | NSPR_API(void) PR_DestroyCondVar(PRCondVar *cvar); |
| michael@0 | 36 | |
| michael@0 | 37 | /* |
| michael@0 | 38 | ** The thread that waits on a condition is blocked in a "waiting on |
| michael@0 | 39 | ** condition" state until another thread notifies the condition or a |
| michael@0 | 40 | ** caller specified amount of time expires. The lock associated with |
| michael@0 | 41 | ** the condition variable will be released, which must have be held |
| michael@0 | 42 | ** prior to the call to wait. |
| michael@0 | 43 | ** |
| michael@0 | 44 | ** Logically a notified thread is moved from the "waiting on condition" |
| michael@0 | 45 | ** state and made "ready." When scheduled, it will attempt to reacquire |
| michael@0 | 46 | ** the lock that it held when wait was called. |
| michael@0 | 47 | ** |
| michael@0 | 48 | ** The timeout has two well known values, PR_INTERVAL_NO_TIMEOUT and |
| michael@0 | 49 | ** PR_INTERVAL_NO_WAIT. The former value requires that a condition be |
| michael@0 | 50 | ** notified (or the thread interrupted) before it will resume from the |
| michael@0 | 51 | ** wait. If the timeout has a value of PR_INTERVAL_NO_WAIT, the effect |
| michael@0 | 52 | ** is to release the lock, possibly causing a rescheduling within the |
| michael@0 | 53 | ** runtime, then immediately attempting to reacquire the lock and resume. |
| michael@0 | 54 | ** |
| michael@0 | 55 | ** Any other value for timeout will cause the thread to be rescheduled |
| michael@0 | 56 | ** either due to explicit notification or an expired interval. The latter |
| michael@0 | 57 | ** must be determined by treating time as one part of the monitored data |
| michael@0 | 58 | ** being protected by the lock and tested explicitly for an expired |
| michael@0 | 59 | ** interval. |
| michael@0 | 60 | ** |
| michael@0 | 61 | ** Returns PR_FAILURE if the caller has not locked the lock associated |
| michael@0 | 62 | ** with the condition variable or the thread was interrupted (PR_Interrupt()). |
| michael@0 | 63 | ** The particular reason can be extracted with PR_GetError(). |
| michael@0 | 64 | */ |
| michael@0 | 65 | NSPR_API(PRStatus) PR_WaitCondVar(PRCondVar *cvar, PRIntervalTime timeout); |
| michael@0 | 66 | |
| michael@0 | 67 | /* |
| michael@0 | 68 | ** Notify ONE thread that is currently waiting on 'cvar'. Which thread is |
| michael@0 | 69 | ** dependent on the implementation of the runtime. Common sense would dictate |
| michael@0 | 70 | ** that all threads waiting on a single condition have identical semantics, |
| michael@0 | 71 | ** therefore which one gets notified is not significant. |
| michael@0 | 72 | ** |
| michael@0 | 73 | ** The calling thead must hold the lock that protects the condition, as |
| michael@0 | 74 | ** well as the invariants that are tightly bound to the condition, when |
| michael@0 | 75 | ** notify is called. |
| michael@0 | 76 | ** |
| michael@0 | 77 | ** Returns PR_FAILURE if the caller has not locked the lock associated |
| michael@0 | 78 | ** with the condition variable. |
| michael@0 | 79 | */ |
| michael@0 | 80 | NSPR_API(PRStatus) PR_NotifyCondVar(PRCondVar *cvar); |
| michael@0 | 81 | |
| michael@0 | 82 | /* |
| michael@0 | 83 | ** Notify all of the threads waiting on the condition variable. The order |
| michael@0 | 84 | ** that the threads are notified is indeterminant. The lock that protects |
| michael@0 | 85 | ** the condition must be held. |
| michael@0 | 86 | ** |
| michael@0 | 87 | ** Returns PR_FAILURE if the caller has not locked the lock associated |
| michael@0 | 88 | ** with the condition variable. |
| michael@0 | 89 | */ |
| michael@0 | 90 | NSPR_API(PRStatus) PR_NotifyAllCondVar(PRCondVar *cvar); |
| michael@0 | 91 | |
| michael@0 | 92 | PR_END_EXTERN_C |
| michael@0 | 93 | |
| michael@0 | 94 | #endif /* prcvar_h___ */ |
