aboutsummaryrefslogtreecommitdiffstats
path: root/lib/tools/doc/src/eprof.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2010-06-11 09:38:27 +0000
committerErlang/OTP <[email protected]>2010-06-11 09:38:27 +0000
commit68cd5932ea4a1b8b371a74ab2c817c5bc9b35d1a (patch)
treeb022f6c345aa2e3966e4e43215913596bba6274a /lib/tools/doc/src/eprof.xml
parentf58c3fd91edb99ab04f57828c932fb3cc4dd46d7 (diff)
parent913c7f82cf3f2594d2f0731fd73b79cd82502ff6 (diff)
downloadotp-68cd5932ea4a1b8b371a74ab2c817c5bc9b35d1a.tar.gz
otp-68cd5932ea4a1b8b371a74ab2c817c5bc9b35d1a.tar.bz2
otp-68cd5932ea4a1b8b371a74ab2c817c5bc9b35d1a.zip
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).
Diffstat (limited to 'lib/tools/doc/src/eprof.xml')
-rw-r--r--lib/tools/doc/src/eprof.xml55
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>