DTRACE_LOCKSTAT(4)

💅 DTRACE_LOCKSTAT(4) — like, the lockstat DTrace provider bestie 💅

okay so this is the manual page for dtrace_lockstat(4), from the Kernel Interfaces Manual, and we are gonna get you so caught up. grab a boba, bestie, we're talking kernel locks 🫶

---

✨ NAME ✨

dtrace_lockstat — a DTrace provider for tracing CPU scheduling events

ngl the NAME line says "CPU scheduling events" and I'm just reporting what it says, fr fr, no cap. 😭

---

🌸 SYNOPSIS 🌸

lockstat:::adaptive-acquire(struct mtx *);

lockstat:::adaptive-release(struct mtx *);

lockstat:::adaptive-spin(struct mtx *, uint64_t);

lockstat:::adaptive-block(struct mtx *, uint64_t);

lockstat:::spin-acquire(struct mtx *);

lockstat:::spin-release(struct mtx *);

lockstat:::spin-spin(struct mtx *, uint64_t);

lockstat:::rw-acquire(struct rwlock *, int);

lockstat:::rw-release(struct rwlock *, int);

lockstat:::rw-block(struct rwlock *, uint64_t, int, int, int);

lockstat:::rw-spin(struct rwlock *, uint64_t);

lockstat:::rw-upgrade(struct rwlock *);

lockstat:::rw-downgrade(struct rwlock *);

lockstat:::sx-acquire(struct sx *, int);

lockstat:::sx-release(struct sx *, int);

lockstat:::sx-block(struct sx *, uint64_t, int, int, int);

lockstat:::sx-spin(struct sx *, uint64_t);

lockstat:::sx-upgrade(struct sx *);

lockstat:::sx-downgrade(struct sx *);

lockstat:::lockmgr-acquire(struct lock *, int);

lockstat:::lockmgr-release(struct lock *, int);

lockstat:::lockmgr-disown(struct lock *, int);

lockstat:::lockmgr-block(struct lock *, uint64_t, int, int, int);

lockstat:::lockmgr-upgrade(struct lock *);

lockstat:::lockmgr-downgrade(struct lock *);

lockstat:::thread-spin(struct mtx *, uint64);

look at all those probes. twenty-six of them. they ate. 💅✨

---

🦋 DESCRIPTION 🦋

The DTrace lockstat provider is the whole vibe for tracing events related to locking on FreeBSD. 🌈

The dtrace_lockstat provider contains DTrace probes for inspecting kernel lock state transitions. Probes exist for the lockmgr(9), mutex(9), rwlock(9), and sx(9) lock types. The lockstat(1) utility can be used to collect and display data collected from the dtrace_lockstat provider. Each type of lock has acquire() and release() probes which expose the lock structure being operated upon, as well as probes which fire when a thread contends with other threads for ownership of a lock. 🔥

💖 adaptive mutex probes 💖

The lockstat:::adaptive-acquire() and lockstat:::adaptive-release() probes fire when an MTX_DEF mutex(9) is acquired and released, respectively. The only argument is a pointer to the lock structure which describes the lock being acquired or released.

The lockstat:::adaptive-spin() probe fires when a thread spins while waiting for a MTX_DEF mutex(9) to be released by another thread. The first argument is a pointer to the lock structure that describes the lock and the second argument is the amount of time, in nanoseconds, that the mutex spent spinning. The lockstat:::adaptive-block() probe fires when a thread takes itself off the CPU while trying to acquire an MTX_DEF mutex(9) that is owned by another thread. The first argument is a pointer to the lock structure that describes the lock and the second argument is the length of time, in nanoseconds, that the waiting thread was blocked. The lockstat:::adaptive-block() and lockstat:::adaptive-spin() probes fire only after the lock has been successfully acquired, and in particular, after the lockstat:::adaptive-acquire() probe fires. 👑

bestie this ordering detail matters!! the -block() and -spin() probes don't fire first, they fire after the acquire probe. periodt.

🎀 spin mutex probes 🎀

The lockstat:::spin-acquire() and lockstat:::spin-release() probes fire when a MTX_SPIN mutex(9) is acquired or released, respectively. The only argument is a pointer to the lock structure which describes the lock being acquired or released.

