From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/tools/doc/src/cprof.xml | 294 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 lib/tools/doc/src/cprof.xml (limited to 'lib/tools/doc/src/cprof.xml') diff --git a/lib/tools/doc/src/cprof.xml b/lib/tools/doc/src/cprof.xml new file mode 100644 index 0000000000..421ed7875a --- /dev/null +++ b/lib/tools/doc/src/cprof.xml @@ -0,0 +1,294 @@ + + + + +
+ + 2002 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + cprof + Raimo Niskanen + nobody + + nobody + + 2002-09-12 + PA1 + cprof.sgml +
+ cprof + A simple Call Count Profiling Tool using breakpoints for minimal runtime performance impact. + +

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 performance 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 tracing since no trace message has to be generated. Some + measurements indicates performance degradation in the vicinity + of 10 percent. + +

+ + + + analyse() -> {AllCallCount, ModAnalysisList} + analyse(Limit) -> {AllCallCount, ModAnalysisList} + analyse(Mod) -> ModAnlysis + analyse(Mod, Limit) -> ModAnalysis + Collect and analyse call counters. + + 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 + decreasing 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 decreasing ModCallCount order. + +

If call counters are still running while + analyse/0..2 is executing, 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 running call count trace for all functions. + +

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() + Pause running call count trace for matching functions. + + 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 + erlang: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() + Restart existing call counters for matching functions. + + 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 erlang(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. + +

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() + Start call count tracing for matching functions. + + FuncSpec = Mod | {Mod,Func,Arity}, {FS} + Mod = atom() + Func = atom() + Arity = integer() + FS = term() + + +

Start call count tracing for matching functions in matching + modules. 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 running 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. + +

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() + Stop call count tracing for matching functions. + + FuncSpec = Mod | {Mod,Func,Arity}, {FS} + Mod = atom() + Func = atom() + Arity = integer() + FS = term() + + +

Stop call count tracing for matching functions in matching + modules. 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

+
+ + -- cgit v1.2.3