NSPR Reference: Chapter 8 Cached Monitors
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 8 Cached Monitors

This chapter describes the functions you use when you work with cached monitors. Unlike a plain monitor, a cached monitor is associated with the address of a protected object, and the association is maintained only while the protection is needed. This arrangement allows a cached monitor to be associated with another object without preallocating a monitor for all objects. A hash table is used to quickly map addresses to their respective monitors. The system automatically enlarges the hash table as needed.

##### Important

Cached monitors are slower to use than their uncached counterparts.

See Chapter 7 "Monitors" for information about uncached monitors.

## Cached Monitors Functions

Cached monitors allow the client to associate monitoring protection and state change synchronization in a lazy fashion. The monitoring capability is associated with the protected object only during the time it is required, allowing the monitor object to be reused. This additional flexibility comes at the cost of a small loss in performance.

`PR_CEnterMonitor` enters the lock associated with a cached monitor.

- `PR_CExitMonitor` decrements the entry count associated with a cached monitor.

- `PR_CWait` waits for a notification that a monitor's state has changed.

- `PR_CNotify` notifies a thread waiting for a change in the state of monitored data.

- `PR_CNotifyAll` notifies all the threads waiting for a change in the state of monitored data.

#### PR_CEnterMonitor

Enters the lock associated with a cached monitor.

##### Syntax

    #include <prcmon.h>

    PRMonitor* PR_CEnterMonitor(void *address);

##### Parameter

The function has the following parameter:

    address
| A reference to the data that is to be protected by the monitor. This reference must remain valid as long as there are monitoring operations being performed.

##### Returns

The function returns one of the following values:

If successful, the `function` returns a pointer to the `PRMonitor` associated with the value specified in the `address` parameter.

- If unsuccessful (the monitor cache needs to be expanded and the system is out of memory), the function returns `NULL`.

##### Description

`PR_CEnterMonitor` uses the value specified in the `address` parameter to find a monitor in the monitor cache, then enters the lock associated with the monitor. If no match is found, an available monitor is associated with the address and the monitor's entry count is incremented (so it has a value of one). If a match is found, then either the calling thread is already in the monitor (and this is a reentrant call) or another thread is holding the monitor's mutex. In the former case, the entry count is simply incremented and the function returns. In the latter case, the calling thread is likely to find the monitor locked by another thread and waits for that thread to exit before continuing.

Note | `PR_CEnterMonitor` and `PR_CExitMonitor` must be paired--that is, there must be an exit for every entry--or the object will never become available for any other thread.

#### PR_CExitMonitor

Decrement the entry count associated with a cached monitor.

##### Syntax

    #include <prcmon.h>

    PRStatus PR_CExitMonitor(void *address);

##### Parameters

The function has the following parameters:

    address
| The address of the protected object--the same address previously passed to `PR_CEnterMonitor`.

##### Returns

The function returns one of the following values:

If successful, `PR_SUCCESS`.

- If unsuccessful, `PR_FAILURE`. This may indicate that the address parameter is invalid or that the calling thread is not in the monitor.

##### Description

Using the value specified in the `address` parameter to find a monitor in the monitor cache, `PR_CExitMonitor` decrements the entry count associated with the monitor. If the decremented entry count is zero, the monitor is exited.

#### PR_CWait

Wait for a notification that a monitor's state has changed.

##### Syntax

    #include <prcmon.h>

    PRStatus PR_CWait(
       void *address,
       PRIntervalTime timeout);

##### Parameters

The function has the following parameters:

    address
| The address of the protected object--the same address previously passed to `PR_CEnterMonitor`.
    timeout
| The amount of time (in`PRIntervalTime` units) that the thread is willing to wait for an explicit notification before being rescheduled. If you specify `PR_INTERVAL_NO_TIMEOUT`, the function returns if and only if the object is notified.

##### Returns

The function returns one of the following values:

`PR_SUCCESS` indicates either that the monitored object has been notified or that the interval specified in the `timeout` parameter has been exceeded.

- `PR_FAILURE` indicates either that the monitor could not be located in the cache or that the monitor was located and the calling thread was not the thread that held the monitor's mutex.

##### Description

Using the value specified in the `address` parameter to find a monitor in the monitor cache, `PR_CWait` waits for a notification that the monitor's state has changed. While the thread is waiting, it exits the monitor (just as if it had called `PR_CExitMonitor` as many times as it had called `PR_CEnterMonitor`). When the wait has finished, the thread regains control of the monitor's lock with the same entry count as before the wait began.

The thread waiting on the monitor resumes execution when the monitor is notified (assuming the thread is the next in line to receive the notify) or when the interval specified in the `timeout` parameter has been exceeded. When the thread resumes execution, it is the caller's responsibility to test the state of the monitored data to determine the appropriate action.

#### PR_CNotify

Notify a thread waiting on a change in the state of monitored data.

##### Syntax

    #include <prcmon.h>

    PRStatus PR_CNotify(void *address);

##### Parameter

The function has the following parameters:

    address
| The address of the monitored object. The calling thread must be in the monitor defined by the value of the address.

##### Returns

The function returns one of the following values:

`PR_SUCCESS` indicates that the calling thread is the holder of the mutex for the monitor referred to by the `address` parameter.

- `PR_FAILURE` indicates that the monitor has not been entered by the calling thread.

##### Description

Using the value specified in the `address` parameter to find a monitor in the monitor cache, `PR_CNotify` notifies single a thread waiting for the monitor's state to change. If a thread is waiting on the monitor (having called `PR_CWait`), then that thread is made ready. As soon as the thread is scheduled, it attempts to reenter the monitor.

#### PR_CNotifyAll

Notifies all the threads waiting for a change in the state of monitored data.

##### Syntax

    #include <prcmon.h>

    PRStatus PR_CNotifyAll(void *address);

##### Parameter

The function has the following parameters:

    address
| The address of the monitored object. The calling thread must be in the monitor at the time `PR_CNotifyAll` is called.

##### Returns

The function returns one of the following values:

`PR_SUCCESS` indicates that the referenced monitor was located and the calling thread was in the monitor.

- `PR_FAILURE` indicates that the referenced monitor could not be located or that the calling thread was not in the monitor

##### Description

Using the value specified in the `address` parameter to find a monitor in the monitor cache, `PR_CNotifyAll` notifies all threads waiting for the monitor's state to change. All of the threads waiting on the state change are then scheduled to reenter the monitor.

Previous Contents Next

Last Updated May 18, 2001