From 031e4e19120af3e40fcc937bebb4cc45b59f5b87 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson
Date: Wed, 11 May 2016 19:08:49 +0200
Subject: erts: Fix confusion among match spec examples
Tracing and ETS examples were not separated correctly
under the corresponding headings.
---
erts/doc/src/match_spec.xml | 75 +++++++++++++++++++++++----------------------
1 file changed, 38 insertions(+), 37 deletions(-)
(limited to 'erts/doc')
diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml
index 3944f24f84..ca73d78b8d 100644
--- a/erts/doc/src/match_spec.xml
+++ b/erts/doc/src/match_spec.xml
@@ -528,7 +528,7 @@
- ETS Examples
+ Tracing Examples
Match an argument list of three where the first and third arguments
are equal:
has to be a proper list.
- 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.
-
- Match all objects in an ets table with arity > 1 and the first
- element is 'gandalf', return element 2.
- =',{size, '$1'},2}],
- [{element,2,'$1'}]}]
- ]]>
- In the above example, if the first element had been the key,
- it's much more efficient to match that key in the
- part than in the part. The search space of
- the tables is restricted with regards to the so
- that only objects with the matching key are searched.
-
- Match tuples of 3 elements where the second element is either
- 'merry' or 'pippin', return the whole objects.
-
- The function can be useful for testing
- complicated ets matches.
-
-
- Tracing Examples
Only generate trace message if trace control word is set to 1:
+
+
+ ETS Examples
+ 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.
+
+ Match all objects in an ets table with arity > 1 and the first
+ element is 'gandalf', return element 2.
+ =',{size, '$1'},2}],
+ [{element,2,'$1'}]}]
+ ]]>
+ In the above example, if the first element had been the key,
+ it's much more efficient to match that key in the
+ part than in the part. The search space of
+ the tables is restricted with regards to the so
+ that only objects with the matching key are searched.
+
+ Match tuples of 3 elements where the second element is either
+ 'merry' or 'pippin', return the whole objects.
+
+ The function can be useful for testing
+ complicated ets matches.
+
--
cgit v1.2.3
From 46f08788d88e61f41f34f775314444191ebe3b41 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson
Date: Thu, 12 May 2016 18:13:20 +0200
Subject: erts: Add send/receive trace to match spec user guide
Introduce section/terminology "Match target".
---
erts/doc/src/match_spec.xml | 74 +++++++++++++++++++++++++++++++++------------
1 file changed, 54 insertions(+), 20 deletions(-)
(limited to 'erts/doc')
diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml
index ca73d78b8d..7be3d15de6 100644
--- a/erts/doc/src/match_spec.xml
+++ b/erts/doc/src/match_spec.xml
@@ -33,21 +33,15 @@
match_spec.xml
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
- 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
+ erlang:trace_pattern/3
+ or to search for objects in an ETS table with for example
+ ets:select/2.
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.
- Match specifications are given to the BIF to
- execute matching of function arguments as well as to define some actions
- to be taken when the match succeeds (the part). Match
- specifications can also be used in ETS, to specify objects to be
- returned from an 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.
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.
+
+
+ Match target
+ 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.
+
+
+ Context |
+ Type |
+ Match target |
+ Description |
+
+
+ ETS |
+ |
+ {Key, Value1, Value2, ...} |
+ A table object |
+
+
+ Trace |
+ call |
+ [Arg1, Arg2, ...] |
+ Function arguments |
+
+
+ Trace |
+ send |
+ [Receiver, Message] |
+ Receiving process/port and message term |
+
+
+ Trace |
+ 'receive' |
+ [Node, Sender, Message] |
+ Sending node, process/port and message term |
+
+ Match target depending on context
+
+
+
Variables and literals
Variables take the form ']]> where
@@ -396,10 +435,8 @@
parts, only variables bound previously may
be used. As a special case, in the
parts, the variable
- expands to the whole expression which matched the
- (i.e., the whole parameter list to the possibly
- traced function or the whole matching object in the ets table)
- and the variable expands to a list
+ expands to the whole match target
+ term and the variable expands to a list
of the values of all bound variables in order
(i.e. ).
@@ -480,8 +517,8 @@
For each tuple in the list and while no
match has succeeded:
- - Match the part against the arguments to the
- function,
+
- Match the part against the
+ match target term,
binding the ']]> variables (much like in
).
If the cannot match the arguments, the match fails.
@@ -522,9 +559,6 @@
term. The 's are executed as in an imperative
language, i.e. for their side effects. Functions with side effects
are also allowed when tracing.
-
In ETS the match head is a (or a single match
- variable) while it is a list (or a single match variable) when
- tracing.