.TH cprof 3erl "tools 3.5.3" "Ericsson AB" "Erlang Module Definition"
.SH NAME
cprof \- A simple Call Count Profiling Tool using breakpoints for minimal runtime performance impact.
.SH DESCRIPTION
.LP
The \fIcprof\fR\& 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\&.
.LP
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 BIFs cannot be call count traced\&.
.LP
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\&.
.LP
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\&.
.LP
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\&.
.SH EXPORTS
.LP
.nf

.B
analyse() ->
.B
           {AllCallCount :: integer() >= 0,
.B
            ModAnalysisList :: mod_analysis_list()}
.br
.fi
.br
.nf

.B
analyse(Limit) ->
.B
           {AllCallCount :: integer() >= 0,
.B
            ModAnalysisList :: mod_analysis_list()}
.br
.fi
.br
.nf

.B
analyse(Mod) -> ModAnalysis :: mod_analysis()
.br
.fi
.br
.nf

.B
analyse(Mod, Limit) -> ModAnalysis :: mod_analysis()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Mod = module()
.br
Limit = integer() >= 0
.br
.nf
\fBmod_analysis_list()\fR\& = [mod_analysis()]
.fi
.br
.nf
\fBmod_analysis()\fR\& = 
.br
    {Mod :: module(),
.br
     ModCallCount :: integer() >= 0,
.br
     FuncAnalysisList :: func_analysis_list()}
.fi
.br
.nf
\fBfunc_analysis_list()\fR\& = 
.br
    [{mfa(), FuncCallCount :: integer() >= 0}]
.fi
.br
.RE
.RE
.RS
.LP
Collects and analyses the call counters presently in the node for either module \fIMod\fR\&, or for all modules (except \fIcprof\fR\& itself), and returns:
.RS 2
.TP 2
.B
\fIFuncAnalysisList\fR\&:
A list of tuples, one for each function in a module, in decreasing \fIFuncCallCount\fR\& order\&.
.TP 2
.B
\fIModCallCount\fR\&:
The sum of \fIFuncCallCount\fR\& values for all functions in module \fIMod\fR\&\&.
.TP 2
.B
\fIAllCallCount\fR\&:
The sum of \fIModCallCount\fR\& values for all modules concerned in \fIModAnalysisList\fR\&\&.
.TP 2
.B
\fIModAnalysisList\fR\&:
A list of tuples, one for each module except \fIcprof\fR\&, in decreasing \fIModCallCount\fR\& order\&.
.RE
.LP
If call counters are still running while \fIanalyse/0\&.\&.2\fR\& is executing, you might get an inconsistent result\&. This happens if the process executing \fIanalyse/0\&.\&.2\fR\& gets scheduled out so some other process can increment the counters that are being analysed, Calling \fIpause()\fR\& before analysing takes care of the problem\&.
.LP
If the \fIMod\fR\& argument is given, the result contains a \fIModAnalysis\fR\& tuple for module \fIMod\fR\& only, otherwise the result contains one \fIModAnalysis\fR\& tuple for all modules returned from \fIcode:all_loaded()\fR\& except \fIcprof\fR\& itself\&.
.LP
All functions with a \fIFuncCallCount\fR\& lower than \fILimit\fR\& are excluded from \fIFuncAnalysisList\fR\&\&. They are still included in \fIModCallCount\fR\&, though\&. The default value for \fILimit\fR\& is \fI1\fR\&\&.
.RE

.LP
.nf

.B
pause() -> integer() >= 0
.br
.fi
.br
.RS
.LP
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 \fI(pause({\&'_\&',\&'_\&',\&'_\&'})+stop({on_load}))\fR\&\&.
.LP
See also \fIpause/1\&.\&.3\fR\& below\&.
.RE

.LP
.nf

.B
pause(FuncSpec) -> integer() >= 0
.br
.fi
.br
.nf

