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 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 (inPRIntervalTime 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