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.

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[])
 {