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

-- cgit v1.2.3