path: root/lib/inviso/src/inviso_tool_lib.erl

% ``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 via the world wide web 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.
%% 
%% The Initial Developer of the Original Code is Ericsson Utvecklings AB.
%% Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings
%% AB. All Rights Reserved.''
%% 
%%     $Id$
%%
%% Description:
%% Support module to the inviso tool.
%%
%% Authors:
%% Lennart Öhman, [email protected]
%% -----------------------------------------------------------------------------

-module(inviso_tool_lib).

%% -----------------------------------------------------------------------------
%% Exported library APIs
%% -----------------------------------------------------------------------------
-export([inviso_cmd/3,expand_module_names/3,make_patterns/7,std_tdg/2]).
-export([mk_tdg_args/2,mk_complete_tdg_args/2,get_datetime_from_tdg_args/1]).
-export([debug/3]).

%% -----------------------------------------------------------------------------
%% Constants.
%% -----------------------------------------------------------------------------
-define(DBG_OFF,off).                        % No internal debug indicator.


%% =============================================================================
%% Functions for inviso_cmd
%% =============================================================================

%% Help function which executes a trace control call. The reason for having a special
%% function is that we either want to do rpc if the trace control component is
%% located on another Erlang node than this one. Or call trace_c directly if
%% it actually is on this node.
%% Returns whatever the inviso function returns. In case of badrpc it is wrapped
%% in an error-tuple.
inviso_cmd(NodeName,Func,Args) ->
    case node() of
	NodeName ->                          % Control component on this node.
	    apply(inviso,Func,Args);
	_ ->                                 % On other node, must do RPC.
	    case rpc:call(NodeName,inviso,Func,Args) of
		{badrpc,Reason} ->
		    {error,{badrpc,Reason}};
		Result ->
		    Result
	    end
    end.
%% -----------------------------------------------------------------------------


%% =============================================================================
%% Functions for expand_module_names
%% =============================================================================

%% Help function which expands the module name depending on how it is expressed.
%% Setting Nodes to 'void' makes it non-distributed, expanding only here.
%% The following special cases are handled:
%% '_'  =All modules, no expansion into individual module names. Instead
%%       it is intended to use the '_' mechanism in the trace_pattern BIF.
%%       Can therefore not be combined with a directory regexp.
%% "*"  =Is translated into ".*".
%% "abc"=Means ".*abc.*". Can only be used for module or directory names
%%       containing upper or lowercase, digits and a slash.
%% Returns {multinode_expansion,NodeModules},
%%         {singlenode_expansion,Modules},
%%         'module', 'wildcard' or {error,Reason},
%% To limit the places where expansion is done, the option {expand_only_at,Node}
%% can be provided in the Opts list.
%% In the non-distributed case the singlenode_expansion will be returned.
expand_module_names(_Nodes,Mod={_,'_'},_) ->
    {error,{faulty_regexp_combination,Mod}};
expand_module_names(Nodes,{DirStr,ModStr},Opts) when is_list(DirStr), is_list(ModStr) ->
    case expand_module_names_special_regexp(DirStr) of
	{ok,NewDirStr} ->
	    case expand_module_names_special_regexp(ModStr) of
		{ok,NewModStr} ->
		    expand_module_names_2(Nodes,NewDirStr,NewModStr,Opts);
		{error,_Reason} ->
		    {error,{faulty_regexp,ModStr}}
	    end;
	{error,_Reason} ->
	    {error,{faulty_regexp,DirStr}}
    end;
expand_module_names(_,'_',_Opts) ->          % If we want to trace all modules
    wildcard;                                % we shall not expand it.
expand_module_names(_Nodes,Mod,_Opts) when is_atom(Mod) ->
    module;                                  % If it is an atom, no expansion.
expand_module_names(Nodes,"*",Opts) ->       % Treat this as a reg.exp.
    expand_module_names(Nodes,".*",Opts);
expand_module_names(Nodes,ModStr,Opts) when is_list(ModStr) ->
    case expand_module_names_special_regexp(ModStr) of
	{ok,NewModStr} ->
	    expand_module_names_2(Nodes,NewModStr,Opts);
	{error,_Reason} ->
	    {error,{faulty_regexp,ModStr}}
    end.

expand_module_names_2(void,ModStr,Opts) ->   % Non-distributed case.
    {singlenode_expansion,inviso_rt_lib:expand_regexp(ModStr,Opts)};
