The R13B03 release.OTP_R13B03

1 files changed, 294 insertions, 0 deletions

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 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2002</year>
+      <year>2007</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.
+
+  The Initial Developer of the Original Code is Ericsson AB.
+    </legalnotice>
+
+    <title>cprof</title>
+    <prepared>Raimo Niskanen</prepared>
+    <responsible>nobody</responsible>
+    <docno></docno>
+    <approved>nobody</approved>
+    <checked></checked>
+    <date>2002-09-12</date>
+    <rev>PA1</rev>
+    <file>cprof.sgml</file>
+  </header>
+  <module>cprof</module>
+  <modulesummary>A simple Call Count Profiling Tool using breakpoints for minimal runtime performance impact.</modulesummary>
+  <description>
+    <p>The <c>cprof</c> 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. 
+      </p>
+    <p>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 <term id="BIF"></term>s
+      cannot be call count traced.
+      </p>
+    <p>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.
+      </p>
+    <p>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.
+      </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 degradation in the vicinity
+      of 10 percent.
+            <marker id="analyse"></marker>
+</p>
+  </description>
+  <funcs>
+    <func>
+      <name>analyse() -> {AllCallCount, ModAnalysisList}</name>
+      <name>analyse(Limit) -> {AllCallCount, ModAnalysisList}</name>
+      <name>analyse(Mod) -> ModAnlysis</name>
+      <name>analyse(Mod, Limit) -> ModAnalysis</name>
+      <fsummary>Collect and analyse call counters.</fsummary>
+      <type>
+        <v>Limit = integer()</v>
+        <v>Mod = atom()</v>
+        <v>AllCallCount = integer()</v>
+        <v>ModAnalysisList = [ModAnalysis]</v>
+        <v>ModAnalysis = {Mod, ModCallCount, FuncAnalysisList}</v>
+        <v>ModCallCount = integer()</v>
+        <v>FuncAnalysisList = [{{Mod, Func, Arity}, FuncCallCount}]</v>
+        <v>Func = atom()</v>
+        <v>Arity = integer()</v>
+        <v>FuncCallCount = integer()</v>
+      </type>
+      <desc>
+        <p>Collects and analyses the call counters presently in the
+          node for either module <c>Mod</c>, or for all modules
+          (except <c>cprof</c> itself), and returns: </p>
+        <taglist>
+          <tag><c>FuncAnalysisList</c></tag>
+          <item>A list of tuples, one for each function in a module, in
+           decreasing <c>FuncCallCount</c> order.</item>
+          <tag><c>ModCallCount</c></tag>
+          <item>The sum of <c>FuncCallCount</c> values for all
+           functions in module <c>Mod</c>.</item>
+          <tag><c>AllCallCount</c></tag>
+          <item>The sum of <c>ModCallCount</c> values for all modules
+           concerned in <c>ModAnalysisList</c>.</item>
+          <tag><c>ModAnalysisList</c></tag>
+          <item>A list of tuples, one for each module except
+          <c>cprof</c>, in decreasing <c>ModCallCount</c> order.</item>
+        </taglist>
+        <p>If call counters are still running while
+          <c>analyse/0..2</c> is executing, you might get an
+          inconsistent result. This happens if the process executing
+          <c>analyse/0..2</c> gets scheduled out so some other process
+          can increment the counters that are being analysed, Calling
+          <c>pause()</c> before analysing takes care of the problem.
+          </p>
+        <p>If the <c>Mod</c> argument is given, the result contains a
+          <c>ModAnalysis</c> tuple for module <c>Mod</c> only,
+          otherwise the result contains one <c>ModAnalysis</c> tuple
+          for all  modules returned from <c>code:all_loaded()</c>
+          except <c>cprof</c> itself.
+          </p>
+        <p>All functions with a <c>FuncCallCount</c> lower than
+          <c>Limit</c> are excluded from <c>FuncAnalysisList</c>. They
+          are still included in <c>ModCallCount</c>, though. 
+          The default value for <c>Limit</c> is <c>1</c>.
+                    <marker id="pause_0"></marker>
+</p>
+      </desc>
+    </func>
+    <func>
+      <name>pause() -> integer()</name>
+      <fsummary>Pause running call count trace for all functions.</fsummary>
+      <desc>
+        <p>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 
+          <c>(pause({'_','_','_'})+stop({on_load}))</c>.
+          </p>
+        <p>See also 
+          <seealso marker="#pause">pause/1..3</seealso> below.
+                    <marker id="pause"></marker>
+</p>
+      </desc>
+    </func>
+    <func>
+      <name>pause(FuncSpec) -> integer()</name>
+      <name>pause(Mod, Func) -> integer()</name>
+      <name>pause(Mod, Func, Arity) -> integer()</name>
+      <fsummary>Pause running call count trace for matching functions.</fsummary>
+      <type>
+        <v>FuncSpec = Mod | {Mod,Func,Arity}, {FS}</v>
+        <v>Mod = atom()</v>
+        <v>Func = atom()</v>
+        <v>Arity = integer()</v>
+        <v>FS = term()</v>
+      </type>
+      <desc>
+        <p>Pause call counters for matching functions in matching 
+          modules. The <c>FS</c> argument can be used to
+          specify the first argument to
+          <c>erlang:trace_pattern/3</c>. See erlang(3). 
+          </p>
+        <p>The call counters for all matching functions that
+          has got call count breakpoints are paused at their current
+          count. 
+          </p>
+        <p>Return the number of matching functions that can have
+          call count breakpoints, the same as
+          <c>start/0..3</c> with the same arguments would have
+          returned. 
+                    <marker id="restart"></marker>
+</p>
+      </desc>
+    </func>
+    <func>
+      <name>restart() -> integer()</name>
+      <name>restart(FuncSpec) -> integer()</name>
+      <name>restart(Mod, Func) -> integer()</name>
+      <name>restart(Mod, Func, Arity) -> integer()</name>
+      <fsummary>Restart existing call counters for matching functions.</fsummary>
+      <type>
+        <v>FuncSpec = Mod | {Mod,Func,Arity}, {FS}</v>
+        <v>Mod = atom()</v>
+        <v>Func = atom()</v>
+        <v>Arity = integer()</v>
+        <v>FS = term()</v>
+      </type>
+      <desc>
+        <p>Restart call counters for the matching functions in
+          matching modules that are call count traced. The <c>FS</c>
+          argument can be used to specify the first argument to
+          <c>erlang:trace_pattern/3</c>. See erlang(3).
+          </p>
+        <p>The call counters for all matching functions that has got
+          call count breakpoints are set to zero and running.
+          </p>
+        <p>Return the number of matching functions that can have
+          call count breakpoints, the same as
+          <c>start/0..3</c> with the same arguments would have
+          returned. 
+                    <marker id="start_0"></marker>
+</p>
+      </desc>
+    </func>
+    <func>
+      <name>start() -> integer()</name>
+      <fsummary>Start call count tracing for all functions.</fsummary>
+      <desc>
+        <p>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 
+          <c>(start({'_','_','_'})+start({on_load}))</c>.
+          </p>
+        <p>See also 
+          <seealso marker="#start">start/1..3</seealso> below.
+                    <marker id="start"></marker>
+</p>
+      </desc>
+    </func>
+    <func>
+      <name>start(FuncSpec) -> integer()</name>
+      <name>start(Mod, Func) -> integer()</name>
+      <name>start(Mod, Func, Arity) -> integer()</name>
+      <fsummary>Start call count tracing for matching functions.</fsummary>
+      <type>
+        <v>FuncSpec = Mod | {Mod,Func,Arity}, {FS}</v>
+        <v>Mod = atom()</v>
+        <v>Func = atom()</v>
+        <v>Arity = integer()</v>
+        <v>FS = term()</v>
+      </type>
+      <desc>
+        <p>Start call count tracing for matching functions in matching 
+          modules. The <c>FS</c> argument can be used to specify the
+          first argument to <c>erlang:trace_pattern/3</c>, for example
+          <c>on_load</c>. See erlang(3). 
+          </p>
+        <p>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.
+          </p>
+        <p>Return the number of matching functions that has got
+          call count breakpoints.
+                    <marker id="stop_0"></marker>
+</p>
+      </desc>
+    </func>
+    <func>
+      <name>stop() -> integer()</name>
+      <fsummary>Stop call count tracing for all functions.</fsummary>
+      <desc>
+        <p>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 
+          <c>(stop({'_','_','_'})+stop({on_load}))</c>.
+          </p>
+        <p>See also 
+          <seealso marker="#stop">stop/1..3</seealso> below.
+                    <marker id="stop"></marker>
+</p>
+      </desc>
+    </func>
+    <func>
+      <name>stop(FuncSpec) -> integer()</name>
+      <name>stop(Mod, Func) -> integer()</name>
+      <name>stop(Mod, Func, Arity) -> integer()</name>
+      <fsummary>Stop call count tracing for matching functions.</fsummary>
+      <type>
+        <v>FuncSpec = Mod | {Mod,Func,Arity}, {FS}</v>
+        <v>Mod = atom()</v>
+        <v>Func = atom()</v>
+        <v>Arity = integer()</v>
+        <v>FS = term()</v>
+      </type>
+      <desc>
+        <p>Stop call count tracing for matching functions in matching 
+          modules. The <c>FS</c> argument can be used to specify the
+          first argument to <c>erlang:trace_pattern/3</c>, for example
+          <c>on_load</c>. See erlang(3). 
+          </p>
+        <p>Remove call count breakpoints from the matching functions that
+          has call count breakpoints.
+          </p>
+        <p>Return the number of matching functions that can have
+          call count breakpoints, the same as
+          <c>start/0..3</c> with the same arguments would have
+          returned. 
+          </p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>See Also</title>
+    <p><seealso marker="eprof">eprof</seealso>(3), 
+      <seealso marker="fprof">fprof</seealso>(3), 
+      erlang(3), 
+      <seealso marker="cprof_chapter">User's Guide</seealso></p>
+  </section>
+</erlref>
+