aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/seq_trace.xml
diff options
context:
space:
mode:
authorHans Bolinder <hasse@erlang.org>2011-05-06 16:01:56 +0200
committerHans Bolinder <hasse@erlang.org>2011-05-11 14:20:58 +0200
commit5a485461a1157fef1bb3ce8426bfd1ad57b5ca52 (patch)
treed77f79b9a1b98e7bf2bf3886ebec61d504317fc4 /lib/kernel/doc/src/seq_trace.xml
parent68fe6a14539b82250373ef114d6576e74e1b8f2e (diff)
downloadotp-5a485461a1157fef1bb3ce8426bfd1ad57b5ca52.tar.gz
otp-5a485461a1157fef1bb3ce8426bfd1ad57b5ca52.tar.bz2
otp-5a485461a1157fef1bb3ce8426bfd1ad57b5ca52.zip
Use Erlang specs and types for documentation
Diffstat (limited to 'lib/kernel/doc/src/seq_trace.xml')
-rw-r--r--lib/kernel/doc/src/seq_trace.xml95
1 files changed, 41 insertions, 54 deletions
diff --git a/lib/kernel/doc/src/seq_trace.xml b/lib/kernel/doc/src/seq_trace.xml
index 6c043dd767..1ab955bd8a 100644
--- a/lib/kernel/doc/src/seq_trace.xml
+++ b/lib/kernel/doc/src/seq_trace.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1998</year><year>2009</year>
+ <year>1998</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -47,17 +47,22 @@
from users.</p>
</note>
</description>
+ <datatypes>
+ <datatype>
+ <name name="token"/>
+ <desc>
+ <p>An opaque term (a tuple) representing a trace token.</p>
+ </desc>
+ </datatype>
+ </datatypes>
<funcs>
<func>
- <name>set_token(Token) -> PreviousToken</name>
+ <name name="set_token" arity="1"/>
<fsummary>Set the trace token</fsummary>
- <type>
- <v>Token = PreviousToken = term() | []</v>
- </type>
<desc>
- <p>Sets the trace token for the calling process to <c>Token</c>.
- If <c>Token == []</c> then tracing is disabled, otherwise
- <c>Token</c> should be an Erlang term returned from
+ <p>Sets the trace token for the calling process to <c><anno>Token</anno></c>.
+ If <c><anno>Token</anno> == []</c> then tracing is disabled, otherwise
+ <c><anno>Token</anno></c> should be an Erlang term returned from
<c>get_token/0</c> or <c>set_token/1</c>. <c>set_token/1</c>
can be used to temporarily exclude message passing from
the trace by setting the trace token to empty like this:</p>
@@ -72,18 +77,16 @@ seq_trace:set_token(OldToken), % activate the trace token again
</desc>
</func>
<func>
- <name>set_token(Component, Val) -> {Component, OldVal}</name>
+ <name name="set_token" arity="2"/>
<fsummary>Set a component of the trace token</fsummary>
- <type>
- <v>Component = label | serial | Flag</v>
- <v>&nbsp;Flag = send | 'receive' | print | timestamp </v>
- <v>Val = OldVal -- see below</v>
- </type>
+ <type name="component"/>
+ <type name="flag"/>
+ <type name="value"/>
<desc>
- <p>Sets the individual <c>Component</c> of the trace token to
- <c>Val</c>. Returns the previous value of the component.</p>
+ <p>Sets the individual <c><anno>Component</anno></c> of the trace token to
+ <c><anno>Val</anno></c>. Returns the previous value of the component.</p>
<taglist>
- <tag><c>set_token(label, Int)</c></tag>
+ <tag><c>set_token(label, <anno>Integer</anno>)</c></tag>
<item>
<p>The <c>label</c> component is an integer which
identifies all events belonging to the same sequential
@@ -93,31 +96,31 @@ seq_trace:set_token(OldToken), % activate the trace token again
</item>
<tag><c>set_token(serial, SerialValue)</c></tag>
<item>
- <p><c>SerialValue = {Previous, Current}</c>.
+ <p><c>SerialValue = {<anno>Previous</anno>, <anno>Current</anno>}</c>.
The <c>serial</c> component contains counters which
enables the traced messages to be sorted, should never be
set explicitly by the user as these counters are updated
automatically. Default is <c>{0, 0}</c>.</p>
</item>
- <tag><c>set_token(send, Bool)</c></tag>
+ <tag><c>set_token(send, <anno>Bool</anno>)</c></tag>
<item>
<p>A trace token flag (<c>true | false</c>) which
enables/disables tracing on message sending. Default is
<c>false</c>.</p>
</item>
- <tag><c>set_token('receive', Bool)</c></tag>
+ <tag><c>set_token('receive', <anno>Bool</anno>)</c></tag>
<item>
<p>A trace token flag (<c>true | false</c>) which
enables/disables tracing on message reception. Default is
<c>false</c>.</p>
</item>
- <tag><c>set_token(print, Bool)</c></tag>
+ <tag><c>set_token(print, <anno>Bool</anno>)</c></tag>
<item>
<p>A trace token flag (<c>true | false</c>) which
enables/disables tracing on explicit calls to
<c>seq_trace:print/1</c>. Default is <c>false</c>.</p>
</item>
- <tag><c>set_token(timestamp, Bool)</c></tag>
+ <tag><c>set_token(timestamp, <anno>Bool</anno>)</c></tag>
<item>
<p>A trace token flag (<c>true | false</c>) which
enables/disables a timestamp to be generated for each
@@ -127,11 +130,8 @@ seq_trace:set_token(OldToken), % activate the trace token again
</desc>
</func>
<func>
- <name>get_token() -> TraceToken</name>
+ <name name="get_token" arity="0"/>
<fsummary>Return the value of the trace token</fsummary>
- <type>
- <v>TraceToken = term() | []</v>
- </type>
<desc>
<p>Returns the value of the trace token for the calling process.
If <c>[]</c> is returned, it means that tracing is not active.
@@ -141,13 +141,11 @@ seq_trace:set_token(OldToken), % activate the trace token again
</desc>
</func>
<func>
- <name>get_token(Component) -> {Component, Val}</name>
+ <name name="get_token" arity="1"/>
<fsummary>Return the value of a trace token component</fsummary>
- <type>
- <v>Component = label | serial | Flag</v>
- <v>&nbsp;Flag = send | 'receive' | print | timestamp </v>
- <v>Val -- see set_token/2</v>
- </type>
+ <type name="component"/>
+ <type name="flag"/>
+ <type name="value"/>
<desc>
<p>Returns the value of the trace token component
<c>Component</c>. See
@@ -156,33 +154,26 @@ seq_trace:set_token(OldToken), % activate the trace token again
</desc>
</func>
<func>
- <name>print(TraceInfo) -> void()</name>
+ <name name="print" arity="1"/>
<fsummary>Put the Erlang term <c>TraceInfo</c>into the sequential trace output</fsummary>
- <type>
- <v>TraceInfo = term()</v>
- </type>
<desc>
- <p>Puts the Erlang term <c>TraceInfo</c> into the sequential
+ <p>Puts the Erlang term <c><anno>TraceInfo</anno></c> into the sequential
trace output if the calling process currently is executing
within a sequential trace and the <c>print</c> flag of
the trace token is set.</p>
</desc>
</func>
<func>
- <name>print(Label, TraceInfo) -> void()</name>
+ <name name="print" arity="2"/>
<fsummary>Put the Erlang term <c>TraceInfo</c>into the sequential trace output</fsummary>
- <type>
- <v>Label = int()</v>
- <v>TraceInfo = term()</v>
- </type>
<desc>
<p>Same as <c>print/1</c> with the additional condition that
- <c>TraceInfo</c> is output only if <c>Label</c> is equal to
+ <c><anno>TraceInfo</anno></c> is output only if <c>Label</c> is equal to
the label component of the trace token.</p>
</desc>
</func>
<func>
- <name>reset_trace() -> void()</name>
+ <name name="reset_trace" arity="0"/>
<fsummary>Stop all sequential tracing on the local node</fsummary>
<desc>
<p>Sets the trace token to empty for all processes on the
@@ -194,26 +185,22 @@ seq_trace:set_token(OldToken), % activate the trace token again
</desc>
</func>
<func>
- <name>set_system_tracer(Tracer) -> OldTracer</name>
+ <name name="set_system_tracer" arity="1"/>
<fsummary>Set the system tracer</fsummary>
- <type>
- <v>Tracer = OldTracer = pid() | port() | false</v>
- </type>
+ <type name="tracer"/>
<desc>
<p>Sets the system tracer. The system tracer can be either a
- process or port denoted by <c>Tracer</c>. Returns the previous
+ process or port denoted by <c><anno>Tracer</anno></c>. Returns the previous
value (which can be <c>false</c> if no system tracer is
active).</p>
- <p>Failure: <c>{badarg, Info}}</c> if <c>Pid</c> is not an
+ <p>Failure: <c>{badarg, Info}}</c> if <c><anno>Pid</anno></c> is not an
existing local pid.</p>
</desc>
</func>
<func>
- <name>get_system_tracer() -> Tracer</name>
+ <name name="get_system_tracer" arity="0"/>
<fsummary>Return the pid() or port() of the current system tracer.</fsummary>
- <type>
- <v>Tracer = pid() | port() | false</v>
- </type>
+ <type name="tracer"/>
<desc>
<p>Returns the pid or port identifier of the current system
tracer or <c>false</c> if no system tracer is activated.</p>