expand_module_names_2(Nodes,ModStr,Opts) ->
    case get_expand_regexp_at_opts(Opts) of
	{ok,Node} ->                         % Expansion only at this node.
	    case inviso_rt_lib:expand_regexp([Node],ModStr,Opts) of
		[{Node,Modules}] when is_list(Modules) ->
		    {singlenode_expansion,Modules};
		[{Node,_}] ->                % Most likely badrpc.
		    {error,{faulty_node,Node}}
	    end;
	false ->                             % Expand on all nodes.
	    Result=inviso_rt_lib:expand_regexp(Nodes,ModStr,Opts),
	    {multinode_expansion,Result}
    end.
expand_module_names_2(void,DirStr,ModStr,Opts) -> % Non-distributed case.
    {singlenode_expansion,inviso_rt_lib:expand_regexp(DirStr,ModStr,Opts)};
expand_module_names_2(Nodes,DirStr,ModStr,Opts) ->
    case get_expand_regexp_at_opts(Opts) of
	{ok,Node} ->                         % Expansion only at this node.
	    case inviso_rt_lib:expand_regexp([Node],DirStr,ModStr,Opts) of
		[{Node,Modules}] when is_list(Modules) ->
		    {singlenode_expansion,Modules};
		[{Node,_}] ->                % Most likely badrpc.
		    {error,{faulty_node,Node}}
	    end;
	false ->                             % Expand on all nodes.
	    Result=inviso_rt_lib:expand_regexp(Nodes,DirStr,ModStr,Opts),
	    {multinode_expansion,Result}
    end.

%% Help function which converts a special regexp into a proper one. With
%% special regexps we mean e.g:"abc" which is supposed to mean ".*abc.*".
%% Always returns a regexp or {error,Reason}. 
expand_module_names_special_regexp(Str) ->
    StrLen=length(Str),
    case re:run(Str,"[0-9a-zA-Z_/]*") of
	{match,[{0,StrLen}]} ->	             % Ok, it is the special case.
	    {ok,".*"++Str++".*"};            % Convert it to a proper regexp.
	{match,_} ->
	    {ok,Str};                        % Keep it and hope it is a regexp.
	nomatch ->
	    {ok,Str};                        % Keep it and hope it is a regexp.
	{error,Reason} ->                    % Can't continue with this!
	    {error,Reason}
    end.
%% -----------------------------------------------------------------------------


%% =============================================================================
%% Functions for make_pattern.
%% =============================================================================

-define(DEPTH,3).                            % Max recursive safety catch depth.

%% Help function that creates trace-patterns for each module in the list.
%% It can handle both lists of modules or lists of nodes and modules.
%% It will also in the process apply safety catches, if such are not disabled,
%% in order to prevent certain patterns to form.
%% The safety catch function is supposed to return either 'ok' or {new,NewTracePattern}.
%% Where the NewTracePattern is a list of zero or more {M,F,Arity,MS}. The
%% NewTracePatter is then the replacement for the tried trace-pattern.
%% Note that the new trace-pattern(s) are also tried against all safety catches.
%% This can possibly result in even replacements of the replacements. There is
%% a depth meter to prevent the safety catch mechanism from circularly expanding
%% trace patterns for ever.
%% Returns a list of [{Node,PatternList},...] or [Pattern,...].
%% The latter is used when the modules have been expanded on a single node.
make_patterns(Catches,Opts,Dbg,NodeModsOrMods,F,A,MS) ->
    OwnArg=get_ownarg_opts(Opts),
    case get_disable_safety_opts(Opts) of
	true ->                              % Do not use the safety catches.
	    make_patterns_2(void,OwnArg,Dbg,NodeModsOrMods,F,A,MS);
	false ->
	    make_patterns_2(Catches,OwnArg,Dbg,NodeModsOrMods,F,A,MS)
    end.
	    
make_patterns_2(Catches,OwnArg,Dbg,[{Node,Mods}|Rest],F,A,MS) when is_list(Mods) ->
    TPs=make_patterns_3(Catches,OwnArg,Dbg,Mods,F,A,MS,[]),
    [{Node,join_patterns(TPs)}|make_patterns_2(Catches,OwnArg,Dbg,Rest,F,A,MS)];
make_patterns_2(Catches,OwnArg,Dbg,[{_Node,_}|Rest],F,A,MS) -> % badrpc!?
    make_patterns_2(Catches,OwnArg,Dbg,Rest,F,A,MS);
