You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

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.


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