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