From 100b825383319c9bc5ff57707348d39ad72279a9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= <psyeugenic@gmail.com>
Date: Fri, 4 Jun 2010 12:23:57 +0200
Subject: Update eprof documentation

The eprof documentation is updated to reflect the new eprof application
and some API changes and convenience functions.
---
 lib/tools/doc/src/eprof.xml | 49 ++++++++++++++++++++++++++++-----------------
 1 file changed, 31 insertions(+), 18 deletions(-)

(limited to 'lib')

diff --git a/lib/tools/doc/src/eprof.xml b/lib/tools/doc/src/eprof.xml
index ae1033f2d0..8839b2e69e 100644
--- a/lib/tools/doc/src/eprof.xml
+++ b/lib/tools/doc/src/eprof.xml
@@ -35,8 +35,7 @@
       used. The profiling is done using the Erlang trace BIFs. Tracing of
       local function calls for a specified set of processes is enabled when
       profiling is begun, and disabled when profiling is stopped.</p>
-    <p>When using Eprof, expect a significant slowdown in program execution,
-      in most cases at least 100 percent.</p>
+    <p>When using Eprof expect a slowdown in program execution.</p>
   </description>
   <funcs>
     <func>
@@ -47,15 +46,19 @@
         <v>Reason = {already_started,Pid}</v>
       </type>
       <desc>
-        <p>Starts the Eprof server which owns the Eprof internal database.</p>
+        <p>Starts the Eprof server which holds the internal state of the collected data.</p>
       </desc>
     </func>
     <func>
-      <name>start_profiling(Rootset) -> profiling | error</name>
-      <name>profile(Rootset) -> profiling | error</name>
+      <name>start_profiling(Rootset) -> profiling | {error, Reason}</name>
+      <name>start_profiling(Rootset,Pattern) -> profiling | {error, Reason}</name>
       <fsummary>Start profiling.</fsummary>
       <type>
         <v>Rootset = [atom() | pid()]</v>
+	<v>Pattern = {Module, Function, Arity}</v>
+	<v>Module = Function = atom()</v>
+	<v>Arity = integer()</v>
+        <v>Reason = term()</v>
       </type>
       <desc>
         <p>Starts profiling for the processes in <c>Rootset</c> (and any new
@@ -64,6 +67,9 @@
         <p><c>Rootset</c> is a list of pids and registered names.</p>
         <p>The function returns <c>profiling</c> if tracing could be enabled
           for all processes in <c>Rootset</c>, or <c>error</c> otherwise.</p>
+        <p>A pattern can be selected to narrow the profiling. For instance ca a specific
+	    module be selected and only the code processes executes in that module will be
+	    profiled.</p>
       </desc>
     </func>
     <func>
@@ -75,14 +81,20 @@
       </desc>
     </func>
     <func>
-      <name>profile(Rootset,Fun) -> {ok,Value} | {error,Reason} | error</name>
-      <name>profile(Rootset,Module,Function,Args) -> {ok,Value} | {error,Reason} | error</name>
+      <name>profile(Fun) -> profiling | {error, Reason}</name>
+      <name>profile(Rootset) -> profiling | {error, Reason}</name>
+      <name>profile(Rootset,Fun) -> {ok, Value} | {error,Reason}</name>
+      <name>profile(Rootset,Fun,Pattern) -> {ok, Value} | {error, Reason}</name>
+      <name>profile(Rootset,Module,Function,Args) -> {ok, Value} | {error, Reason}</name>
+      <name>profile(Rootset,Module,Function,Args,Pattern) -> {ok, Value} | {error, Reason}</name>
       <fsummary>Start profiling.</fsummary>
       <type>
         <v>Rootset = [atom() | pid()]</v>
         <v>Fun = fun() -> term()</v>
+	<v>Pattern = {Module, Function, Arity}</v>
         <v>Module = Function = atom()</v>
         <v>Args = [term()]</v>
+	<v>Arity = integer()</v>
         <v>Value = Reason = term()</v>
       </type>
       <desc>
@@ -96,7 +108,7 @@
           <c>Rootset</c>, the function returns <c>{ok,Value}</c> when
           <c>Fun()</c>/<c>apply</c> returns with the value <c>Value</c>, or
           <c>{error,Reason}</c> if <c>Fun()</c>/<c>apply</c> fails with
-          exit reason <c>Reason</c>. Otherwise it returns <c>error</c>
+	  exit reason <c>Reason</c>. Otherwise it returns <c>{error, Reason}</c>
           immediately.</p>
         <p>The programmer must ensure that the function given as argument
           is truly synchronous and that no work continues after
@@ -104,7 +116,15 @@
       </desc>
     </func>
     <func>
-      <name>analyse()</name>
+      <name>analyze() -> ok</name>
+      <name>analyze(Type) -> ok</name>
+      <name>analyze(Type,Options) -> ok</name>
+      <type>
+        <v>Type = procs | total</v>
+	<v>Options = [{filter, Filter} | {sort, Sort}</v>
+	<v>Filter = [{calls, integer()} | {time, float()}]</v>
+	<v>Sort = time | calls | mfa</v>
+      </type>
       <fsummary>Display profiling results per process.</fsummary>
       <desc>
         <p>Call this function when profiling has been stopped to display
@@ -113,17 +133,10 @@
           <item>how much time has been used by each process, and</item>
           <item>in which function calls this time has been spent.</item>
         </list>
-        <p>Time is shown as percentage of total time, not as absolute time.</p>
-      </desc>
-    </func>
-    <func>
-      <name>total_analyse()</name>
-      <fsummary>Display profiling results per function call.</fsummary>
-      <desc>
-        <p>Call this function when profiling has been stopped to display
+	<p>Call <c>analyze</c> with <c>total</c> option when profiling has been stopped to display
           the results per function call, that is in which function calls
           the time has been spent.</p>
-        <p>Time is shown as percentage of total time, not as absolute time.</p>
+        <p>Time is shown as percentage of total time and as absolute time.</p>
       </desc>
     </func>
     <func>
-- 
cgit v1.2.3