%%
%% %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.