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(-)
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.