The Tor Browser / file revision

 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */

 /* This Source Code Form is subject to the terms of the Mozilla Public

  * License, v. 2.0. If a copy of the MPL was not distributed with this

  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

 #ifndef prcvar_h___

 #define prcvar_h___

 #include "prlock.h"

 #include "prinrval.h"

 PR_BEGIN_EXTERN_C

 typedef struct PRCondVar PRCondVar;

 /*

 ** Create a new condition variable.

 **

 ** 	"lock" is the lock used to protect the condition variable.

 **

 ** Condition variables are synchronization objects that threads can use

 ** to wait for some condition to occur.

 **

 ** This may fail if memory is tight or if some operating system resource

 ** is low. In such cases, a NULL will be returned.

 */

 NSPR_API(PRCondVar*) PR_NewCondVar(PRLock *lock);

 /*

 ** Destroy a condition variable. There must be no thread

 ** waiting on the condvar. The caller is responsible for guaranteeing

 ** that the condvar is no longer in use.

 **

 */

 NSPR_API(void) PR_DestroyCondVar(PRCondVar *cvar);

 /*

 ** The thread that waits on a condition is blocked in a "waiting on

 ** condition" state until another thread notifies the condition or a

 ** caller specified amount of time expires. The lock associated with

 ** the condition variable will be released, which must have be held

 ** prior to the call to wait.

 **

 ** Logically a notified thread is moved from the "waiting on condition"

 ** state and made "ready." When scheduled, it will attempt to reacquire

 ** the lock that it held when wait was called.

 **

 ** The timeout has two well known values, PR_INTERVAL_NO_TIMEOUT and

 ** PR_INTERVAL_NO_WAIT. The former value requires that a condition be

 ** notified (or the thread interrupted) before it will resume from the

 ** wait. If the timeout has a value of PR_INTERVAL_NO_WAIT, the effect

 ** is to release the lock, possibly causing a rescheduling within the

 ** runtime, then immediately attempting to reacquire the lock and resume.

 **

 ** Any other value for timeout will cause the thread to be rescheduled

 ** either due to explicit notification or an expired interval. The latter

 ** must be determined by treating time as one part of the monitored data

 ** being protected by the lock and tested explicitly for an expired

 ** interval.

 **

 ** Returns PR_FAILURE if the caller has not locked the lock associated

 ** with the condition variable or the thread was interrupted (PR_Interrupt()).

 ** The particular reason can be extracted with PR_GetError().

 */

 NSPR_API(PRStatus) PR_WaitCondVar(PRCondVar *cvar, PRIntervalTime timeout);

 /*

 ** Notify ONE thread that is currently waiting on 'cvar'. Which thread is

 ** dependent on the implementation of the runtime. Common sense would dictate

 ** that all threads waiting on a single condition have identical semantics,

 ** therefore which one gets notified is not significant. 

 **

 ** The calling thead must hold the lock that protects the condition, as

 ** well as the invariants that are tightly bound to the condition, when

 ** notify is called.

 **

 ** Returns PR_FAILURE if the caller has not locked the lock associated

 ** with the condition variable.

 */

 NSPR_API(PRStatus) PR_NotifyCondVar(PRCondVar *cvar);

 /*

 ** Notify all of the threads waiting on the condition variable. The order

 ** that the threads are notified is indeterminant. The lock that protects

 ** the condition must be held.

 **

 ** Returns PR_FAILURE if the caller has not locked the lock associated

 ** with the condition variable.

 */

 NSPR_API(PRStatus) PR_NotifyAllCondVar(PRCondVar *cvar);

 PR_END_EXTERN_C

 #endif /* prcvar_h___ */