Merge branch 'lukas/erts/tracer-module-and-more/PR-1009/OTP-10268'

* lukas/erts/tracer-module-and-more/PR-1009/OTP-10268: (26 commits)
  erts: Don't trace on link events when port is dead
  erts: more logging in trace_bif_SUITE trace_bif_return
  erts: Make trace_delivered go via sys msg dispatcher again
  erts: Add comment about future trace optimizations
  erts: Optimize tracer reload test
  erts: Document erlang:match_spec_test/3
  runtime_tools: Make dbg work with erl_tracer modules
  runtime_rools: Allow new timestamp trace flags
  runtime_tools: Lots of dbg docs updates
  erts: Deallocate heap fragments from trace nif calls
  eprof: Fix tests after tracer module incompatabilities
  fprof: update to work with new spawned trace event
  erts: Add 'spawned' trace event to 'procs' trace flag
  erts: send and receive no longer need status lock
  erts: Do 'unregister' as "self-tracing"
  erts: Silence harmless valgrind warning in dec_term
  erts: Fix end_per_testcase crash in local_trace_SUITE
  observer: Update ttb to work with tracing on ports
  runtime_tools: Update dbg to work with tracing on ports
  erts: Add tracing examples in match spec docs
  ...

1 files changed, 47 insertions, 5 deletions

diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml
index 975f01cf2c..3944f24f84 100644
--- a/erts/doc/src/match_spec.xml
+++ b/erts/doc/src/match_spec.xml
@@ -287,7 +287,7 @@
         can <em>not</em> be one of the atoms <c><![CDATA[all]]></c>, <c><![CDATA[new]]></c> or 
         <c><![CDATA[existing]]></c> (unless, of course, they are registered names).
         <c><![CDATA[P2]]></c> can <em>not</em> be <c><![CDATA[cpu_timestamp]]></c> nor
-        <c><![CDATA[{tracer,_}]]></c>.
+        <c><![CDATA[tracer]]></c>.
         Returns <c><![CDATA[true]]></c> and may only be used in
         the <c><![CDATA[MatchBody]]></c> part when tracing.
         </p>
@@ -298,7 +298,7 @@
         be either a process identifier or a registered name and is given
         as the first argument to the match_spec function. 
         <c><![CDATA[P2]]></c> can <em>not</em> be <c><![CDATA[cpu_timestamp]]></c> nor
-        <c><![CDATA[{tracer,_}]]></c>. Returns
+        <c><![CDATA[tracer]]></c>. Returns
         <c><![CDATA[true]]></c> and may only be used in the <c><![CDATA[MatchBody]]></c> part
         when tracing.
         </p>
@@ -308,11 +308,14 @@
         disable list is applied first, but effectively all changes
         are applied atomically. The trace flags
         are the same as for <c><![CDATA[erlang:trace/3]]></c> not including
-        <c><![CDATA[cpu_timestamp]]></c> but including <c><![CDATA[{tracer,_}]]></c>. If a
+        <c><![CDATA[cpu_timestamp]]></c> but including <c><![CDATA[tracer]]></c>. If a
         tracer is specified in both lists, the tracer in the 
         enable list takes precedence. If no tracer is specified the
         same tracer as the process executing the match spec is 
-        used. With three parameters to this function the first is 
+        used. When using a <seealso marker="erl_tracer">tracer module</seealso>
+        the module has to be loaded before the match specification is executed.
+        If it is not loaded the match will fail.
+        With three parameters to this function the first is
         either a process identifier or the registered name of a
         process to set trace flags on, the second is the disable
         list, and the third is the enable list. Returns
@@ -525,7 +528,7 @@
   </section>
 
   <section>
-    <title>Examples</title>
+    <title>ETS Examples</title>
     <p>Match an argument list of three where the first and third arguments 
       are equal:</p>
     <code type="none"><![CDATA[
@@ -616,5 +619,44 @@
     <p>The function <c><![CDATA[ets:test_ms/2]]></c> can be useful for testing
       complicated ets matches.</p>
   </section>
+  <section>
+    <title>Tracing Examples</title>
+    <p>Only generate trace message if trace control word is set to 1:</p>
+    <code type="none"><![CDATA[
+[{'_',
+  [{'==',{get_tcw},{const, 1}}],
+  []}]
+    ]]></code>
+    <p>Only generate trace message if there is a seq trace token:</p>
+    <code type="none"><![CDATA[
+[{'_',
+  [{'==',{is_seq_trace},{const, 1}}],
+  []}]
+    ]]></code>
+    <p>Remove 'silent' trace flag when first argument is 'verbose'
+    and add it when it is 'silent':</p>
+    <code type="none"><![CDATA[
+[{'$1',
+  [{'==',{hd, '$1'},verbose}],
+  [{trace, [silent],[]}]},
+ {'$1',
+  [{'==',{hd, '$1'},silent}],
+  [{trace, [],[silent]}]}]
+    ]]></code>
+    <p>Add return_trace message if function is of arity 3:</p>
+    <code type="none"><![CDATA[
+[{'$1',
+  [{'==',{length, '$1'},3}],
+  [{return_trace}]},
+ {'_',[],[]}]
+    ]]></code>
+    <p>Only generate trace message if function is of arity 3 and first argument is 'trace':</p>
+    <code type="none"><![CDATA[
+[{['trace','$2','$3'],
+  [],
+  []},
+ {'_',[],[]}]
+    ]]></code>
+  </section>
 </chapter>