Merge branch 'sverker/trace-send-receive-matchspec/OTP-13507'

Second merge of this branch to master
with some more docs

3 files changed, 155 insertions, 59 deletions

diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml
index 3944f24f84..7be3d15de6 100644
--- a/erts/doc/src/match_spec.xml
+++ b/erts/doc/src/match_spec.xml
@@ -33,21 +33,15 @@
     <file>match_spec.xml</file>
   </header>
   <p>A "match specification" (match_spec) is an Erlang term describing a
-    small "program" that will try to match something (either the
-    parameters to a function as used in the <c><![CDATA[erlang:trace_pattern/2]]></c>
-    BIF, or the objects in an ETS table.). 
+    small "program" that will try to match something. It can be used
+    to either control tracing with
+    <seealso marker="erlang#trace_pattern/3">erlang:trace_pattern/3</seealso>
+    or to search for objects in an ETS table with for example
+    <seealso marker="stdlib:ets#select/2">ets:select/2</seealso>.
     The match_spec in many ways works like a small function in Erlang, but is
     interpreted/compiled by the Erlang runtime system to something much more
     efficient than calling an Erlang function. The match_spec is also
     very limited compared to the expressiveness of real Erlang functions.</p>
-  <p>Match specifications are given to the BIF <c><![CDATA[erlang:trace_pattern/2]]></c> to
-    execute matching of function arguments as well as to define some actions
-    to be taken when the match succeeds (the <c><![CDATA[MatchBody]]></c> part). Match
-    specifications can also be used in ETS, to specify objects to be
-    returned from an <c><![CDATA[ets:select/2]]></c> call (or other select
-    calls). The semantics and restrictions differ slightly when using
-    match specifications for tracing and in ETS, the differences are
-    defined in a separate paragraph below.</p>
   <p>The most notable difference between a match_spec and an Erlang fun is
     of course the syntax. Match specifications are Erlang terms, not
     Erlang code.  A match_spec also has a somewhat strange concept of
@@ -382,6 +376,51 @@
       the pid() of the current process.</p>
   </section>
 
+  <marker id="match_target"></marker>
+  <section>
+    <title>Match target</title>
+    <p>Each execution of a match specification is done against
+      a match target term. The format and content of the target term
+      depends on the context in which the match is done. The match
+      target for ETS is always a full table tuple. The match target
+      for call trace is always a list of all function arguments. The
+      match target for event trace depends on the event type, see
+      table below.</p>
+      <table>
+      <row>
+        <cell align="left" valign="middle">Context</cell>
+        <cell align="left" valign="middle">Type</cell>
+        <cell align="left" valign="middle">Match target</cell>
+        <cell align="left" valign="middle">Description</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">ETS</cell>
+        <cell align="left" valign="middle"></cell>
+        <cell align="left" valign="middle">{Key, Value1, Value2, ...}</cell>
+        <cell align="left" valign="middle">A table object</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">Trace</cell>
+        <cell align="left" valign="middle">call</cell>
+        <cell align="left" valign="middle">[Arg1, Arg2, ...]</cell>
+        <cell align="left" valign="middle">Function arguments</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">Trace</cell>
+        <cell align="left" valign="middle">send</cell>
+        <cell align="left" valign="middle">[Receiver, Message]</cell>
+        <cell align="left" valign="middle">Receiving process/port and message term</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">Trace</cell>
+        <cell align="left" valign="middle">'receive'</cell>
+        <cell align="left" valign="middle">[Node, Sender, Message]</cell>
+        <cell align="left" valign="middle">Sending node, process/port and message term</cell>
+      </row>
+      <tcaption>Match target depending on context</tcaption>
+      </table>
+  </section>
+
   <section>
     <title>Variables and literals</title>
     <p>Variables take the form <c><![CDATA['$<number>']]></c> where
@@ -396,10 +435,8 @@
       <c><![CDATA[MatchCondition]]></c> parts, only variables bound previously may
       be used. As a special case, in the
       <c><![CDATA[MatchCondition/MatchBody]]></c> parts, the variable <c><![CDATA['$_']]></c>
-      expands to the whole expression which matched the
-      <c><![CDATA[MatchHead]]></c> (i.e., the whole parameter list to the possibly
-      traced function or the whole matching object in the ets table)
-      and the variable <c><![CDATA['$$']]></c> expands to a list
+      expands to the whole <seealso marker="#match_target">match target</seealso>
+      term and the variable <c><![CDATA['$$']]></c> expands to a list
       of the values of all bound variables in order 
       (i.e. <c><![CDATA[['$1','$2', ...]]]></c>).
       </p>
