Ubuntu Manpage: dtrace_lockstat — a DTrace provider for tracing CPU scheduling events

Provided by: freebsd-manpages_12.0-1_all

NAME

       dtrace_lockstat — a DTrace provider for tracing CPU scheduling events

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:::thread-spin(struct mtx *, uint64);

DESCRIPTION

The DTrace lockstat provider allows the tracing of events related to locking on FreeBSD.

The dtrace_lockstat provider contains DTrace probes for inspecting kernel lock state transitions. Probes
exist for the 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.

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.

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.

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:::rw-block() probe fires when a thread removes itself from the CPU while waiting to acquire
a rwlock(9). The lockstat:::rw-spin() probe fires when a thread spins while waiting to acquire a
rwlock(9). Both probes take the same set of arguments. The first argument is a pointer to the lock
structure that describes the lock. The second argument is the length of time, in nanoseconds, that the
waiting thread was off the CPU or spinning for the lock. The third argument is 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. The fourth argument is 0 if the thread is waiting for a writer to release the lock, and 1 if the
thread is waiting for a reader to release the lock. The fifth argument is 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 0.

The lockstat:::rw-upgrade() probe fires when a thread successfully upgrades a held rwlock(9) read lock to
a write lock. The lockstat:::rw-downgrade() probe fires when a thread downgrades a held rwlock(9) write
lock to a read lock. The only argument is a pointer to the structure which describes the lock being
acquired.

The lockstat:::sx-acquire() and lockstat:::sx-release() probes fire when a sx(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 shared lock is being acquired or released, and 1 if the exclusive lock is
being acquired or released.

The lockstat:::sx-block() probe fires when a thread takes itself off the CPU while waiting to acquire a
sx(9). The lockstat:::sx-spin() probe fires when a thread spins while waiting to acquire a sx(9). Both
probes take the same set of arguments. The first argument is a pointer to the lock structure that
describes the lock. The second argument is the length of time, in nanoseconds, that the waiting thread
was off the CPU or spinning for the lock. The third argument is 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. The fourth
argument is 0 if the thread is waiting for a writer to release the lock, and 1 if the thread is waiting
for a reader to release the lock. The fifth argument is 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 0.

The lockstat:::sx-upgrade() probe fires when a thread successfully upgrades a held sx(9) shared lock to
an exclusive lock. The only argument is a pointer to the structure which describes the lock being
acquired. The lockstat:::sx-downgrade() probe fires when a thread downgrades a held sx(9) exclusive lock
to a shared lock.

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.

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

BUGS