A "match specification" (match_spec) is an Erlang term describing a
small "program" that will try to match something. It can be used
to either control tracing with
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
exceptions. An exception (e.g.,
A match_spec used in tracing can be described in this informal grammar:
A match_spec used in ets can be described in this informal grammar:
The different functions allowed in
is_atom, is_float, is_integer, is_list, is_number, is_pid, is_port,
is_reference, is_tuple, is_map, is_binary, is_function: Like the
corresponding guard tests in Erlang, return
is_record: Takes an additional parameter, which SHALL
be the result of
'not': Negates its single argument (anything other
than
'and': Returns
'or': Returns
andalso: Like
orelse: Like
'xor': Only two arguments, of which one has to be true
and the other false to return
abs, element, hd, length, node, round, size, tl, trunc, '+', '-', '*', 'div', 'rem', 'band', 'bor', 'bxor', 'bnot', 'bsl', 'bsr', '>', '>=', '<', '=<', '=:=', '==', '=/=', '/=', self: Work as the corresponding Erlang bif's (or
operators). In case of bad arguments, the result depends on
the context. In the
is_seq_trace: Returns
set_seq_token: Works like
get_seq_token: Works just like
message: Sets an additional message appended to the
trace message sent. One can only set one additional message in
the body; subsequent calls will replace the appended message. As
a special case,
Takes one argument, the message. Returns
return_trace: Causes a
NOTE! If the traced function is tail recursive, this match
spec function destroys that property.
Hence, if a match spec executing this function is used on a
perpetual server process, it may only be active for a limited
time, or the emulator will eventually use all memory in the host
machine and crash. If this match_spec function is inhibited
using the
exception_trace: Same as return_trace,
plus; if the traced function exits due to an exception,
an
process_dump: Returns some textual information about
the current process as a binary. Takes no arguments and is only
allowed in the
enable_trace: With one parameter this function turns
on tracing like the Erlang call
disable_trace: With one parameter this function
disables tracing like the Erlang call
trace: With two parameters this function takes a list
of trace flags to disable as first parameter and a list
of trace flags to enable as second parameter. Logically, the
disable list is applied first, but effectively all changes
are applied atomically. The trace flags
are the same as for
caller:
Returns the calling function as a tuple {Module,
Function, Arity} or the atom
Note that if a "technically built in function" (i.e. a
function not written in Erlang) is traced, the
display: For debugging purposes only; displays the
single argument as an Erlang term on stdout, which is seldom
what is wanted. Returns
The trace control word is a 32-bit unsigned integer intended for generic trace control. The trace control word can be tested and set both from within trace match specifications and with BIFs. This call is only allowed when tracing.
silent:
Takes one argument. If the argument is
This mode can also be activated with the
If the argument is
If the argument is neither
Note that all "function calls" have to be tuples,
even if they take no arguments. The value of
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.
Variables take the form
In the
The execution of the match expression, when the runtime system decides whether a trace message should be sent, goes as follows:
For each tuple in the
ETS match specifications are there to produce a return
value. Usually the
When tracing there is no return value to produce, the
match specification either matches or doesn't. The effect when the
expression matches is a trace message rather then a returned
term. The
Match an argument list of three where the first and third arguments are equal:
Match an argument list of three where the second argument is a number greater than three:
', '$1', 3}],
[]}]
]]>
Match an argument list of three, where the third argument
is a tuple containing argument one and two or a list
beginning with argument one and two (i. e.
The above problem may also be solved like this:
Match two arguments where the first is a tuple beginning with a list which in turn begins with the second argument times two (i. e. [{[4,x],y},2] or [{[8], y, z},4])
Match three arguments. When all three are equal and are numbers, append the process dump to the trace message, else let the trace message be as is, but set the sequential trace token label to 4711.
As can be noted above, the parameter list can be matched
against a single
Only generate trace message if trace control word is set to 1:
Only generate trace message if there is a seq trace token:
Remove 'silent' trace flag when first argument is 'verbose' and add it when it is 'silent':
Add return_trace message if function is of arity 3:
Only generate trace message if function is of arity 3 and first argument is 'trace':
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
Match tuples of 3 elements where the second element is either 'merry' or 'pippin', return the whole objects.
The function