{anchor:top}
h1. {anchor:CHP-PLOCKSTAT} {{plockstat}} Provider
The {{plockstat}} provider makes available probes that can be used to observe the behavior of user-level synchronization primitives including lock contention and hold times. The [{{plockstat}}(1M)|http://docs.sun.com/doc/819-2240/plockstat-1m?a=view] command is a DTrace consumer that uses the {{plockstat}} provider to gather data on user-level locking events.
[Top|#top]
h2. {anchor:CHP-PLOCKSTAT-1} Overview
The {{plockstat}} provider makes available probes for the following types of events:
{section}
{column:width=15%}
_Contention Events_
{column}
{column:width=85%}
These probes correspond to contention on a user-level synchronization primitive, and fire when a thread is forced to wait for a resource to become available. Solaris is generally optimized for the non-contention case, so prolonged contention is not expected; these probes should be used to understand those cases where contention does arise. Because contention is designed to be (relatively) rare, enabling contention-event probes generally doesn't have a serious probe effect; they can be enabled without concern for substantially affecting performance.
{column}
{section}
{section}
{column:width=15%}
_Hold Events_
{column}
{column:width=85%}
These probes correspond to acquiring, releasing or otherwise manipulating a user-level synchronization primitive. As such, these probes can be used to answer arbitrary questions about the way user-level synchronization primitives are manipulated. Because applications typically acquire and release synchronization primitives very often, enabling hold-event probes can have a greater probe effect than enabling contention-event probes. While the probe effect induced by enabling them can be substantial, it is not pathological; they may still be enabled with confidence on production applications.
{column}
{section}
{section}
{column:width=15%}
_Error Events_
{column}
{column:width=85%}
These probes correspond to any kind of anomalous behavior encountered when acquiring or releasing a user-level synchronization primitive. These events can be used to detect errors encountered while a thread is blocking on a user-level synchronization primitive. Error events should be extremely uncommon so enabling them shouldn't induce a serious probe effect.
{column}
{section}
[Top|#top]
h2. {anchor:CHP-PLOCKSTAT-2} Mutex Probes
_Mutexes_ enforce mutual exclusion to critical sections. When a thread attempts to acquire a mutex held by another thread using {{mutex_lock(3C)}} or {{pthread_mutex_lock(3C)}}, it will determine if the owning thread is running on a different CPU. If it is, the acquiring thread will _spin_ for a short while waiting for the mutex to become available. If the owner is not executing on another CPU, the acquiring thread will _block_.\\
\\The four {{plockstat}} probes pertaining to mutexes are listed in [Table 31–1|#TBL-UMUTEX]. For each probe, {{arg0}} contains a pointer to the {{mutex_t}} or {{pthread_mutex_t}} structure (these are identical types) that represents the mutex.
h6. {anchor:TBL-UMUTEX} Mutex Probes
|{{mutex-acquire}}|Hold event probe that fires immediately after a mutex is acquired. {{arg1}} contains a boolean value that indicates whether the acquisition was recursive on a recursive mutex. {{arg2}} indicates the number of iterations that the acquiring thread spent spinning on this mutex. {{arg2}} will be non-zero only if the {{mutex-spin}} probe fired on this mutex acquisition.|
|{{mutex-block}}|Contention event probe that fires before a thread blocks on a held mutex. Both {{mutex-block}} and {{mutex-spin}} might fire for a single lock acquisition.|
|{{mutex-spin}}|Contention event probe that fires before a thread begins spinning on a held mutex. Both {{mutex-block}} and {{mutex-spin}} might fire for a single lock acquisition.|
|{{mutex-release}}|Hold event probe that fires immediately after an mutex is released. {{arg1}} contains a boolean value that indicates whether the event corresponds to a recursive release on a recursive mutex.|
|{{mutex-error}}|Error event probe that fires when an error is encountered on a mutex operation. {{arg1}} is the {{errno}} value for the error encountered.|
[Top|#top]
h2. {anchor:CHP-PLOCKSTAT-3} Reader/Writer Lock Probes
_Reader/write locks_ permit multiple readers _or_ a single writer, but not both, to be in a critical section at one time. These locks are typically used for structures that are searched more frequently than they are modified, or when threads spend substantial time in a critical section. Users interact with reader/writer locks using the Solaris {{rwlock(3C)}} or POSIX {{pthread_rwlock_init(3C)}} interfaces.\\
\\The probes pertaining to readers/writer locks are in [Table 31–2|#TBL-URWLOCK]. For each probe, {{arg0}} contains a pointer to the {{rwlock_t}} or {{pthread_rwlock_t}}structure (these are identical types) that represents the adaptive lock. {{arg1}} contains a boolean value that indicates whether the operation was as a writer.
h6. {anchor:TBL-URWLOCK} Readers/Writer Lock Probes
|{{rw-acquire}}|Hold event probe that fires immediately after a readers/writer lock is acquired.|
|{{rw-block}}|Contention event probe that fires before a thread blocks while attempting to acquire a lock. If enabled, the {{rw-acquire}} probe or the {{rw-error}} probe will fire after {{rw-block}}.|
|{{rw-release}}|Hold event probe that fires immediately after a reader/writer lock is released|
|{{rw-error}}|Error event probe that fires when an error is encountered during a reader/writer lock operation. {{arg1}} is the {{errno}} value of the error encountered.|
[Top|#top]
h2. {anchor:CHP-PLOCKSTAT-STABILITY} Stability
The {{plockstat}} provider uses DTrace's stability mechanism to describe its stabilities, as shown in the following table. For more information about the stability mechanism, see [Chapter 39, Stability|Stability].
||Element||Name stability||Data stability||Dependency class||
|Provider|Evolving|Evolving|ISA|
|Module|Private|Private|Unknown|
|Function|Private|Private|Unknown|
|Name|Evolving|Evolving|ISA|
|Arguments|Evolving|Evolving|ISA|
{excerpt:hidden=true}Converted by tech dogg's sgml2wiki on Tue 20 Nov 2007 at 9:25:41 PM{excerpt}
h1. {anchor:CHP-PLOCKSTAT} {{plockstat}} Provider
The {{plockstat}} provider makes available probes that can be used to observe the behavior of user-level synchronization primitives including lock contention and hold times. The [{{plockstat}}(1M)|http://docs.sun.com/doc/819-2240/plockstat-1m?a=view] command is a DTrace consumer that uses the {{plockstat}} provider to gather data on user-level locking events.
[Top|#top]
h2. {anchor:CHP-PLOCKSTAT-1} Overview
The {{plockstat}} provider makes available probes for the following types of events:
{section}
{column:width=15%}
_Contention Events_
{column}
{column:width=85%}
These probes correspond to contention on a user-level synchronization primitive, and fire when a thread is forced to wait for a resource to become available. Solaris is generally optimized for the non-contention case, so prolonged contention is not expected; these probes should be used to understand those cases where contention does arise. Because contention is designed to be (relatively) rare, enabling contention-event probes generally doesn't have a serious probe effect; they can be enabled without concern for substantially affecting performance.
{column}
{section}
{section}
{column:width=15%}
_Hold Events_
{column}
{column:width=85%}
These probes correspond to acquiring, releasing or otherwise manipulating a user-level synchronization primitive. As such, these probes can be used to answer arbitrary questions about the way user-level synchronization primitives are manipulated. Because applications typically acquire and release synchronization primitives very often, enabling hold-event probes can have a greater probe effect than enabling contention-event probes. While the probe effect induced by enabling them can be substantial, it is not pathological; they may still be enabled with confidence on production applications.
{column}
{section}
{section}
{column:width=15%}
_Error Events_
{column}
{column:width=85%}
These probes correspond to any kind of anomalous behavior encountered when acquiring or releasing a user-level synchronization primitive. These events can be used to detect errors encountered while a thread is blocking on a user-level synchronization primitive. Error events should be extremely uncommon so enabling them shouldn't induce a serious probe effect.
{column}
{section}
[Top|#top]
h2. {anchor:CHP-PLOCKSTAT-2} Mutex Probes
_Mutexes_ enforce mutual exclusion to critical sections. When a thread attempts to acquire a mutex held by another thread using {{mutex_lock(3C)}} or {{pthread_mutex_lock(3C)}}, it will determine if the owning thread is running on a different CPU. If it is, the acquiring thread will _spin_ for a short while waiting for the mutex to become available. If the owner is not executing on another CPU, the acquiring thread will _block_.\\
\\The four {{plockstat}} probes pertaining to mutexes are listed in [Table 31–1|#TBL-UMUTEX]. For each probe, {{arg0}} contains a pointer to the {{mutex_t}} or {{pthread_mutex_t}} structure (these are identical types) that represents the mutex.
h6. {anchor:TBL-UMUTEX} Mutex Probes
|{{mutex-acquire}}|Hold event probe that fires immediately after a mutex is acquired. {{arg1}} contains a boolean value that indicates whether the acquisition was recursive on a recursive mutex. {{arg2}} indicates the number of iterations that the acquiring thread spent spinning on this mutex. {{arg2}} will be non-zero only if the {{mutex-spin}} probe fired on this mutex acquisition.|
|{{mutex-block}}|Contention event probe that fires before a thread blocks on a held mutex. Both {{mutex-block}} and {{mutex-spin}} might fire for a single lock acquisition.|
|{{mutex-spin}}|Contention event probe that fires before a thread begins spinning on a held mutex. Both {{mutex-block}} and {{mutex-spin}} might fire for a single lock acquisition.|
|{{mutex-release}}|Hold event probe that fires immediately after an mutex is released. {{arg1}} contains a boolean value that indicates whether the event corresponds to a recursive release on a recursive mutex.|
|{{mutex-error}}|Error event probe that fires when an error is encountered on a mutex operation. {{arg1}} is the {{errno}} value for the error encountered.|
[Top|#top]
h2. {anchor:CHP-PLOCKSTAT-3} Reader/Writer Lock Probes
_Reader/write locks_ permit multiple readers _or_ a single writer, but not both, to be in a critical section at one time. These locks are typically used for structures that are searched more frequently than they are modified, or when threads spend substantial time in a critical section. Users interact with reader/writer locks using the Solaris {{rwlock(3C)}} or POSIX {{pthread_rwlock_init(3C)}} interfaces.\\
\\The probes pertaining to readers/writer locks are in [Table 31–2|#TBL-URWLOCK]. For each probe, {{arg0}} contains a pointer to the {{rwlock_t}} or {{pthread_rwlock_t}}structure (these are identical types) that represents the adaptive lock. {{arg1}} contains a boolean value that indicates whether the operation was as a writer.
h6. {anchor:TBL-URWLOCK} Readers/Writer Lock Probes
|{{rw-acquire}}|Hold event probe that fires immediately after a readers/writer lock is acquired.|
|{{rw-block}}|Contention event probe that fires before a thread blocks while attempting to acquire a lock. If enabled, the {{rw-acquire}} probe or the {{rw-error}} probe will fire after {{rw-block}}.|
|{{rw-release}}|Hold event probe that fires immediately after a reader/writer lock is released|
|{{rw-error}}|Error event probe that fires when an error is encountered during a reader/writer lock operation. {{arg1}} is the {{errno}} value of the error encountered.|
[Top|#top]
h2. {anchor:CHP-PLOCKSTAT-STABILITY} Stability
The {{plockstat}} provider uses DTrace's stability mechanism to describe its stabilities, as shown in the following table. For more information about the stability mechanism, see [Chapter 39, Stability|Stability].
||Element||Name stability||Data stability||Dependency class||
|Provider|Evolving|Evolving|ISA|
|Module|Private|Private|Unknown|
|Function|Private|Private|Unknown|
|Name|Evolving|Evolving|ISA|
|Arguments|Evolving|Evolving|ISA|
{excerpt:hidden=true}Converted by tech dogg's sgml2wiki on Tue 20 Nov 2007 at 9:25:41 PM{excerpt}