make_patterns_2(Catches,OwnArg,Dbg,Modules,F,A,MS) when is_list(Modules) ->
    TPs=make_patterns_3(Catches,OwnArg,Dbg,Modules,F,A,MS,[]),
    join_patterns(TPs);
make_patterns_2(_,_,_,[],_,_,_) ->
    [].

make_patterns_3(void,OwnArg,Dbg,[M|Rest],F,A,MS,Result) -> % S-catches not used!
    make_patterns_3(void,OwnArg,Dbg,Rest,F,A,MS,[{M,F,A,MS}|Result]);
make_patterns_3(Catches,OwnArg,Dbg,[M|Rest],F,A,MS,Result) ->
    NewTPs=try_safety_catches(Catches,OwnArg,[{M,F,A,MS}],Dbg,[],?DEPTH),
    make_patterns_3(Catches,OwnArg,Dbg,Rest,F,A,MS,[NewTPs|Result]);
make_patterns_3(_,_,_,[],_,_,_,Result) ->
    lists:flatten(Result).

try_safety_catches(_Catches,_OwnArg,TPs,Dbg,_Accum,0) -> % Max depth here!
    debug(max_catch_depth,Dbg,[TPs]),
    TPs;                                     % Just return them unchanged.
try_safety_catches(Catches,OwnArg,[TP={M,F,A,MS}|Rest],Dbg,Accum,Depth) ->
    case try_safety_catch(Catches,OwnArg,M,F,A,MS,Dbg) of
	ok ->                                % This pattern is safe!
	    try_safety_catches(Catches,OwnArg,Rest,Dbg,[TP|Accum],?DEPTH);
	{new,NewTPs} ->                      % Then we must try them too!
	    NewTPs2=try_safety_catches(Catches,OwnArg,NewTPs,Dbg,[],Depth-1),
	    try_safety_catches(Catches,OwnArg,Rest,Dbg,[NewTPs2|Accum],?DEPTH)
    end;
try_safety_catches(_,_,[],_,Accum,_) ->
    Accum.

try_safety_catch([{SafetyMod,SafetyFunc}|Rest],OwnArg,M,F,A,MS,Dbg) ->
    case (catch apply(SafetyMod,SafetyFunc,[M,F,A,MS,OwnArg])) of
	ok ->                                % This catch has no oppinion about it.
	    try_safety_catch(Rest,OwnArg,M,F,A,MS,Dbg); % Continue with the next.
	{new,NewTPs} ->                      % Replace it with this or these new.
	    debug(safety_catch,Dbg,[new,{SafetyMod,SafetyFunc},M,F,A,MS,NewTPs]),
	    {new,NewTPs};                    % and stop trying safety cathes.
	{'EXIT',Reason} ->                   % Something wrong with the safety catch.
	    debug(safety_catch,Dbg,['EXIT',{SafetyMod,SafetyFunc},M,F,A,MS,Reason]),
	    try_safety_catch(Rest,OwnArg,M,F,A,MS,Dbg) % Skip it and go on.
    end;
try_safety_catch([],_,_,_,_,_,_) ->
    ok.                                      % Since it passed all, it is safe!
%% -----------------------------------------------------------------------------

%% Help function that joins patterns together. This is necessary since you can
%% only set the pattern once for a module-function-arity. This function can not
%% remove conflicting match-spec "commands". Match-specs will simply be concatenated.
%% Returns a list of patterns where each mod-func-arity is unique.
join_patterns(Patterns) ->
    join_patterns_2(Patterns,[]).

join_patterns_2([{M,F,Arity,MS}|Rest],Result) ->
    case join_patterns_is_already_done(M,F,Arity,Result) of
	false ->                             % No we have not collapsed this one.
	    case join_patterns_3(M,F,Arity,Rest) of
		[] ->                        % No this combination is unique.
		    join_patterns_2(Rest,[{M,F,Arity,MS}|Result]);
		MSs ->                       % We got a list of all other TPs.
		    join_patterns_2(Rest,[{M,F,Arity,MS++MSs}|Result])
	    end;
	true ->                              % We already joined this M-F-Arity.
	    join_patterns_2(Rest,Result)     % Simply skip it, already done.
    end;
join_patterns_2([],Result) ->
    Result.                                  % Reversed but does not matter!

%% Help function checking if we have already built a trace-pattern for
%% this M-F-Arity. If so, the found M-F-Arity is already handled.
join_patterns_is_already_done(M,F,Arity,[{M,F,Arity,_}|_]) ->
    true;
