NSPR Reference: Chapter 5 Locks
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 5 Locks

This chapter describes the NSPR API for creation and manipulation of a mutex of type `PRLock`.

Lock Type
Lock Functions

In NSPR, a mutex of type `PRLock` controls locking, and associated condition variables communicate changes in state among threads. When a programmer associates a mutex with an arbitrary collection of data, the mutex provides a protective monitor around the data.

In general, a monitor is a conceptual entity composed of a mutex, one or more condition variables, and the monitored data. Monitors in this generic sense should not be confused with monitors used in Java programming. In addition to `PRLock`, NSPR provides another mutex type, `PRMonitor`, which is reentrant and can have only one associated condition variable. `PRMonitor` is intended for use with Java and reflects the Java approach to thread synchronization.

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

For reference information on NSPR condition variables, see Chapter 6 "Condition Variables"

## Lock Type

#### PRLock

A mutual exclusion lock.

##### Syntax

    #include <prlock.h>

    typedef struct PRLock PRLock;

##### Description

NSPR represents a lock as an opaque entity to clients of the functions described in this chapter. Functions that operate on locks do not have timeouts and are not interruptible.

## Lock Functions

`PR_NewLock` creates a new lock object.

- `PR_DestroyLock` destroys a specified lock object.

- `PR_Lock` locks a specified lock object.

- `PR_Unlock` unlocks a specified lock object.

#### PR_NewLock

Creates a new lock.

##### Syntax

    #include <prlock.h>

    PRLock* PR_NewLock(void);

##### Returns

The function returns one of the following values:

If successful, a pointer to the new lock object.

- If unsuccessful (for example, the lock cannot be created because of resource constraints), `NULL`.

##### Description

`PR_NewLock` creates a new opaque lock

#### PR_DestroyLock

Destroys a specified lock object.

##### Syntax

    #include <prlock.h>

    void PR_DestroyLock(PRLock *lock);

##### Parameter

`PR_DestroyLock` has one parameter:

    lock
| A pointer to a lock object.

##### Caution

The caller must ensure that no thread is currently in a lock-specific function. Locks do not provide self-referential protection against deletion.

#### PR_Lock

Locks a specified lock object.

##### Syntax

    #include <prlock.h>

    void PR_Lock(PRLock *lock);

##### Parameter

`PR_Lock` has one parameter:

    lock
| A pointer to the lock object to be locked.

##### Description

When `PR_Lock` returns, the calling thread is "in the monitor," also called "holding the monitor's lock." Any thread that attempts to acquire the same lock blocks until the holder of the lock exits the monitor. Acquiring the lock is not an interruptible operation, nor is there any timeout mechanism.

#### PR_Unlock

Releases a specified lock object. Releasing an unlocked lock results in an error.

##### Syntax

    #include <prlock.h>

    PRStatus PR_UnLock(PRLock *lock);

##### Parameter

`PR_UnLock` has one parameter:

    lock
| A pointer to the lock object to be released.

##### Returns

The function returns one of the following values:

If successful, `PR_Success`.

- If unsuccessful (for example, if the caller does not own the lock), `PR_FAILURE`.

Previous Contents Next

Last Updated May 18, 2001