<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>2006</year><year>2009</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
</legalnotice>
<title>inviso_rt_meta</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
</header>
<module>inviso_rt_meta</module>
<modulesummary>Direct API to the Inviso Runtime Component's meta tracer</modulesummary>
<description>
<p>This module provides a direct API to the inviso meta tracer. These functions are only meant to be used in meta tracing <c>CallFunc</c> and <c>RemoveFunc</c>.</p>
<p>It can sometimes be necessary to manipulate meta match-patterns from <c>CallFunc</c>s and <c>RemoveFunc</c>s. The problem then is that call-funcs and remove-funcs are meta trace call-backs executed inside the inviso meta tracer's context. Hence making calls to the regular API's manipulating meta trace-patterns will hang the inviso meta tracer!.</p>
<p>To remedy this problem, a number of useful tpm-functions are available in this API. It must be understood that their actions are local to the Erlang node where they are called.</p>
</description>
<funcs>
<func>
<name>tpm_ms(Mod,Func,Arity,MSname,MS) -> {ok,0} | {ok,1} | {error,not_initiated}</name>
<fsummary>Adds a list of match-specs, associated with the name <c>MSname</c>, to <c>Mod:Func/Arity</c>.</fsummary>
<desc>
<p>See inviso:tpm_ms/6 for details. Note that this function only effects meta trace-patterns on the Erlang node where the function is called. This also implies that only the local inviso meta tracer's name-database is updated with <c>MSname</c>.</p>
</desc>
</func>
<func>
<name>tpm_ms_tracer(Mod,Func,Arity,MSname,MS) -> {ok,0} | {ok,1} | {error,not_initiated}</name>
<fsummary>As tpm_ms_tracer/5 but also adds a <c>{tracer,Tracer}</c>trace flag to the enable-list of every <c>trace</c>in <c>MS</c>.</fsummary>
<desc>
<p>See inviso:tpm_ms_ms/6 for details. Note that this function only effects meta trace-patterns on the Erlang node where the function is called. This also implies that only the local inviso meta tracer's name-database is updated with <c>MSname</c>.</p>
</desc>
</func>
<func>
<name>list_tpm_ms(Mod,Func,Arity) -> [MSname]</name>
<fsummary>Returns a list of <c>MSname</c>.</fsummary>
<desc>
<p>Returns a list of all <c>MSname</c> in use for <c>Mod:Func/Arity</c>. This can be useful instead of having to have an own-implemented database over currently in use meta match-functions for a particular function.</p>
</desc>
</func>
<func>
<name>ctpm_ms(Mod,Func,Arity,MSname) -> ok</name>
<fsummary>Removes the list of match-specs associated with the <c>MSname</c>from the meta trace-pattern of <c>Mod:Func/Arity</c>.</fsummary>
<desc>
<p>See inviso:ctpm_ms/5 for details. Note that this function only effects meta trace-patterns on the Erlang node where the function is called. This also implies that only the local inviso meta tracer's name-database is updated with <c>MSname</c>.</p>
</desc>
</func>
<func>
<name>get_tracer() -> Tracer</name>
<fsummary>Returns the pid or port acting as regular tracer.</fsummary>
<type>
<v>Tracer = pid() | port()</v>
</type>
<desc>
<p>Returns the pid or port acting as the receiver of regular trace messages. This is useful if it is necessary to manipulate meta trace-patterns by hand (using <c>erlang:trace_pattern/3</c>) and the <c>{tracer,Tracer}</c> must be used in one of the match-function bodies.</p>
</desc>
</func>
</funcs>
</erlref>