The lockstat:::spin-spin() probe fires when a thread spins while waiting for a MTX_SPIN mutex(9) to be released by another thread. The first argument is a pointer to the lock structure that describes the lock and the second argument is the length of the time spent spinning, in nanoseconds. The lockstat:::spin-spin() probe fires only after the lock has been successfully acquired, and in particular, after the lockstat:::spin-acquire() probe fires. ✨

🌸 rw / sx / lockmgr acquire & release 🌸

The lockstat:::rw-acquire() and lockstat:::rw-release() probes fire when a rwlock(9) is acquired or released, respectively. The first argument is a pointer to the structure which describes the lock being acquired. The second argument is 0 if the lock is being acquired or released as a writer, and 1 if it is being acquired or released as a reader. The lockstat:::sx-acquire() and lockstat:::sx-release(), and lockstat:::lockmgr-acquire() and lockstat:::lockmgr-release() probes fire upon the corresponding events for sx(9) and lockmgr(9) locks, respectively. The lockstat:::lockmgr-disown() probe fires when a lockmgr(9) exclusive lock is disowned. In this state, the lock remains exclusively held, but may be released by a different thread. The lockstat:::lockmgr-release() probe does not fire when releasing a disowned lock. The first argument is a pointer to the structure which describes the lock being disowned. The second argument is 0, for compatibility with lockstat:::lockmgr-release(). 💜

the way that a disowned lock stays exclusively held but can be released by a different thread?? that's giving main character energy and also a very specific fact you should not forget. and yes, the -release() probe is not firing for it. 🙈

🧚 block & spin probes (the group chat) 🧚

The lockstat:::rw-block(), lockstat:::sx-block(), and lockstat:::lockmgr-block() probes fire when a thread removes itself from the CPU while waiting to acquire a lock of the corresponding type. The lockstat:::rw-spin() and lockstat:::sx-spin() probes fire when a thread spins while waiting to acquire a lock of the corresponding type. All probes take the same set of arguments:

• arg1 — a pointer to the lock structure that describes the lock.
• arg2 — the length of time, in nanoseconds, that the waiting thread was off the CPU or spinning for the lock.
• arg3 — 0 if the thread is attempting to acquire the lock as a writer, and 1 if the thread is attempting to acquire the lock as a reader.
• arg4 — 0 if the thread is waiting for a reader to release the lock, and 1 if the thread is waiting for a writer to release the lock.
• arg5 — the number of readers that held the lock when the thread first attempted to acquire the lock. This argument will be 0 if the fourth argument is 1.

like, five args, all consistent, we love a uniform interface. 🫶

⭐ upgrade & downgrade ⭐

The lockstat:::lockmgr-upgrade(), lockstat:::rw-upgrade(), and lockstat:::sx-upgrade() probes fire when a thread successfully upgrades a held lockmgr(9), rwlock(9), or sx(9) shared/reader lock to an exclusive/writer lock. The only argument is a pointer to the structure which describes the lock being acquired. The lockstat:::lockmgr-downgrade(), lockstat:::rw-downgrade(), and lockstat:::sx-downgrade() probes fire when a thread downgrades a held lockmgr(9), rwlock(9), or sx(9) exclusive/writer lock to a shared/reader lock.

glow up = upgrade, humble era = downgrade, iykyk. 💅

💀 thread-spin 💀

The lockstat:::thread-spin() probe fires when a thread spins on a thread lock, which is a specialized MTX_SPIN mutex(9). The first argument is a pointer to the structure that describes the lock and the second argument is the length of time, in nanoseconds, that the thread was spinning.

---

👀 SEE ALSO 👀

dtrace(1), lockstat(1), locking(9), mutex(9), rwlock(9), SDT(9), sx(9)

go read those too, bestie, they're literally right there. 📚

---

🌈 HISTORY 🌈

The dtrace_lockstat provider first appeared in Solaris. The FreeBSD implementation of the dtrace_lockstat provider first appeared in FreeBSD 9. 🦋

---

💖 AUTHORS 💖

This manual page was written by George V. Neville-Neil <gnn@FreeBSD.org> and Mark Johnston <markj@FreeBSD.org>.

not me being obsessed with people who write manpages, absolute icons, thank you for your service 🫶✨

---

🍓 BUGS 🍓

Probes for rmlock(9) locks have not yet been added. 😭

so like, if you were looking for rmlock(9) probes... they're not here yet. that's the whole bug note, no cap.

---

and that's the page, bestie!! this one is from Debian, dated August 20, 2019, and it's DTRACE_LOCKSTAT(4) — go trace some locks and slay 💅💖✨