plockstat Provider - Oracle Solaris Dynamic Tracing Guide

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) command is a DTrace consumer that uses the plockstat provider to gather data on user-level locking events.

Overview

The plockstat provider makes available probes for the following types of events:

Contention Events

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. Oracle 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.

Hold Events

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.

Error Events

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.

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 11-20. For each probe, arg0 contains a pointer to the mutex_t or pthread_mutex_t structure (these are identical types) that represents the mutex.

Table 11-20 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.

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 Oracle Solaris rwlock(3C) or POSIX pthread_rwlock_init(3C) interfaces.

The probes pertaining to readers/writer locks are in Table 11-21. For each probe, arg0 contains a pointer to the rwlock_t or pthread_rwlock_tstructure (these are identical types) that represents the adaptive lock. arg1 contains a boolean value that indicates whether the operation was as a writer.

Table 11-21 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.

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 18, 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

Skip Navigation Links
Exit Print View
	Oracle Solaris Dynamic Tracing Guide Oracle Solaris 11 Information Library