join_patterns_is_already_done(M,F,Arity,[_|Rest]) ->
    join_patterns_is_already_done(M,F,Arity,Rest);
join_patterns_is_already_done(_,_,_,[]) ->
    false.

%% Help function which simply concatenates all match-specs for this
%% M-F-Arity.
join_patterns_3(M,F,Arity,[{M,F,Arity,MS}|Rest]) ->
    [MS|join_patterns_3(M,F,Arity,Rest)];
join_patterns_3(M,F,Arity,[_|Rest]) ->
    join_patterns_3(M,F,Arity,Rest);
join_patterns_3(_,_,_,[]) ->
    [].
%% -----------------------------------------------------------------------------


%% =============================================================================
%% Function for tracer data creation.
%% =============================================================================

-define(I2L(Arg),integer_to_list(Arg)).

%% The inviso_tool uses a tracer-data generator function to create the tracer_data
%% specification for each node that shall participate in tracing controlled
%% through the inviso-tool. If no own tracer data generator function is specified,
%% this function is used.
std_tdg(Node,{{Y,Mo,D},{H,Mi,S}}) ->
    NameStr=atom_to_list(Node)++"_"++?I2L(Y)++"-"++?I2L(Mo)++"-"++?I2L(D)++"_"++
	?I2L(H)++"-"++?I2L(Mi)++"-"++?I2L(S),
    LogTD={file,NameStr++".log"},
    TiTD={file,NameStr++".ti"},
    [{trace,LogTD},{ti,TiTD}].
%% ------------------------------------------------------------------------------

%% mk_tdg_args(DateTime,Args)=TDGargs
%%   DateTime={Date,Time}
%%     Date=tuple(),
%%     Time=tuple(),
%%   Args=list()
%%   TDGargs=list(),
%% Creates the TDGargs list used when calling functions making the CompleteTDGargs.
mk_tdg_args(DateTime,Args) ->
    [DateTime|Args].
%% ------------------------------------------------------------------------------

%% mk_complete_tdg_args(Node,TDGargs)=CompleteTDGargs
%% Returns the list of all arguments a tracer data generator function must accept.
mk_complete_tdg_args(Node,TDGargs) ->
    [Node|TDGargs].
%% ------------------------------------------------------------------------------

%% get_datetime_from_tdg_args(TDGargs)=DateTime
%% Function returning the DateTime tuple in a TDGargs list.
get_datetime_from_tdg_args([DateTime|_]) ->
    DateTime.
%% ------------------------------------------------------------------------------


%% =============================================================================
%% Various help functions.
%% =============================================================================

%% -----------------------------------------------------------------------------
%% Functions handling set trace-pattern options.
%% -----------------------------------------------------------------------------

%% Gets additional arguments given to various configurable functions.
%% Returns a list.
get_ownarg_opts(Opts) ->
    case lists:keysearch(arg,1,Opts) of
	{value,{_,OwnArg}} when is_list(OwnArg) ->
	    OwnArg;
	{value,{_,OwnArg}} ->
	    [OwnArg];
	false ->
	    []
    end.
%% -----------------------------------------------------------------------------

get_disable_safety_opts(Opts) ->
    case lists:member(disable_safety,Opts) of
	true ->
	    true;
	false ->
	    false
    end.
%% -----------------------------------------------------------------------------

get_expand_regexp_at_opts(Opts) ->
    case lists:keysearch(expand_only_at,1,Opts) of
	{value,{_,Node}} when is_atom(Node) ->
	    {ok,Node};
	_ ->
	    false
    end.
%% -----------------------------------------------------------------------------


%% =============================================================================
%% Functions for the internal debugging system.
%% =============================================================================

%% The debug system is meant to provide tracing of inviso tool at different levels.
%%
%% debug(What,Level,Description) -> nothing significant.
%%   What : controls what kind of event. This can both be certain parts of the tool
%%          as well as certain levels (info to catastrophy).
%%   Level: Determines if What shall be printed or not.
%%   Description: this is what happend.
debug(_What,?DBG_OFF,_Description) ->
    true;                                    % Debug is off, no action.
debug(What,On,Description) ->
    debug_2(What,On,Description).

debug_2(What,_,Description) ->
    io:format("INVISO DEBUG:~w, ~p~n",[What,Description]).
%% -----------------------------------------------------------------------------