aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src
diff options
context:
space:
mode:
authorLukas Larsson <[email protected]>2016-05-19 10:54:43 +0200
committerLukas Larsson <[email protected]>2016-05-24 10:42:16 +0200
commit115f0ba77ad7d01ab95fd9f9bbeca53f04f12284 (patch)
treec7134ee895b23d8160440cec7dd1598b1f689de3 /erts/doc/src
parent0bc0e3e51a4229245c4111667eec9133a1a8984c (diff)
downloadotp-115f0ba77ad7d01ab95fd9f9bbeca53f04f12284.tar.gz
otp-115f0ba77ad7d01ab95fd9f9bbeca53f04f12284.tar.bz2
otp-115f0ba77ad7d01ab95fd9f9bbeca53f04f12284.zip
erts: Move tracer SecondTraceTerm to Opts map
The extra trace data has been moved to the opts map in order for the tracer to be able to distinguish inbetween extra trace data 'undefined' and no extra trace data. In the same commit all opts associations have been changed so that if the tracer should not use them, the key is left unassicated instead of being sent to undefined. This should be give a small performance gain and also makes the API easier to work with.
Diffstat (limited to 'erts/doc/src')
-rw-r--r--erts/doc/src/erl_tracer.xml96
1 files changed, 45 insertions, 51 deletions
diff --git a/erts/doc/src/erl_tracer.xml b/erts/doc/src/erl_tracer.xml
index d4c8bbad31..7841fdfd63 100644
--- a/erts/doc/src/erl_tracer.xml
+++ b/erts/doc/src/erl_tracer.xml
@@ -67,7 +67,7 @@
<desc>
<p>The different trace tags that the tracer will be called with.
Each trace tag is described in greater detail in
- <seealso marker="#Module:trace/6">Module:trace/6</seealso>
+ <seealso marker="#Module:trace/5">Module:trace/5</seealso>
</p>
</desc>
</datatype>
@@ -84,14 +84,18 @@
<p>The options for the tracee.</p>
<taglist>
<tag><c>timestamp</c></tag>
- <item>If not set to <c>undefined</c>, the tracer has been requested to
- include a timestamp.</item>
+ <item>If set the tracer has been requested to include a timestamp.</item>
+ <tag><c>extra</c></tag>
+ <item>If set the tracepoint has included additonal data about
+ the trace event. What the additional data is depends on which
+ <c>TraceTag</c> has been triggered. The <c>extra</c> trace data
+ corresponds to the fifth elemnt in the trace tuples described in
+ <seealso marker="erlang#trace_3_trace_messages">erlang:trace/3</seealso>.</item>
<tag><c>match_spec_result</c></tag>
- <item>If not set to <c>true</c>, the tracer has been requested to
- include the output of a match specification that was run.</item>
+ <item>If set the tracer has been requested to include the output
+ of a match specification that was run.</item>
<tag><c>scheduler_id</c></tag>
- <item>Set to a number if the scheduler id is to be included by the tracer.
- Otherwise it is set to <c>undefined</c>.</item>
+ <item>Set the scheduler id is to be included by the tracer.</item>
</taglist>
</desc>
</datatype>
@@ -115,23 +119,23 @@
<taglist>
<tag><seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso></tag>
<item>Mandatory</item>
- <tag><seealso marker="#Module:trace/6"><c>Module:trace/6</c></seealso></tag>
+ <tag><seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso></tag>
<item>Mandatory</item>
<tag><seealso marker="#Module:enabled_procs/3"><c>Module:enabled_procs/3</c></seealso></tag>
<item>Optional</item>
- <tag><seealso marker="#Module:trace_procs/6"><c>Module:trace_procs/6</c></seealso></tag>
+ <tag><seealso marker="#Module:trace_procs/5"><c>Module:trace_procs/5</c></seealso></tag>
<item>Optional</item>
<tag><seealso marker="#Module:enabled_ports/3"><c>Module:enabled_ports/3</c></seealso></tag>
<item>Optional</item>
- <tag><seealso marker="#Module:trace_ports/6"><c>Module:trace_ports/6</c></seealso></tag>
+ <tag><seealso marker="#Module:trace_ports/5"><c>Module:trace_ports/5</c></seealso></tag>
<item>Optional</item>
<tag><seealso marker="#Module:enabled_running_ports/3"><c>Module:enabled_running_ports/3</c></seealso></tag>
<item>Optional</item>
- <tag><seealso marker="#Module:trace_running_ports/6"><c>Module:trace_running_ports/6</c></seealso></tag>
+ <tag><seealso marker="#Module:trace_running_ports/5"><c>Module:trace_running_ports/5</c></seealso></tag>
<item>Optional</item>
<tag><seealso marker="#Module:enabled_running_procs/3"><c>Module:enabled_running_procs/3</c></seealso></tag>
<item>Optional</item>
- <tag><seealso marker="#Module:trace_running_procs/6"><c>Module:trace_running_procs/6</c></seealso></tag>
+ <tag><seealso marker="#Module:trace_running_procs/5"><c>Module:trace_running_procs/5</c></seealso></tag>
<item>Optional</item>
</taglist>
@@ -166,14 +170,13 @@
</desc>
</func>
<func>
- <name>Module:trace(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag">trace_tag()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -182,17 +185,17 @@
the <seealso marker="#Module:enabled/3">Module:enabled/3</seealso>
callback returned <c>trace</c>. In it any side effects needed by
the tracer should be done. The tracepoint payload is located in
- the <c>FirstTraceTerm</c> and <c>SecondTraceTerm</c>. The content
- of the TraceTerms depends on which <c>TraceTag</c> has been triggered.
- The <c>FirstTraceTerm</c> and <c>SecondTraceTerm</c> correspond to the
- fourth and fifth slot in the trace tuples described in
+ the <c>TraceTerm</c>. The content of the TraceTerm depends on which
+ <c>TraceTag</c> has been triggered.
+ The <c>TraceTerm</c> corresponds to the
+ fourth element in the trace tuples described in
<seealso marker="erlang#trace_3_trace_messages">erlang:trace/3</seealso>.
- If the tuple only has four elements, <c>SecondTraceTerm</c> will be
- <c>undefined</c>.</p>
+ If the trace tuple has five elements, the fifth element will be sent as
+ the <c>extra</c> value in the <c>Opts</c> maps.</p>
</desc>
</func>
<func>
- <name name="trace">Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, undefined, Opts) -> Result</name>
+ <name name="trace">Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, Opts) -> Result</name>
<fsummary>Check if a sequence trace event should be generated.</fsummary>
<type>
<v>TracerState = term()</v>
@@ -228,14 +231,13 @@
</func>
<func>
- <name>Module:trace_procs(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_procs">trace_tag()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -243,7 +245,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_procs/3">Module:enabled_procs/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_procs/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_procs/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -265,14 +267,13 @@
</func>
<func>
- <name>Module:trace_ports(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_ports">trace_tag()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -280,7 +281,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_ports/3">Module:enabled_ports/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_ports/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_ports/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -302,14 +303,13 @@
</func>
<func>
- <name>Module:trace_running_procs(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_running_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_running_procs">trace_tag_running_procs()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -317,7 +317,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_running_procs/3">Module:enabled_running_procs/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_running_procs/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_running_procs/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -339,14 +339,13 @@
</func>
<func>
- <name>Module:trace_running_ports(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_running_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_running_ports">trace_tag_running_ports()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -354,7 +353,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_running_ports/3">Module:enabled_running_ports/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_running_ports/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_running_ports/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -376,14 +375,13 @@
</func>
<func>
- <name>Module:trace_call(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_call(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_call">trace_tag_call()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -391,7 +389,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_call/3">Module:enabled_call/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_call/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_call/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -413,14 +411,13 @@
</func>
<func>
- <name>Module:trace_send(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_send(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_send">trace_tag_send()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -428,7 +425,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_send/3">Module:enabled_send/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_send/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_send/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -450,14 +447,13 @@
</func>
<func>
- <name>Module:trace_receive(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_receive(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_receive">trace_tag_receive()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -465,7 +461,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_receive/3">Module:enabled_receive/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_receive/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_receive/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -487,14 +483,13 @@
</func>
<func>
- <name>Module:trace_garbage_collection(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_garbage_collection(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_gc">trace_tag_gc()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -502,7 +497,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_garbage_collection/3">Module:enabled_garbage_collection/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_garbage_collection/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_garbage_collection/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -543,7 +538,7 @@ ok
<pre>
-module(erl_msg_tracer).
--export([enabled/3, trace/6, load/0]).
+-export([enabled/3, trace/5, load/0]).
load() ->
erlang:load_nif("erl_msg_tracer", []).
@@ -551,7 +546,7 @@ load() ->
enabled(_, _, _) ->
error.
-trace(_, _, _,_, _, _) ->
+trace(_, _, _,_, _) ->
error.
</pre>
<p>erl_msg_tracer.c</p>
@@ -569,7 +564,7 @@ static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
static ErlNifFunc nif_funcs[] = {
{"enabled", 3, enabled},
- {"trace", 6, trace}
+ {"trace", 5, trace}
};
ERL_NIF_INIT(erl_msg_tracer, nif_funcs, load, NULL, upgrade, unload)
@@ -632,9 +627,8 @@ static ERL_NIF_TERM enabled(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
* argv[0]: TraceTag, should only be 'send'
* argv[1]: TracerState, process to send {argv[2], argv[4]} to
* argv[2]: Tracee
- * argv[3]: Message, ignored
- * argv[4]: Recipient
- * argv[5]: Options, ignored
+ * argv[3]: Recipient
+ * argv[4]: Options, ignored
*/
static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
{