Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

regenerated docs.

  • Loading branch information...
commit 90b830681cb8a80359fa3095693aab2f3d44f6dc 1 parent b36b845
@huiqing huiqing authored
View
19 doc/overview-summary.html
@@ -61,10 +61,11 @@
<p>The function <a href="percept2:profile-3">percept2:profile/3</a> takes 3 parameters. A file specification for the data destination as the first argument. The file specification can be a filename (which is the case for Percept) or a wrap file specification as what is used by the <code>dbg</code> library. If a single filename is specified, all the trace messages are saved in this file; if a wrap file specification is used, then the trace is written
to a limited number of files each with a limited size. The actual filenames are Filename ++ SeqCnt ++ Suffix, where SeqCnt counts as a decimal string from 0 to WrapCnt. </p>
-<p>With the current version of Percept2, if the number of files in this wrap trace is as many as WrapCnt, the oldest file is deleted then a new file is opened to become the current (as what is described in <code>dbg</code>). For off-line profiling, this means some profiling data may get lost. We are in the process of addressing this problem, and at this stage, we assume the WrapCnt and WrapSize are big enough to accommodate all the trace data.</p>
+<p>With the current version of Percept2, if the number of files in this wrap trace is as many as WrapCnt, the oldest file is deleted then a new file is opened to become the current (as what is described in <code>dbg</code>). For off-line profiling, this means some profiling data may get lost. We are in the process of addressing this problem, and at this stage, we assume the WrapCnt and WrapSize are big enough to accommodate all the trace data.</p>
+
<p>The second argument is a callback entry-point, from where the profiling starts. The third argument is a list of module names whose functions (both exported
-<p>The second argument is a callback entry-point, from where the profiling starts.</p>
-
+functions and local functions) will be traced. No functions will be traced if <code>Modules</code> is an empty list.</p>
+
<p>The profiling starts with executing the entry function given, and goes on for the whole duration until the entry function retures and the
the profiling has concluded.</p>
@@ -72,9 +73,8 @@
<p>Assume there is a directory named <code>test</code> which contains some Erlang files, we could use the following command to start the profiling
of the similar code detection being applied to the <code>test</code> directory.</p>
-
-<pre> percept2:profile("sim_code.dat",
- {sim_code,sim_code_detection, [["./test"], 3, 40, 2, 4, 0.8, [], 8]},
+
+<pre> percept2:profile("sim_code.dat",
{sim_code,sim_code_detection, [["./test"], 3, 40, 2, 4, 0.8, [], 8]}, [sim_code])</pre>
<p>In this example, we choose to profile the message passing between processes, the scheduling and states of processes/ports, and also the call/return_to activities of those functions exported by module <code>sim_code</code> (as a matter of fact, all the functions defined in this module are exported).</p>
@@ -82,9 +82,8 @@
<p>Percept2 sets up the trace and profiling facilities to listen for the traced event. It then stores these events to the file: sim_code.dat. </p>
<p>Alternatively, we could use the following command to have multiple data files to store the trace data:</p>
-
-<pre> percept2:profile({"sim_code", wrap, ".dat", 20000000, 10},
- {sim_code,sim_code_detection, [["./test"], 3, 40, 2, 4, 0.8, [], 8]},
+
+<pre> percept2:profile({"sim_code", wrap, ".dat", 20000000, 10},
{sim_code,sim_code_detection, [["./test"], 3, 40, 2, 4, 0.8, [], 8]}, [sim_code])</pre>
<p>In the latter case, Percept2 stores trace events to files: sim_code0.dat, sim_code1.dat, etc. The actual run of this profiling command generated
@@ -208,6 +207,6 @@
The work is sponsored by the European Union Seventh Framework Programme(FP7).
We are very grateful that we were able to extend the <a href="http://www.erlang.org/doc/man/percept.html">Percept</a> tool.
-<hr>
+<hr>
<div class="navbar"><a name="#navbar_bottom"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<p><i>Generated by EDoc, Sep 26 2012, 10:00:54.</i></p>
View
17 doc/overview.edoc
@@ -56,10 +56,11 @@ to a limited number of files each with a limited size. The actual filenames are
With the current version of Percept2, if the number of files in this wrap trace is as many as WrapCnt, the oldest file is deleted then a new file is opened to become the current (as what is described in `dbg'). For off-line profiling, this means some profiling data may get lost. We are in the process of addressing this problem, and at this stage, we assume the WrapCnt and WrapSize are big enough to accommodate all the trace data.
-The second argument is a callback entry-point, from where the profiling starts.
+The second argument is a callback entry-point, from where the profiling starts. The third argument is a list of module names whose functions (both exported
+functions and local functions) will be traced. No functions will be traced if `Modules' is an empty list.
-The third argument is a list of profiler options. While the standard trace/profile flags can be used in the list, Percept2 also provides a number of flags to represent sets of frequently used flag combinations. For example, the flag `concurreny' for `[procs, runnable_procs, runnable_ports, scheduler]', `message' for `[send, receive]', and `process_scheduling' for `[running, exiting, scheduler_id]'. It is also possible to specify which functions to trace by giving a tuple in the format of `{function, MFA}', where the MFA argument should be a tuple like {Module, Function, Arity}, and the wildcard atom '_' can by used in the same way as in match specification. When functions are traced, the following trace flags
-are enabled: `[call, return_to, arity]'.
+The profiling starts with executing the entry function given, and goes on for the whole duration until the entry function retures and the
+the profiling has concluded.
To illustrate how the tool works, let's take a <em>similar code detection </em>algorithm for Erlang programs as an example. The similar code detection program takes a list of directories/files and some threshold values as parameters, and returns the similar code fragments found in those Erlang files.
@@ -67,9 +68,8 @@ Assume there is a directory named `test' which contains some Erlang files, we co
of the similar code detection being applied to the `test' directory.
``` percept2:profile("sim_code.dat",
- {sim_code,sim_code_detection, [["./test"], 3, 40, 2, 4, 0.8, [], 8]},
- [message, process_scheduling, concurrency,{function, [{sim_code, '_','_'}]}])'''
-
+ {sim_code,sim_code_detection, [["./test"], 3, 40, 2, 4, 0.8, [], 8]}, [sim_code])'''
+
In this example, we choose to profile the message passing between processes, the scheduling and states of processes/ports, and also the call/return_to activities of those functions exported by module `sim_code' (as a matter of fact, all the functions defined in this module are exported).
Percept2 sets up the trace and profiling facilities to listen for the traced event. It then stores these events to the file: sim_code.dat.
@@ -77,9 +77,8 @@ Percept2 sets up the trace and profiling facilities to listen for the traced eve
Alternatively, we could use the following command to have multiple data files to store the trace data:
``` percept2:profile({"sim_code", wrap, ".dat", 20000000, 10},
- {sim_code,sim_code_detection, [["./test"], 3, 40, 2, 4, 0.8, [], 8]},
- [message, process_scheduling, concurrency,{function, [{sim_code, '_','_'}]}])'''
-
+ {sim_code,sim_code_detection, [["./test"], 3, 40, 2, 4, 0.8, [], 8]}, [sim_code])'''
+
In the latter case, Percept2 stores trace events to files: sim_code0.dat, sim_code1.dat, etc. The actual run of this profiling command generated
4 data files: i.e. `sim_code0.dat', `sim_code1.dat', `sim_code2.dat' and `sim_code3.dat'.
View
49 doc/percept2.html
@@ -43,28 +43,18 @@ <h3 class="typedecl"><a name="type-filespec">filespec()</a></h3>
<p><tt>filespec() = <a href="file.html#type-filename">file:filename()</a> | {<a href="file.html#type-filename">file:filename()</a>, wrap, Suffix::string(), WrapSize::pos_integer(), WrapCnt::pos_integer()}</tt></p>
-<h3 class="typedecl"><a name="type-percept_option">percept_option()</a></h3>
-<p><tt>percept_option() = concurreny | message | process_scheduling | {function, [mfa()]} | <a href="#type-trace_flags">trace_flags()</a> | <a href="#type-profile_flags">profile_flags()</a></tt></p>
-
-
-<h3 class="typedecl"><a name="type-profile_flags">profile_flags()</a></h3>
-<p><tt>profile_flags() = runnable_procs | runnable_ports | scheduler | exclusive</tt></p>
-
-
-<h3 class="typedecl"><a name="type-trace_flags">trace_flags()</a></h3>
-<p><tt>trace_flags() = all | send | 'receive' | procs | call | silent | return_to | running | exiting | garbage_collection | timestamp | cpu_timestamp | arity | set_on_spawn | set_on_first_spawn | set_on_link | set_on_first_link</tt></p>
+<h3 class="typedecl"><a name="type-module_name">module_name()</a></h3>
+<p><tt>module_name() = atom()</tt></p>
<h2><a name="index">Function Index</a></h2>
<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#analyze-1">analyze/1</a></td><td>Analyse the trace data collected.</td></tr>
-<tr><td valign="top"><a href="#profile-1">profile/1</a></td><td>Profile to file(s) and only profile process/ports concurrency
- activities.</td></tr>
-<tr><td valign="top"><a href="#profile-2">profile/2</a></td><td>Profile to file(s) with user-specified profiling/tracing options.</td></tr>
-<tr><td valign="top"><a href="#profile-3">profile/3</a></td><td>Profile to file(s) with user-specified profiling/tracing options.</td></tr>
+<tr><td valign="top"><a href="#profile-2">profile/2</a></td><td>Profile to file.</td></tr>
+<tr><td valign="top"><a href="#profile-3">profile/3</a></td><td>Profile to file.</td></tr>
<tr><td valign="top"><a href="#start_webserver-0">start_webserver/0</a></td><td>Starts webserver.</td></tr>
<tr><td valign="top"><a href="#start_webserver-1">start_webserver/1</a></td><td>Starts webserver with a given port number.</td></tr>
<tr><td valign="top"><a href="#stop_db-0">stop_db/0</a></td><td>Stops the percept2 database.</td></tr>
-<tr><td valign="top"><a href="#stop_profile-0">stop_profile/0</a></td><td>Stops the profling.</td></tr>
+<tr><td valign="top"><a href="#stop_profile-0">stop_profile/0</a></td><td>Stops the profiling.</td></tr>
<tr><td valign="top"><a href="#stop_webserver-0">stop_webserver/0</a></td><td>Stops webserver.</td></tr>
</table>
@@ -75,23 +65,26 @@ <h3 class="function"><a name="analyze-1">analyze/1</a></h3>
<p><tt>analyze(FileNames::[<a href="file.html#type-filename">file:filename()</a>]) -&gt; ok | {error, any()}</tt><br></p>
</div><p>Analyse the trace data collected. See the <a href="overview-summary.html">Overview</a> page for examples.</p>
-<h3 class="function"><a name="profile-1">profile/1</a></h3>
-<div class="spec">
-<p><tt>profile(FileSpec::<a href="#type-filespec">filespec()</a>) -&gt; {ok, Port} | {already_started, Port}</tt><br></p>
-</div><p>Profile to file(s) and only profile process/ports concurrency
- activities.</p>
-<p><b>See also:</b> <a href="#stop_profile-0">stop_profile/0</a>.</p>
-
<h3 class="function"><a name="profile-2">profile/2</a></h3>
<div class="spec">
-<p><tt>profile(FileSpec::<a href="#type-filespec">filespec()</a>, Options::[<a href="#type-percept_option">percept_option()</a>]) -&gt; {ok, port()} | {already_started, port()}</tt><br></p>
-</div><p>Profile to file(s) with user-specified profiling/tracing options.</p>
+<p><tt>profile(FileSpec::<a href="#type-filespec">filespec()</a>, Modules::[<a href="#type-module_name">module_name()</a>]) -&gt; {ok, Port} | {already_started, Port}</tt><br></p>
+</div><p><p>Profile to file. Process/scheduler/port activities are
+ traced; <code>Modules</code> specifies the list of module names whose
+ functions (both exported and local functions) should be traced.
+ No functions will be traced if <code>Modules</code> is an empty list.</p>
+
+ The profiling starts when the function is called, and goes no until
+ <code>stop_profile/0</code> is called.</p>
<p><b>See also:</b> <a href="#stop_profile-0">stop_profile/0</a>.</p>
<h3 class="function"><a name="profile-3">profile/3</a></h3>
<div class="spec">
-<p><tt>profile(Filename::string(), MFA::mfa(), Options::[<a href="#type-percept_option">percept_option()</a>]) -&gt; ok | {already_started, Port} | {error, not_started}</tt><br></p>
-</div><p>Profile to file(s) with user-specified profiling/tracing options.
+<p><tt>profile(FileSpec::<a href="#type-filespec">filespec()</a>, Entry::{atom(), atom(), list()}, Modules::[<a href="#type-module_name">module_name()</a>]) -&gt; ok | {already_started, port()} | {error, not_started}</tt><br></p>
+</div><p><p>Profile to file. Process/scheduler/port activities are
+ traced; <code>Modules</code> specifies the list of module names whose
+ functions (both exported and local functions) should be traced.
+ No functions will be traced if <code>Modules</code> is an empty list.</p>
+
The profiling starts with executing the entry function given, and goes
on for the whole duration until the entry function retures and the
the profiling has concluded.</p>
@@ -117,7 +110,7 @@ <h3 class="function"><a name="stop_db-0">stop_db/0</a></h3>
<h3 class="function"><a name="stop_profile-0">stop_profile/0</a></h3>
<div class="spec">
<p><tt>stop_profile() -&gt; ok | {error, not_started}</tt><br></p>
-</div><p>Stops the profling.</p>
+</div><p>Stops the profiling.</p>
<p><b>See also:</b> <a href="#profile-1">profile/1</a>, <a href="#profile-2">profile/2</a>.</p>
<h3 class="function"><a name="stop_webserver-0">stop_webserver/0</a></h3>
@@ -127,6 +120,6 @@ <h3 class="function"><a name="stop_webserver-0">stop_webserver/0</a></h3>
<hr>
<div class="navbar"><a name="#navbar_bottom"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
-<p><i>Generated by EDoc, Sep 24 2012, 11:08:26.</i></p>
+<p><i>Generated by EDoc, Sep 26 2012, 10:00:53.</i></p>
</body>
</html>
View
2  doc/percept2_sampling.html
@@ -122,6 +122,6 @@ <h3 class="function"><a name="sample-5">sample/5</a></h3>
<hr>
<div class="navbar"><a name="#navbar_bottom"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
-<p><i>Generated by EDoc, Sep 24 2012, 11:08:26.</i></p>
+<p><i>Generated by EDoc, Sep 26 2012, 10:00:54.</i></p>
</body>
</html>
Please sign in to comment.
Something went wrong with that request. Please try again.