Documentation/locking/lockstat.rst

File Facts

System

Linux kernel

Corpus path

Documentation/locking/lockstat.rst

Extension

.rst

Size

11819 bytes

Lines

205

Domain

Support Tooling And Documentation

Bucket

Documentation

Inferred role

Support Tooling And Documentation: documentation

Status

atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

• Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

• No C-style include directives detected by the generator.

Detected Declarations

• No top-level syscall, struct, function, initcall, or export declaration detected by the generator.

Annotated Snippet

===============
Lock Statistics
===============

What
====

As the name suggests, it provides statistics on locks.


Why
===

Because things like lock contention can severely impact performance.

How
===

Lockdep already has hooks in the lock functions and maps lock instances to
lock classes. We build on that (see Documentation/locking/lockdep-design.rst).
The graph below shows the relation between the lock functions and the various
hooks therein::

        __acquire
            |
           lock _____
            |        \
            |    __contended
            |         |
            |       <wait>
            | _______/
            |/
            |
       __acquired
            |
            .
          <hold>
            .
            |
       __release
            |
         unlock

  lock, unlock	- the regular lock functions
  __*		- the hooks
  <> 		- states

With these hooks we provide the following statistics:

 con-bounces
	- number of lock contention that involved x-cpu data
 contentions
	- number of lock acquisitions that had to wait
 wait time
     min
	- shortest (non-0) time we ever had to wait for a lock
     max
	- longest time we ever had to wait for a lock
     total
	- total time we spend waiting on this lock
     avg
	- average time spent waiting on this lock
 acq-bounces
	- number of lock acquisitions that involved x-cpu data
 acquisitions
	- number of times we took the lock
 hold time
     min
	- shortest (non-0) time we ever held the lock
     max

Annotation

• Atlas domain: Support Tooling And Documentation / Documentation.
• Implementation status: atlas-only.

Implementation Notes

• This generated page is the file-by-file coverage layer; curated subsystem chapters should link here when they synthesize a multi-file control flow.
• Core OS pages should be promoted from atlas-only to deep-reviewed when they explain data structures, invariants, locking, lifecycle, and C implementation snippets.
• Driver-family pages are intentionally pattern-oriented unless they are part of the selected PCIe/NVMe representative device path.