pr_centermonitor.rst (1699B)
1 PR_CEnterMonitor 2 ================ 3 4 Enters the lock associated with a cached monitor. 5 6 7 Syntax 8 ------ 9 10 .. code:: 11 12 #include <prcmon.h> 13 14 PRMonitor* PR_CEnterMonitor(void *address); 15 16 17 Parameter 18 ~~~~~~~~~ 19 20 The function has the following parameter: 21 22 ``address`` 23 A reference to the data that is to be protected by the monitor. This 24 reference must remain valid as long as there are monitoring 25 operations being performed. 26 27 28 Returns 29 ~~~~~~~ 30 31 The function returns one of the following values: 32 33 - If successful, the function returns a pointer to the :ref:`PRMonitor` 34 associated with the value specified in the ``address`` parameter. 35 - If unsuccessful (the monitor cache needs to be expanded and the 36 system is out of memory), the function returns ``NULL``. 37 38 39 Description 40 ----------- 41 42 :ref:`PR_CEnterMonitor` uses the value specified in the ``address`` 43 parameter to find a monitor in the monitor cache, then enters the lock 44 associated with the monitor. If no match is found, an available monitor 45 is associated with the address and the monitor's entry count is 46 incremented (so it has a value of one). If a match is found, then either 47 the calling thread is already in the monitor (and this is a reentrant 48 call) or another thread is holding the monitor's mutex. In the former 49 case, the entry count is simply incremented and the function returns. In 50 the latter case, the calling thread is likely to find the monitor locked 51 by another thread and waits for that thread to exit before continuing. 52 53 .. note:: 54 55 :ref:`PR_CEnterMonitor` and :ref:`PR_CExitMonitor` must be 56 paired--that is, there must be an exit for every entry--or the object 57 will never become available for any other thread.