diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 19:33:14 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 19:33:14 +0000 |
commit | 36d22d82aa202bb199967e9512281e9a53db42c9 (patch) | |
tree | 105e8c98ddea1c1e4784a60a5a6410fa416be2de /docs/nspr/reference/monitors.rst | |
parent | Initial commit. (diff) | |
download | firefox-esr-36d22d82aa202bb199967e9512281e9a53db42c9.tar.xz firefox-esr-36d22d82aa202bb199967e9512281e9a53db42c9.zip |
Adding upstream version 115.7.0esr.upstream/115.7.0esr
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/nspr/reference/monitors.rst')
-rw-r--r-- | docs/nspr/reference/monitors.rst | 63 |
1 files changed, 63 insertions, 0 deletions
diff --git a/docs/nspr/reference/monitors.rst b/docs/nspr/reference/monitors.rst new file mode 100644 index 0000000000..63d43d595b --- /dev/null +++ b/docs/nspr/reference/monitors.rst @@ -0,0 +1,63 @@ +In addition to the mutex type :ref:`PRLock`, NSPR provides a special type, +:ref:`PRMonitor`, for use in Java programming. This chapter describes the +NSPR API for creation and manipulation of a mutex of type :ref:`PRMonitor`. + +- `Monitor Type <#Monitor_Type>`__ +- `Monitor Functions <#Monitor_Functions>`__ + +With a mutex of type :ref:`PRLock`, a single thread may enter the monitor +only once before it exits, and the mutex can have multiple associated +condition variables. + +With a mutex of type :ref:`PRMonitor`, a single thread may re-enter a +monitor as many times as it sees fit. The first time the thread enters a +monitor, it acquires the monitor's lock and the thread's entry count is +incremented to 1. Each subsequent time the thread successfully enters +the same monitor, the thread's entry count is incremented again, and +each time the thread exits the monitor, the thread's entry count is +decremented. When the entry count for a thread reaches zero, the thread +releases the monitor's lock, and other threads that were blocked while +trying to enter the monitor will be rescheduled. + +A call to :ref:`PR_Wait` temporarily returns the entry count to zero. When +the calling thread resumes, it has the same entry count it had before +the wait operation. + +Unlike a mutex of type :ref:`PRLock`, a mutex of type :ref:`PRMonitor` has a +single, implicitly associated condition variable that may be used to +facilitate synchronization of threads with the change in state of +monitored data. + +For an introduction to NSPR thread synchronization, including locks and +condition variables, see `Introduction to +NSPR <Introduction_to_NSPR>`__. + +.. _Monitor_Type: + +Monitor Type +------------ + +With the exception of :ref:`PR_NewMonitor`, which creates a new monitor +object, all monitor functions require a pointer to an opaque object of +type :ref:`PRMonitor`. + +.. _Monitor_Functions: + +Monitor Functions +----------------- + +All monitor functions are thread-safe. However, this safety does not +extend to protecting the monitor object from deletion. + + - :ref:`PR_NewMonitor` creates a new monitor. + - :ref:`PR_DestroyMonitor` destroys a monitor object. + - :ref:`PR_EnterMonitor` enters the lock associated with a specified + monitor. + - :ref:`PR_ExitMonitor` decrements the entry count associated with a + specified monitor. + - :ref:`PR_Wait` waits for a notify on a specified monitor's condition + variable. + - :ref:`PR_Notify` notifies a thread waiting on a specified monitor's + condition variable. + - :ref:`PR_NotifyAll` notifies all threads waiting on a specified + monitor's condition variable. |