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