aboutsummaryrefslogtreecommitdiffstats
path: root/lib/tools/doc/src/cprof_chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/tools/doc/src/cprof_chapter.xml')
-rw-r--r--lib/tools/doc/src/cprof_chapter.xml228
1 files changed, 228 insertions, 0 deletions
diff --git a/lib/tools/doc/src/cprof_chapter.xml b/lib/tools/doc/src/cprof_chapter.xml
new file mode 100644
index 0000000000..cf6a6f843a
--- /dev/null
+++ b/lib/tools/doc/src/cprof_chapter.xml
@@ -0,0 +1,228 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2002</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ 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.
+
+ </legalnotice>
+
+ <title>cprof - The Call Count Profiler</title>
+ <prepared>Raimo Niskanen</prepared>
+ <responsible>nobody</responsible>
+ <docno></docno>
+ <approved>nobody</approved>
+ <checked>no</checked>
+ <date>2002-09-11</date>
+ <rev>PA1</rev>
+ <file>cprof_chapter.xml</file>
+ </header>
+ <p><c>cprof</c> is a profiling tool that can be used to get a picture of
+ how often different functions in the system are called.
+ </p>
+ <p><c>cprof</c> uses breakpoints similar to local call trace,
+ but containing counters, to collect profiling
+ data. Therfore there is no need for special compilation of any
+ module to be profiled.
+ </p>
+ <p><c>cprof</c> presents all profiled modules in decreasing total
+ call count order, and for each module presents all profiled
+ functions also in decreasing call count order. A call count limit
+ can be specified to filter out all functions below the limit.
+ </p>
+ <p>Profiling is done in the following steps:</p>
+ <taglist>
+ <tag><c>cprof:start/0..3</c></tag>
+ <item>Starts profiling with zeroed call counters for specified
+ functions by setting call count breakpoints on them. </item>
+ <tag><c>Mod:Fun()</c></tag>
+ <item>Runs the code to be profiled.</item>
+ <tag><c>cprof:pause/0..3</c></tag>
+ <item>Pauses the call counters for specified functions. This minimises
+ the impact of code running in the background or in the shell
+ that disturbs the profiling. Call counters are automatically
+ paused when they "hit the ceiling" of the host machine word
+ size. For a 32 bit host the maximum counter value is
+ 2147483647.</item>
+ <tag><c>cprof:analyse/0..2</c></tag>
+ <item>Collects call counters and computes the result.</item>
+ <tag><c>cprof:restart/0..3</c></tag>
+ <item>Restarts the call counters from zero for specified
+ functions. Can be used to collect a new set of counters without
+ having to stop and start call count profiling.</item>
+ <tag><c>cprof:stop/0..3</c></tag>
+ <item>Stops profiling by removing call count breakpoints from
+ specified functions.</item>
+ </taglist>
+ <p>Functions can be specified as either all in the system, all in one
+ module, all arities of one function, one function, or all
+ functions in all modules not yet loaded. As for now, BIFs cannot
+ be call count traced.
+ </p>
+ <p>The analysis result can either be for all modules, or for one
+ module. In either case a call count limit can be given to filter
+ out the functions with a call count below the limit. The all
+ modules analysis does <em>not</em> contain the module <c>cprof</c>
+ itself, it can only be analysed by specifying it as a single
+ module to analyse.
+ </p>
+ <p>Call count tracing is very lightweight compared to other forms of
+ tracing since no trace message has to be generated. Some
+ measurements indicates performance degradations in the vicinity of
+ 10 percent.
+ </p>
+ <p>The following sections show some examples of profiling with
+ <c>cprof</c>. See also
+ <seealso marker="cprof">cprof(3)</seealso>.
+ </p>
+
+ <section>
+ <title>Example: Background work</title>
+ <p>From the Erlang shell:</p>
+ <pre>
+1> <input>cprof:start(), cprof:pause(). % Stop counters just after start</input>
+3476
+2> <input>cprof:analyse().</input>
+{30,
+ [{erl_eval,11,
+ [{{erl_eval,expr,3},3},
+ {{erl_eval,'-merge_bindings/2-fun-0-',2},2},
+ {{erl_eval,expand_module_name,2},1},
+ {{erl_eval,merge_bindings,2},1},
+ {{erl_eval,binding,2},1},
+ {{erl_eval,expr_list,5},1},
+ {{erl_eval,expr_list,3},1},
+ {{erl_eval,exprs,4},1}]},
+ {orddict,8,
+ [{{orddict,find,2},6},
+ {{orddict,dict_to_list,1},1},
+ {{orddict,to_list,1},1}]},
+ {packages,7,[{{packages,is_segmented_1,1},6},
+ {{packages,is_segmented,1},1}]},
+ {lists,4,[{{lists,foldl,3},3},{{lists,reverse,1},1}]}]}
+3> <input>cprof:analyse(cprof).</input>
+{cprof,3,[{{cprof,tr,2},2},{{cprof,pause,0},1}]}
+4> <input>cprof:stop().</input>
+3476</pre>
+ <p>The example showed the background work that the shell performs
+ just to interpret the first command line. Most work is done by
+ <c>erl_eval</c> and <c>orddict</c>.
+ </p>
+ <p>What is captured in this example is the part of the work the
+ shell does while interpreting the command line that occurs
+ between the actual calls to <c>cprof:start()</c> and
+ <c>cprof:analyse()</c>.
+ </p>
+ </section>
+
+ <section>
+ <title>Example: One module</title>
+ <p>From the Erlang shell:</p>
+ <pre>
+1> <input>cprof:start(),R=calendar:day_of_the_week(1896,4,27),cprof:pause(),R.</input>
+1
+2> <input>cprof:analyse(calendar).</input>
+{calendar,9,
+ [{{calendar,df,2},1},
+ {{calendar,dm,1},1},
+ {{calendar,dy,1},1},
+ {{calendar,last_day_of_the_month1,2},1},
+ {{calendar,last_day_of_the_month,2},1},
+ {{calendar,is_leap_year1,1},1},
+ {{calendar,is_leap_year,1},1},
+ {{calendar,day_of_the_week,3},1},
+ {{calendar,date_to_gregorian_days,3},1}]}
+3> <input>cprof:stop().</input>
+3271</pre>
+ <p>The example tells us that "Aktiebolaget LM Ericsson &amp; Co"
+ was registered on a Monday (since the return value
+ of the first command is 1), and that the <c>calendar</c> module
+ needed 9 function calls to calculate that.
+ </p>
+ <p>Using <c>cprof:analyse()</c> in this example also shows
+ approximately the same background work as in the first example.
+ </p>
+ </section>
+
+ <section>
+ <title>Example: In the code</title>
+ <p>Write a module:</p>
+ <pre>
+-module(sort).
+
+-export([do/1]).
+
+do(N) ->
+ cprof:stop(),
+ cprof:start(),
+ do(N, []).
+
+do(0, L) ->
+ R = lists:sort(L),
+ cprof:pause(),
+ R;
+do(N, L) ->
+ do(N-1, [random:uniform(256)-1 | L]).</pre>
+ <p>From the Erlang shell:</p>
+ <pre>
+1> <input>c(sort).</input>
+{ok,sort}
+2> <input>l(random).</input>
+{module,random}
+3> <input>sort:do(1000).</input>
+[0,0,1,1,1,1,1,1,2,2,2,3,3,3,3,3,4,4,4,5,5,5,5,6,6,6,6,6,6|...]
+4> <input>cprof:analyse().</input>
+{9050,
+ [{lists_sort,6047,
+ [{{lists_sort,merge3_2,6},923},
+ {{lists_sort,merge3_1,6},879},
+ {{lists_sort,split_2,5},661},
+ {{lists_sort,rmerge3_1,6},580},
+ {{lists_sort,rmerge3_2,6},543},
+ {{lists_sort,merge3_12_3,6},531},
+ {{lists_sort,merge3_21_3,6},383},
+ {{lists_sort,split_2_1,6},338},
+ {{lists_sort,rmerge3_21_3,6},299},
+ {{lists_sort,rmerge3_12_3,6},205},
+ {{lists_sort,rmerge2_2,4},180},
+ {{lists_sort,rmerge2_1,4},171},
+ {{lists_sort,merge2_1,4},127},
+ {{lists_sort,merge2_2,4},121},
+ {{lists_sort,mergel,2},79},
+ {{lists_sort,rmergel,2},27}]},
+ {random,2001,
+ [{{random,uniform,1},1000},
+ {{random,uniform,0},1000},
+ {{random,seed0,0},1}]},
+ {sort,1001,[{{sort,do,2},1001}]},
+ {lists,1,[{{lists,sort,1},1}]}]}
+5> <input>cprof:stop().</input>
+5369</pre>
+ <p>The example shows some details of how <c>lists:sort/1</c>
+ works. It used 6047 function calls in the module
+ <c>lists_sort</c> to complete the work.
+ </p>
+ <p>This time, since the shell was not involved, no other work was
+ done in the system during the profiling. If you retry the same
+ example with a freshly started Erlang emulator, but omit the
+ command <c>l(random)</c>, the analysis will show a lot more
+ function calls done by <c>code_server</c> and others to
+ automatically load the module <c>random</c>.
+ </p>
+ </section>
+</chapter>
+