@@ -480,8 +517,8 @@
     <p>For each tuple in the <c><![CDATA[MatchExpression]]></c> list and while no
       match has succeeded:</p>
     <list type="bulleted">
-      <item>Match the <c><![CDATA[MatchHead]]></c> part against the arguments to the
-       function, 
+      <item>Match the <c><![CDATA[MatchHead]]></c> part against the
+       match target term,
        binding the <c><![CDATA['$<number>']]></c> variables (much like in
       <c><![CDATA[ets:match/2]]></c>).
        If the <c><![CDATA[MatchHead]]></c> cannot match the arguments, the match fails.
@@ -522,13 +559,10 @@
       term. The <c><![CDATA[ActionTerm]]></c>'s are executed as in an imperative
       language, i.e. for their side effects. Functions with side effects
       are also allowed when tracing.</p>
-    <p>In ETS the match head is a <c><![CDATA[tuple()]]></c> (or a single match
-      variable) while it is a list (or a single match variable) when
-      tracing.</p>
   </section>
 
   <section>
-    <title>ETS Examples</title>
+    <title>Tracing Examples</title>
     <p>Match an argument list of three where the first and third arguments 
       are equal:</p>
     <code type="none"><![CDATA[
@@ -585,42 +619,6 @@
       parameter list with a single variable is a special case. In all 
       other cases the <c><![CDATA[MatchHead]]></c> has to be a <em>proper</em> list.
       </p>
-    <p>Match all objects in an ets table where the first element is 
-      the atom 'strider' and the tuple arity is 3 and return the whole
-      object.</p>
-    <code type="none"><![CDATA[
-[{{strider,'_','_'},
-  [],
-  ['$_']}]
-    ]]></code>
-    <p>Match all objects in an ets table with arity &gt; 1 and the first 
-      element is 'gandalf', return element 2.</p>
-    <code type="none"><![CDATA[
-[{'$1',
-  [{'==', gandalf, {element, 1, '$1'}},{'>=',{size, '$1'},2}],
-  [{element,2,'$1'}]}]
-    ]]></code>
-    <p>In the above example, if the first element had been the key,
-      it's much more efficient to match that key in the <c><![CDATA[MatchHead]]></c>
-      part than in the <c><![CDATA[MatchConditions]]></c> part. The search space of
-      the tables is restricted with regards to the <c><![CDATA[MatchHead]]></c> so
-      that only objects with the matching key are searched. 
-      </p>
-    <p>Match tuples of 3 elements where the second element is either
-      'merry' or 'pippin', return the whole objects.</p>
-    <code type="none"><![CDATA[
-[{{'_',merry,'_'},
-  [],
-  ['$_']},
- {{'_',pippin,'_'},
-  [],
-  ['$_']}]
-    ]]></code>
-    <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[
 [{'_',
@@ -658,5 +656,42 @@
  {'_',[],[]}]
     ]]></code>
   </section>
+
+  <section>
+    <title>ETS Examples</title>
+    <p>Match all objects in an ets table where the first element is
+      the atom 'strider' and the tuple arity is 3 and return the whole
+      object.</p>
+    <code type="none"><![CDATA[
+[{{strider,'_','_'},
+  [],
+  ['$_']}]
+    ]]></code>
+    <p>Match all objects in an ets table with arity &gt; 1 and the first
+      element is 'gandalf', return element 2.</p>
+    <code type="none"><![CDATA[
+[{'$1',
+  [{'==', gandalf, {element, 1, '$1'}},{'>=',{size, '$1'},2}],
+  [{element,2,'$1'}]}]
+    ]]></code>
+    <p>In the above example, if the first element had been the key,
+      it's much more efficient to match that key in the <c><![CDATA[MatchHead]]></c>
+      part than in the <c><![CDATA[MatchConditions]]></c> part. The search space of
+      the tables is restricted with regards to the <c><![CDATA[MatchHead]]></c> so
+      that only objects with the matching key are searched.
+      </p>
+    <p>Match tuples of 3 elements where the second element is either
+      'merry' or 'pippin', return the whole objects.</p>
+    <code type="none"><![CDATA[
+[{{'_',merry,'_'},
+  [],
+  ['$_']},
+ {{'_',pippin,'_'},
+  [],
+  ['$_']}]
+    ]]></code>
+    <p>The function <c><![CDATA[ets:test_ms/2]]></c> can be useful for testing
+      complicated ets matches.</p>
+  </section>
 </chapter>
 
diff --git a/lib/runtime_tools/doc/src/dbg.xml b/lib/runtime_tools/doc/src/dbg.xml
index 103b8b52e9..49b11ddc3c 100644
--- a/lib/runtime_tools/doc/src/dbg.xml
+++ b/lib/runtime_tools/doc/src/dbg.xml
@@ -439,6 +439,50 @@ Error: fun containing local erlang function calls ('is_atomm' called in guard)\
           global calls (and functions).</p>
       </desc>
     </func>
+
+
+    <func>
+      <name>tpe(Event, MatchSpec) -> {ok, MatchDesc} | {error, term()}</name>
+      <fsummary>Set pattern for traced event</fsummary>
+      <type>
+	<v>Event = send | 'receive'</v>
+        <v>MatchSpec = integer() | Built-inAlias | [] | match_spec()</v>
+	<v>Built-inAlias = x | c | cx</v>
+        <v>MatchDesc = [MatchInfo]</v>
+        <v>MatchInfo = {saved, integer()} | MatchNum</v>
+        <v>MatchNum = {matched, node(), 1} | {matched, node(), 0, RPCError}</v>
+      </type>
+      <desc>
+        <p>This function associates a match specification with trace event
+	  <c>send</c> or <c>'receive'</c>. By default all executed <c>send</c>
+	  and <c>'receive'</c> events are traced if enabled for a process.
+	  A match specification can be used to filter traced events
+	  based on sender, receiver and/or message content.</p>
+        <p>For a description of the <c>match_spec()</c> syntax,
+          please turn to the <em>User's guide</em> part of the online
+          documentation for the runtime system (<em>erts</em>). The
+          chapter <seealso marker="erts:match_spec"><em>Match Specifications in Erlang</em></seealso>
+          explains the general match specification "language".</p>
+	<p>For <c>send</c>, the matching is done on the list <c>[Receiver, Msg]</c>.
+	  <c>Receiver</c> is the process or port identity of the receiver and
+	  <c>Msg</c> is the message term. The pid of the sending process can be
+	  accessed with the guard function <c>self/0</c>.</p>
+	<p>For <c>'receive'</c>, the matching is done on the list <c>[Node, Sender, Msg]</c>.
+	  <c>Node</c> is the node name of the sender. <c>Sender</c> is the
+	  process or port identity of the sender, or the atom
+	  <c>undefined</c> if the sender is not known (which may
+	  be the case for remote senders). <c>Msg</c> is the
+	  message term. The pid of the receiving process can be
+	  accessed with the guard function <c>self/0</c>.</p>
+        <p>All nodes added with <seealso marker="#n-1"><c>n/1</c></seealso> or
+          <seealso marker="#tracer-3"><c>tracer/3</c></seealso> will
+          be affected by this call.</p>
+        <p>The return value is the same as for
+	  <seealso marker="#tp-2"><c>tp/2</c></seealso>. The number of matched
+	  events are never larger than 1 as <c>tpe/2</c> does not
+	  accept any form of wildcards for argument <c>Event</c>.</p>
+      </desc>
+    </func>
     <func>
       <name>ctp()</name>
       <fsummary>Clear call trace pattern for the specified functions</fsummary>
@@ -563,6 +607,22 @@ Error: fun containing local erlang function calls ('is_atomm' called in guard)\
       </desc>
     </func>
     <func>
+      <name>ctpe(Event) -> {ok, MatchDesc} | {error, term()}</name>
+      <fsummary>Clear trace pattern for the specified event</fsummary>
+      <type>
+        <v>Event = send | 'receive'</v>
+        <v>MatchDesc = [MatchNum]</v>
+        <v>MatchNum = {matched, node(), 1} | {matched, node(), 0, RPCError}</v>
+      </type>
+      <desc>
+        <p>This function clears match specifications for the specified
+	  trace event (<c>send</c> or <c>'receive'</c>). It will revert back
+	  to the default behavior of tracing all triggered events.</p>
+        <p>The return value follow the same style as for
+	  <seealso marker="#ctp-1"><c>ctp/1</c></seealso>.</p>
+      </desc>
+    </func>
+    <func>
       <name>ltp() -> ok</name>
       <fsummary>List saved and built-in match specifications on the console.</fsummary>
       <desc>
diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml
index 2d69c201bc..b32638f04d 100644
--- a/lib/stdlib/doc/src/ets.xml
+++ b/lib/stdlib/doc/src/ets.xml
@@ -123,8 +123,9 @@
     <p>Some of the functions uses a <em>match specification</em>,
       match_spec. A brief explanation is given in
       <seealso marker="#select/2">select/2</seealso>. For a detailed
-      description, see the chapter "Match specifications in Erlang" in
-      <em>ERTS User's Guide</em>.</p>
+      description, see chapter
+      <seealso marker="erts:match_spec">Match Specifications in Erlang</seealso>
+      in <em>ERTS User's Guide</em>.</p>
   </section>
 
   <datatypes>