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

FreeBSD Manual Pages

  
 
  

home | help
cprof(3)		   Erlang Module Definition		      cprof(3)

NAME
       cprof  -	A simple Call Count Profiling Tool using breakpoints for mini-
       mal runtime performance impact.

DESCRIPTION
       The cprof module	is used	to profile a program  to  find	out  how  many
       times different functions are called. Breakpoints similar to local call
       trace, but containing a counter,	are used to minimise  runtime  perfor-
       mance impact.

       Since  breakpoints are used there is no need for	special	compilation of
       any module to be	profiled. For now these	breakpoints can	only be	set on
       BEAM code so s cannot be	call count traced.

       The size	of the call counters is	the host machine word size. One	bit is
       used when pausing the counter, so  the  maximum	counter	 value	for  a
       32-bit host is 2147483647.

       The profiling result is delivered as a term containing a	sorted list of
       entries,	one per	module.	Each module entry contains a  sorted  list  of
       functions. The sorting order in both cases is of	decreasing call	count.

       Call count tracing is very lightweight compared to other	forms of trac-
       ing since no trace message has to be generated. Some measurements indi-
       cates performance degradation in	the vicinity of	10 percent.

EXPORTS
       analyse() -> {AllCallCount, ModAnalysisList}
       analyse(Limit) -> {AllCallCount,	ModAnalysisList}
       analyse(Mod) -> ModAnalysis
       analyse(Mod, Limit) -> ModAnalysis

	      Types:

		 Limit = integer()
		 Mod = atom()
		 AllCallCount =	integer()
		 ModAnalysisList = [ModAnalysis]
		 ModAnalysis = {Mod, ModCallCount, FuncAnalysisList}
		 ModCallCount =	integer()
		 FuncAnalysisList = [{{Mod, Func, Arity}, FuncCallCount}]
		 Func =	atom()
		 Arity = integer()
		 FuncCallCount = integer()

	      Collects	and  analyses  the call	counters presently in the node
	      for either module	Mod, or	for all	modules	(except	cprof itself),
	      and returns:

		FuncAnalysisList:
		  A  list of tuples, one for each function in a	module,	in de-
		  creasing FuncCallCount order.

		ModCallCount:
		  The sum of FuncCallCount values for all functions in	module
		  Mod.

		AllCallCount:
		  The  sum of ModCallCount values for all modules concerned in
		  ModAnalysisList.

		ModAnalysisList:
		  A list of tuples, one	for each module	except cprof,  in  de-
		  creasing ModCallCount	order.

	      If call counters are still running while analyse/0..2 is execut-
	      ing, you might get an inconsistent result. This happens  if  the
	      process  executing analyse/0..2 gets scheduled out so some other
	      process can increment the	 counters  that	 are  being  analysed,
	      Calling pause() before analysing takes care of the problem.

	      If  the Mod argument is given, the result	contains a ModAnalysis
	      tuple for	module Mod only, otherwise  the	 result	 contains  one
	      ModAnalysis    tuple    for    all    modules    returned	  from
	      code:all_loaded()	except cprof itself.

	      All functions with a FuncCallCount lower than Limit are excluded
	      from  FuncAnalysisList. They are still included in ModCallCount,
	      though. The default value	for Limit is 1.

       pause() -> integer()

	      Pause call count tracing for all functions in  all  modules  and
	      stop  it	for all	functions in modules to	be loaded. This	is the
	      same as (pause({'_','_','_'})+stop({on_load})).

	      See also pause/1..3 below.

       pause(FuncSpec) -> integer()
       pause(Mod, Func)	-> integer()
       pause(Mod, Func,	Arity) -> integer()

	      Types:

		 FuncSpec = Mod	| {Mod,Func,Arity}, {FS}
		 Mod = atom()
		 Func =	atom()
		 Arity = integer()
		 FS = term()

	      Pause call counters for matching functions in matching  modules.
	      The FS argument can be used to specify the first argument	to er-
	      lang:trace_pattern/3. See	erlang(3).

	      The call counters	for all	matching functions that	has  got  call
	      count breakpoints	are paused at their current count.

	      Return the number	of matching functions that can have call count
	      breakpoints, the same as	start/0..3  with  the  same  arguments
	      would have returned.

       restart() -> integer()
       restart(FuncSpec) -> integer()
       restart(Mod, Func) -> integer()
       restart(Mod, Func, Arity) -> integer()

	      Types:

		 FuncSpec = Mod	| {Mod,Func,Arity}, {FS}
		 Mod = atom()
		 Func =	atom()
		 Arity = integer()
		 FS = term()

	      Restart  call  counters  for  the	matching functions in matching
	      modules that are call count traced. The FS argument can be  used
	      to specify the first argument to erlang:trace_pattern/3. See er-
	      lang(3).

	      The call counters	for all	matching functions that	has  got  call
	      count breakpoints	are set	to zero	and running.

	      Return the number	of matching functions that can have call count
	      breakpoints, the same as	start/0..3  with  the  same  arguments
	      would have returned.

       start() -> integer()

	      Start  call  count tracing for all functions in all modules, and
	      also for all functions in	modules	to be loaded. This is the same
	      as (start({'_','_','_'})+start({on_load})).

	      See also start/1..3 below.

       start(FuncSpec) -> integer()
       start(Mod, Func)	-> integer()
       start(Mod, Func,	Arity) -> integer()

	      Types:

		 FuncSpec = Mod	| {Mod,Func,Arity}, {FS}
		 Mod = atom()
		 Func =	atom()
		 Arity = integer()
		 FS = term()

	      Start call count tracing for matching functions in matching mod-
	      ules. The	FS argument can	be used	to specify the first  argument
	      to erlang:trace_pattern/3, for example on_load. See erlang(3).

	      Set call count breakpoints on the	matching functions that	has no
	      call count breakpoints. Call counters are	set to zero  and  run-
	      ning for all matching functions.

	      Return  the number of matching functions that has	got call count
	      breakpoints.

       stop() -> integer()

	      Stop call	count tracing for all functions	in  all	 modules,  and
	      also for all functions in	modules	to be loaded. This is the same
	      as (stop({'_','_','_'})+stop({on_load})).

	      See also stop/1..3 below.

       stop(FuncSpec) -> integer()
       stop(Mod, Func) -> integer()
       stop(Mod, Func, Arity) -> integer()

	      Types:

		 FuncSpec = Mod	| {Mod,Func,Arity}, {FS}
		 Mod = atom()
		 Func =	atom()
		 Arity = integer()
		 FS = term()

	      Stop call	count tracing for matching functions in	matching  mod-
	      ules.  The FS argument can be used to specify the	first argument
	      to erlang:trace_pattern/3, for example on_load. See erlang(3).

	      Remove call count	breakpoints from the matching  functions  that
	      has call count breakpoints.

	      Return the number	of matching functions that can have call count
	      breakpoints, the same as	start/0..3  with  the  same  arguments
	      would have returned.

SEE ALSO
       eprof(3), fprof(3), erlang(3), User's Guide

Ericsson AB			   tools 3.1			      cprof(3)

NAME | DESCRIPTION | EXPORTS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cprof&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help