
# Lockstat Provider 

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

**Parent topic:**[DTrace Provider Reference](../reference/dtrace_providers.md)

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

Probe

`args[0]`

`args[1]`

`args[2]`

<tbody> 
`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`

—

<tbody>

**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 Linux 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              |
