Lockstat Provider

The lockstat provider provides probes that can be used to study lock usage and contention.

lockstat Probes

For all lockstat probes, the module name is vmlinux and the function name is an empty string.

Locks are classified as:

  • Spin: This is spin wait if there's contention.

  • Adaptive: This is either spin wait, or else block, if there's contention.

  • Readers-writer.

The following probes fire when a lock is acquired or released:

  • spin-acquire.

  • spin-release.

  • adaptive-acquire.

  • adaptive-release.

  • rw-acquire.

  • rw-release.

The following probe fires before a lock is acquired if there was contention for the lock and if the probe is enabled:

  • spin-spin.

  • adaptive-block, adaptive-spin. One probe fires or else the other, depending on which wait is used.

  • rw-spin.

Finally, an adaptive-acquire-error probe indicates an error acquiring an adaptive lock.

lockstat Probe Arguments

The following table lists the argument types for the lockstat probes. The argN are implementation specific. Use args[] to access the probe arguments.

Table 9-6 lockstat Probe Arguments

Probe args[0] args[1] args[2]

adaptive-acquire

struct mutex *

—

—

adaptive-acquire-error

struct mutex *

int

—

adaptive-block

struct mutex *

uint64_t

—

adaptive-release

struct mutex *

—

—

adaptive-spin

struct mutex *

uint64_t

—

rw-acquire

struct rwlock *

int

—

rw-release

struct rwlock *

int

—

rw-spin

struct rwlock *

uint64_t

int

spin-acquire

spinlock_t *

—

—

spin-release

spinlock_t *

—

—

spin-spin

spinlock_t *

uint64_t

—

Note:

args[0] has a pointer to the lock in question. The probes that fire in case of contention report a uint64_t args[1], which is the wait time in nanoseconds. The rw probes also report an int that's either RW_READER or RW_WRITER. Finally, adaptive-acquire-error reports an int with a non zero error.

lockstat Examples

The following examples illustrate the use of the probes that are published by the lockstat provider.

adaptive-acquire and spin-acquire

Type the following D source code and save it in a file named whatlock.d: 

lockstat:::spin-acquire,
lockstat:::adaptive-acquire
/pid == $target/
{
  @locks[probename] = count();
}

Run the program on the date command using sudo dtrace -qs whatlock.d -c date. The D output looks similar to: 

 adaptive-acquire                                                  6
 spin-acquire                                                    134

It might be surprising that so many locks are acquired with the date command. The large number of locks is a natural artifact of the fine-grained locking required of a scalable system such as the Oracle Liux kernel.

lockstat Stability

The lockstat provider uses DTrace's stability mechanism to describe its stabilities. These values are listed in the following table.

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