NSPR Reference: Chapter 6 Condition Variables
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

NSPR Reference Previous Contents Next

## Chapter 6 Condition Variables

This chapter describes the API for creating and destroying condition variables, notifying condition variables of changes in monitored data, and making a thread wait on such notification.

Condition Variable Type
Condition Variable Functions

Conditions are closely associated with a single monitor, which typically consists of a mutex, one or more condition variables, and the monitored data. The association between a condition and a monitor is established when a condition variable is created, and the association persists for its life. In addition, a static association exists between the condition and some data within the monitor. This data is what will be manipulated by the program under the protection of the monitor.

A call to `PR_WaitCondVar` causes a thread to block until a specified condition variable receives notification of a change of state in its associated monitored data. Other threads may notify the condition variable when changes occur.

For an introduction to NSPR thread synchronization, including locks and condition variables, see Chapter 1 "Introduction to NSPR"

For reference information on NSPR locks, see Chapter 5 "Locks"

NSPR provides a special type, `PRMonitor`, for use with Java. Unlike a mutex of type `PRLock`, which can have multiple associated condition variables of type `PRCondVar`, a mutex of type `PRMonitor` has a single, implicitly associated condition variable. For information about `PRMonitor`, see Chapter 7 "Monitors"

## Condition Variable Type

#### PRCondVar

Structure for a condition variable.

##### Syntax

    #include <prcvar.h>

    typedef struct PRCondVar PRCondVar;

##### Description

An NSPR condition variable is an opaque object identified by a pointer.

## Condition Variable Functions

`PR_NewCondVar``
` `PR_DestroyCondVar``
` `PR_WaitCondVar``
` `PR_NotifyCondVar``
` `PR_NotifyAllCondVar```

#### PR_NewCondVar

Creates a new condition variable.

##### Syntax

    #include <prcvar.h>

    PRCondVar* PR_NewCondVar(PRLock *lock);

##### Parameter

`PR_NewCondVar` has one parameter:

    lock
| The identity of the mutex that protects the monitored data, including this condition variable.

##### Returns

The function returns one of the following values:

If successful, a pointer to the new condition variable object.

- If unsuccessful (for example, if system resources are unavailable), `NULL`.

#### PR_DestroyCondVar

Destroys a condition variable.

##### Syntax

    #include <prcvar.h>

    void PR_DestroyCondVar(PRCondVar *cvar);

##### Parameter

`PR_DestroyCondVar` has one parameter:

    cvar
| A pointer to the condition variable object to be destroyed.

##### Description

Before calling `PR_DestroyCondVar`, the caller is responsible for ensuring that the condition variable is no longer in use.

#### PR_WaitCondVar

Waits on a condition.

##### Syntax

    #include <prcvar.h>

    PRStatus PR_WaitCondVar(
       PRCondVar *cvar,
       PRIntervalTime timeout);

##### Parameters

`PR_WaitCondVar` has the following parameters:

    cvar
| The condition variable on which to wait.
    timeout
| The value `PR_INTERVAL_NO_TIMEOUT` requires that a condition be notified (or the thread interrupted) before it will resume from the wait. The value `PR_INTERVAL_NO_WAIT` causes the thread to release the lock, possibly causing a rescheduling within the runtime, then immediately attempt to reacquire the lock and resume.

##### Returns

The function returns one of the following values:

If successful, `PR_SUCCESS`.

- If unsuccessful (for example, if the caller has not locked the lock associated with the condition variable or the thread was interrupted with `PR_Interrupt`), `PR_FAILURE.` The details can be determined with `PR_GetError`.

##### Description

Before the call to `PR_WaitCondVar`, the lock associated with the condition variable must be held by the calling thread. After a call to `PR_WaitCondVar`, the lock is released and the thread is blocked in a "waiting on condition" state until another thread notifies the condition or a caller-specified amount of time expires.

When the condition variable is notified, a thread waiting on that condition moves from the "waiting on condition" state to the "ready" state. When scheduled, the thread attemps to reacquire the lock that it held when `PR_WaitCondVar` was called.

Any value other than `PR_INTERVAL_NO_TIMEOUT` or `PR_INTERVAL_NO_WAIT` for the timeout parameter will cause the thread to be rescheduled due to either explicit notification or the expiration of the specified 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.

#### PR_NotifyCondVar

Notifies a condition variable of a change in its associated monitored data.

##### Syntax

    #include <prcvar.h>

    PRStatus PR_NotifyCondVar(PRCondVar *cvar);

##### Parameter

`PR_NotifyCondVar` has one parameter:

    cvar
| The condition variable to notify.

##### Returns

The function returns one of the following values:

If successful, `PR_SUCCESS`.

- If unsuccessful (for example, if the caller has not locked the lock associated with the condition variable), `PR_FAILURE`.

##### Description

The calling thread must hold the lock that protects the condition, as well as the invariants that are tightly bound to the condition.

Notification of a condition variable signals a change of state in some monitored data. When the notification occurs, the runtime promotes a thread that is waiting on the condition variable to a ready state. If more than one thread is waiting, the selection of which thread gets promoted cannot be predicted. This implies that all threads waiting on a single condition variable must have the same semantics. If no thread is waiting on the condition variable, the notify operation is a no-op.

#### PR_NotifyAllCondVar

Notifies all of the threads waiting on a specified condition variable.

##### Syntax

    #include <prcvar.h>

    PRStatus PR_NotifyAllCondVar(PRCondVar *cvar);

##### Returns

The function returns one of the following values:

If successful, `PR_SUCCESS`.

- If unsuccessful (for example, if the caller has not locked the lock associated with the condition variable), `PR_FAILURE`

##### Description

The calling thread must hold the lock that protects the condition, as well as the invariants that are tightly bound to the condition.

A call to `PR_NotifyAllCondVar` causes all of the threads waiting on the specified condition variable to be promoted to a ready state. If no threads are waiting, the operation is no-op.

Previous Contents Next

Last Updated May 18, 2001