.B
pause(Mod, Func) -> integer() >= 0
.br
.fi
.br
.nf

.B
pause(Mod, Func, Arity) -> integer() >= 0
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Mod = module()
.br
Func = atom()
.br
Arity = arity()
.br
.RE
.RE
.RS
.LP
Pause call counters for matching functions in matching modules\&. The \fIFS\fR\& argument can be used to specify the first argument to \fIerlang:trace_pattern/3\fR\&\&.
.LP
The call counters for all matching functions that has got call count breakpoints are paused at their current count\&.
.LP
Return the number of matching functions that can have call count breakpoints, the same as \fIstart/0\&.\&.3\fR\& with the same arguments would have returned\&.
.RE

.LP
.nf

.B
restart() -> integer() >= 0
.br
.fi
.br
.nf

.B
restart(FuncSpec) -> integer() >= 0
.br
.fi
.br
.nf

.B
restart(Mod, Func) -> integer() >= 0
.br
.fi
.br
.nf

.B
restart(Mod, Func, Arity) -> integer() >= 0
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Mod = module()
.br
Func = atom()
.br
Arity = arity()
.br
.RE
.RE
.RS
.LP
Restart call counters for the matching functions in matching modules that are call count traced\&. The \fIFS\fR\& argument can be used to specify the first argument to \fIerlang:trace_pattern/3\fR\&\&.
.LP
The call counters for all matching functions that has got call count breakpoints are set to zero and running\&.
.LP
Return the number of matching functions that can have call count breakpoints, the same as \fIstart/0\&.\&.3\fR\& with the same arguments would have returned\&.
.RE

.LP
.nf

.B
start() -> integer() >= 0
.br
.fi
.br
.RS
.LP
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 \fI(start({\&'_\&',\&'_\&',\&'_\&'})+start({on_load}))\fR\&\&.
.LP
See also \fIstart/1\&.\&.3\fR\& below\&.
.RE

.LP
.nf

.B
start(FuncSpec) -> integer() >= 0
.br
.fi
.br
.nf

.B
start(Mod, Func) -> integer() >= 0
.br
.fi
.br
.nf

.B
start(Mod, Func, Arity) -> integer() >= 0
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Mod = module()
.br
Func = atom()
.br
Arity = arity()
.br
.RE
.RE
.RS
.LP
Start call count tracing for matching functions in matching modules\&. The \fIFS\fR\& argument can be used to specify the first argument to \fIerlang:trace_pattern/3\fR\&, for example \fIon_load\fR\&\&.
.LP
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\&.
.LP
Return the number of matching functions that has got call count breakpoints\&.
.RE

.LP
.nf

.B
stop() -> integer() >= 0
.br
.fi
.br
.RS
.LP
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 \fI(stop({\&'_\&',\&'_\&',\&'_\&'})+stop({on_load}))\fR\&\&.
.LP
See also \fIstop/1\&.\&.3\fR\& below\&.
.RE

.LP
.nf

.B
stop(FuncSpec) -> integer() >= 0
.br
.fi
.br
.nf

.B
stop(Mod, Func) -> integer() >= 0
.br
.fi
.br
.nf

.B
stop(Mod, Func, Arity) -> integer() >= 0
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Mod = module()
.br
Func = atom()
.br
Arity = arity()
.br
.RE
.RE
.RS
.LP
Stop call count tracing for matching functions in matching modules\&. The \fIFS\fR\& argument can be used to specify the first argument to \fIerlang:trace_pattern/3\fR\&, for example \fIon_load\fR\&\&.
.LP
Remove call count breakpoints from the matching functions that has call count breakpoints\&.
.LP
Return the number of matching functions that can have call count breakpoints, the same as \fIstart/0\&.\&.3\fR\& with the same arguments would have returned\&.
.RE

.SH "SEE ALSO"

.LP
eprof(3erl), fprof(3erl), erlang(3erl), User\&'s Guide