docs/nspr/reference/monitors.rst

   1 In addition to the mutex type :ref:`PRLock`, NSPR provides a special type,
   2 :ref:`PRMonitor`, for use in Java programming. This chapter describes the
   3 NSPR API for creation and manipulation of a mutex of type :ref:`PRMonitor`.
   4
   5 -  `Monitor Type <#Monitor_Type>`__
   6 -  `Monitor Functions <#Monitor_Functions>`__
   7
   8 With a mutex of type :ref:`PRLock`, a single thread may enter the monitor
   9 only once before it exits, and the mutex can have multiple associated
  10 condition variables.
  11
  12 With a mutex of type :ref:`PRMonitor`, a single thread may re-enter a
  13 monitor as many times as it sees fit. The first time the thread enters a
  14 monitor, it acquires the monitor's lock and the thread's entry count is
  15 incremented to 1. Each subsequent time the thread successfully enters
  16 the same monitor, the thread's entry count is incremented again, and
  17 each time the thread exits the monitor, the thread's entry count is
  18 decremented. When the entry count for a thread reaches zero, the thread
  19 releases the monitor's lock, and other threads that were blocked while
  20 trying to enter the monitor will be rescheduled.
  21
  22 A call to :ref:`PR_Wait` temporarily returns the entry count to zero. When
  23 the calling thread resumes, it has the same entry count it had before
  24 the wait operation.
  25
  26 Unlike a mutex of type :ref:`PRLock`, a mutex of type :ref:`PRMonitor` has a
  27 single, implicitly associated condition variable that may be used to
  28 facilitate synchronization of threads with the change in state of
  29 monitored data.
  30
  31 For an introduction to NSPR thread synchronization, including locks and
  32 condition variables, see `Introduction to
  33 NSPR <Introduction_to_NSPR>`__.
  34
  35 .. _Monitor_Type:
  36
  37 Monitor Type
  38 ------------
  39
  40 With the exception of :ref:`PR_NewMonitor`, which creates a new monitor
  41 object, all monitor functions require a pointer to an opaque object of
  42 type :ref:`PRMonitor`.
  43
  44 .. _Monitor_Functions:
  45
  46 Monitor Functions
  47 -----------------
  48
  49 All monitor functions are thread-safe. However, this safety does not
  50 extend to protecting the monitor object from deletion.
  51
  52  - :ref:`PR_NewMonitor` creates a new monitor.
  53  - :ref:`PR_DestroyMonitor` destroys a monitor object.
  54  - :ref:`PR_EnterMonitor` enters the lock associated with a specified
  55    monitor.
  56  - :ref:`PR_ExitMonitor` decrements the entry count associated with a
  57    specified monitor.
  58  - :ref:`PR_Wait` waits for a notify on a specified monitor's condition
  59    variable.
  60  - :ref:`PR_Notify` notifies a thread waiting on a specified monitor's
  61    condition variable.
  62  - :ref:`PR_NotifyAll` notifies all threads waiting on a specified
  63    monitor's condition variable.