Merge branch 'egil/eprof' into dev

* egil/eprof:
  Fix eprof to handle error cases
  Dialyzer cleanup for eprof
  Fix fprof_SUITE to use new eprof API
  Switch pattern API for eprof profile with mfa
  Update eprof documentation
  Update eprof_SUITE with more basic tests
  Rename sorting choices for eprof
  Teach eprof to align text output
  Add dump functionality to eprof
  Add log functionality to eprof
  Update eprof tests to reflect new eprof
  Add start timestamp to eprof profiling
  Teach eprof to use the new breakpoints

OTP-8706 egil/eprof

eprof has been reimplemented with support in the Erlang virtual machine and
is now both faster (i.e. slows down the code being measured less) and
scales much better. In measurements we saw speed-ups compared to the old
eprof ranging from 6 times (for sequential code that only uses one
scheduler/core) up to 84 times (for parallel code that uses 8 cores).

1 files changed, 34 insertions, 21 deletions

diff --git a/lib/tools/doc/src/eprof.xml b/lib/tools/doc/src/eprof.xml
index ae1033f2d0..6d68c90768 100644
--- a/lib/tools/doc/src/eprof.xml
+++ b/lib/tools/doc/src/eprof.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2009</year>
+      <year>1996</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       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>eprof</title>
@@ -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>