%%
%% %CopyrightBegin%
%%
%% Copyright Ericsson AB 2004-2009. All Rights Reserved.
%%
%% 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.
%%
%% %CopyrightEnd%
%%
%%% @doc Common Test specific layer on Erlang/OTP rpc.
-module(ct_rpc).
%%% API
-export([app_node/2, app_node/3, app_node/4,
call/4, call/5, call/6, cast/4, cast/5]).
%%%=========================================================================
%%% API
%%%=========================================================================
%%% @spec app_node(App, Candidates) -> NodeName
%%%
%%% App = atom()
%%% Candidates = [NodeName]
%%% NodeName = atom()
%%%
%%% @doc From a set of candidate nodes determines which of them is
%%% running the application App. If none of the candidate nodes
%%% is running the application the function will make the test case
%%% calling this function fail. This function is the same as calling
%%% <code>app_node(App, Candidates, true)</code>.
%%%
app_node(App, Candidates) ->
app_node(App, Candidates, true, []).
%%% @spec app_node(App, Candidates, FailOnBadRPC) -> NodeName
%%%
%%% App = atom()
%%% Candidates = [NodeName]
%%% NodeName = atom()
%%% FailOnBadRPC = true | false
%%%
%%% @doc Same as <code>app_node/2</code> only the <code>FailOnBadRPC</code>
%%% argument will determine if the search for a candidate node should
%%% stop or not if <code>badrpc</code> is received at some point.
%%%
app_node(App, Candidates, FailOnBadRPC) ->
app_node(App, Candidates, FailOnBadRPC, []).
%%% @spec app_node(App, Candidates, FailOnBadRPC, Cookie) -> NodeName
%%%
%%% App = atom()
%%% Candidates = [NodeName]
%%% NodeName = atom()
%%% FailOnBadRPC = true | false
%%% Cookie = atom()
%%%
%%% @doc Same as <code>app_node/2</code> only the <code>FailOnBadRPC</code>
%%% argument will determine if the search for a candidate node should
%%% stop or not if <code>badrpc</code> is received at some point.
%%% The cookie on the client node will be set to <code>Cookie</code>
%%% for this rpc operation (use to match the server node cookie).
%%%
app_node(App, [], _, _) ->
ct:fail({application_not_running, App});
%% Variable _Candidates is a workaround for the strange edoc behavior
%% of creating the spec: app_node(App, Nodes::Candidates) -> NodeName
%% if it does not exist.
app_node(App, _Candidates = [CandidateNode | Nodes], FailOnBadRPC, Cookie) ->
Cookie0 = set_the_cookie(Cookie),
Result = rpc:call(CandidateNode, application, which_applications, []),
set_the_cookie(Cookie0),
case Result of
{badrpc,Reason} when FailOnBadRPC == true ->
ct:fail({Reason,CandidateNode});
{badrpc,_} when FailOnBadRPC == false ->
app_node(App, Nodes, FailOnBadRPC);
Apps ->
case lists:keysearch(App, 1, Apps) of
{value, _} ->
CandidateNode;
_ ->
app_node(App, Nodes, FailOnBadRPC)
end
end.
%%% @spec call(Node, Module, Function, Args) -> term() | {badrpc, Reason}
%%%
%%% @doc Same as call(Node, Module, Function, Args, infinity)
%%%
call(Node, Module, Function, Args) ->
call(Node, Module, Function, Args, infinity, []).
%%% @spec call(Node, Module, Function, Args, TimeOut) ->
%%% term() | {badrpc, Reason}
%%% Node = NodeName | {Fun, FunArgs}
%%% Fun = fun()
%%% FunArgs = term()
%%% NodeName = atom()
%%% Module = atom()
%%% Function = atom()
%%% Args = [term()]
%%% Reason = timeout | term()
%%%
%%% @doc Evaluates apply(Module, Function, Args) on the node Node.
%%% Returns whatever Function returns or {badrpc, Reason} if the
%%% remote procedure call fails. If Node is {Fun, FunArgs} applying
%%% Fun to FunArgs should return a node name.
call(Node, Module, Function, Args, TimeOut) ->
call(Node, Module, Function, Args, TimeOut, []).
%%% @spec call(Node, Module, Function, Args, TimeOut, Cookie) ->
%%% term() | {badrpc, Reason}
%%% Node = NodeName | {Fun, FunArgs}
%%% Fun = fun()
%%% FunArgs = term()
%%% NodeName = atom()
%%% Module = atom()
%%% Function = atom()
%%% Args = [term()]
%%% Reason = timeout | term()
%%% Cookie = atom()
%%%
%%% @doc Evaluates apply(Module, Function, Args) on the node Node.
%%% Returns whatever Function returns or {badrpc, Reason} if the
%%% remote procedure call fails. If Node is {Fun, FunArgs} applying
%%% Fun to FunArgs should return a node name.
%%% The cookie on the client node will be set to <code>Cookie</code>
%%% for this rpc operation (use to match the server node cookie).
call({Fun, FunArgs}, Module, Function, Args, TimeOut, Cookie) ->
Node = Fun(FunArgs),
call(Node, Module, Function, Args, TimeOut, Cookie);
call(Node, Module, Function, Args, TimeOut, Cookie) when is_atom(Node) ->
Cookie0 = set_the_cookie(Cookie),
Result = rpc:call(Node, Module, Function, Args, TimeOut),
set_the_cookie(Cookie0),
Result.
%%% @spec cast(Node, Module, Function, Args) -> ok
%%% Node = NodeName | {Fun, FunArgs}
%%% Fun = fun()
%%% FunArgs = term()
%%% NodeName = atom()
%%% Module = atom()
%%% Function = atom()
%%% Args = [term()]
%%% Reason = timeout | term()
%%%
%%% @doc Evaluates apply(Module, Function, Args) on the node Node.
%%% No response is delivered and the process which makes the call is
%%% not suspended until the evaluation is compleated as in the case of
%%% call/[3,4]. If Node is {Fun, FunArgs} applying
%%% Fun to FunArgs should return a node name.
cast(Node, Module, Function, Args) ->
cast(Node, Module, Function, Args, []).
%%% @spec cast(Node, Module, Function, Args, Cookie) -> ok
%%% Node = NodeName | {Fun, FunArgs}
%%% Fun = fun()
%%% FunArgs = term()
%%% NodeName = atom()
%%% Module = atom()
%%% Function = atom()
%%% Args = [term()]
%%% Reason = timeout | term()
%%% Cookie = atom()
%%%
%%% @doc Evaluates apply(Module, Function, Args) on the node Node.
%%% No response is delivered and the process which makes the call is
%%% not suspended until the evaluation is compleated as in the case of
%%% call/[3,4]. If Node is {Fun, FunArgs} applying
%%% Fun to FunArgs should return a node name.
%%% The cookie on the client node will be set to <code>Cookie</code>
%%% for this rpc operation (use to match the server node cookie).
cast({Fun, FunArgs}, Module, Function, Args, Cookie) ->
Node = Fun(FunArgs),
cast(Node, Module, Function, Args, Cookie);
cast(Node, Module, Function, Args, Cookie) when is_atom(Node) ->
Cookie0 = set_the_cookie(Cookie),
true = rpc:cast(Node, Module, Function, Args),
set_the_cookie(Cookie0),
ok.
%%%---------- Internal -----------
%%% @hidden
set_the_cookie([]) ->
[];
set_the_cookie(Cookie) ->
Cookie0 = erlang:get_cookie(),
erlang:set_cookie(node(),Cookie),
Cookie0.
