mutex_profiling(9)

NAME

MUTEX_PROFILING - kernel mutex profiling support

SYNOPSIS

options MUTEX_PROFILING

DESCRIPTION

The MUTEX_PROFILING kernel option adds support for measuring

and reporting mutex use and contention statistics. These statistics

are collated
by ``acquisition point''. Acquisition points are distinct

places in the
kernel source code (identified by source file name and line

number) where
a mutex is acquired.

For each acquisition point, the following statistics are ac

cumulated:

+o The total number of non-recursive acquisitions.

+o The total time the mutex was held after being acquired

at this point.

+o The longest time the mutex was ever continuously held

after being

acquired at this point.

+o The total number of times the mutex was already held by

another

thread when this point was reached, requiring a spin or

a sleep.

+o The total number of time another thread tried to acquire

the mutex

while it was held after having been acquired at this

point.

In addition, the average hold time is derived from the total

hold time
and the number of acquisitions.

The MUTEX_PROFILING kernel option also adds the following

sysctl(8) variables to control and monitor the profiling code:

debug.mutex.prof.enable

Enable or disable the mutex profiling code. This

defaults to 0
(off).

debug.mutex.prof.reset

Reset the current mutex profiling buffers.

debug.mutex.prof.acquisitions

The total number of mutex acquisitions recorded.

debug.mutex.prof.records

The total number of acquisition points recorded.

Note that only
active acquisition points (i.e., points that have

been reached at
least once) are counted.

debug.mutex.prof.maxrecords

The maximum number of acquisition points the profil

ing code is
capable of monitoring. Since it would not be possi

ble to call
malloc(9) from within the mutex profiling code, this

is a static
limit. The number of records can be changed with

the
MPROF_BUFFERS kernel option.

debug.mutex.prof.rejected

The number of acquisition points that were ignored

after the
table filled up.

debug.mutex.prof.hashsize

The size of the hash table used to map acquisition

points to
statistics records. The hash size can be changed

with the
MPROF_HASH_SIZE kernel option.

debug.mutex.prof.collisions

The number of hash collisions in the acquisition

point hash
table.

debug.mutex.prof.stats

The actual profiling statistics in plain text. The

columns are
as follows, from left to right:

max The longest continuous hold time in

microseconds.

total The total (accumulated) hold time in

microseconds.

count The total number of acquisitions.

avg The average hold time in microseconds,

derived from

the total hold time and the number of

acquisitions.

cnt_hold The number of times the mutex was held

and another

thread attempted to lock the mutex.

cnt_lock The number of times the mutex was al

ready locked

when this point was reached.

name The name of the acquisition point, de

rived from the

source file name and line number, fol

lowed by the
name of the mutex in parentheses.

SEE ALSO

sysctl(8), mutex(9)

HISTORY

Mutex profiling support appeared in FreeBSD 5.0.

AUTHORS

The MUTEX_PROFILING code was written by Eivind Eklund <eivind@FreeBSD.org>, Dag-Erling Smorgrav <des@FreeBSD.org>

and Robert
Watson <rwatson@FreeBSD.org>. This manual page was written

by Dag-Erling
Smorgrav <des@FreeBSD.org>.

NOTES

The MUTEX_PROFILING option increases the size of struct mtx,

so a kernel
built with that option will not work with modules built

without it.

The MUTEX_PROFILING option also prevents inlining of the mu

tex code,
which results in a fairly severe performance penalty. It

should therefore only be enabled on systems where mutex profiling is ac

tually needed.
MUTEX_PROFILING will introduce a substantial performance

overhead that is
easily monitorable using other profiling tools, so combining

profiling
tools with MUTEX_PROFILING is not recommended.

Measurements are made and stored in nanoseconds using nan

otime(9), but
are presented in microseconds. This should still be suffi

cient for the
locks one would be most interested in profiling (those that

are held long
and/or acquired often).

MUTEX_PROFILING should generally not be used in combination

with other
debugging options, as the results may be strongly affected

by interactions between the features. In particular, MUTEX_PROFILING

will report
higher than normal uma(9) lock contention when run with IN

VARIANTS due to
extra locking that occurs when INVARIANTS is present; like

wise, using it
in combination with WITNESS will lead to much higher lock

hold times and
contention in profiling output.

BSD January 7, 2005

BSD