Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MUTEX_PROFILING(9)	 BSD Kernel Developer's	Manual	    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 report-
     ing 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 accumulated:

     +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 ac-
	 quired	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) vari-
     ables 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 profiling code is
	     capable of	monitoring.  Since it would not	be possible 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 ta-
	     ble filled	up.

     debug.mutex.prof.hashsize
	     The size of the hash table	used to	map acquisition	points to sta-
	     tistics 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 ta-
	     ble.

     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 already locked	when
		       this point was reached.

	     name      The name	of the acquisition point, derived from the
		       source file name	and line number, followed 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 mutex code,
     which results in a	fairly severe performance penalty.  It should there-
     fore only be enabled on systems where mutex profiling is actually 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 nanotime(9),	but
     are presented in microseconds.  This should still be sufficient 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 interac-
     tions between the features.  In particular, MUTEX_PROFILING will report
     higher than normal	uma(9) lock contention when run	with INVARIANTS	due to
     extra locking that	occurs when INVARIANTS is present; likewise, using it
     in	combination with WITNESS with will lead	to much	higher lock hold times
     and contention in profiling output.

BSD				January	7, 2005				   BSD

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | HISTORY | AUTHORS | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MUTEX_PROFILING&sektion=9&manpath=FreeBSD+5.5-RELEASE>

home | help