ct_rpc(3)

💖 NAME 💖

okay bestie, welcome to ct_rpc — it's the Common Test specific layer that sits on top of Erlang/OTP's rpc. yes, that rpc. the glow-up edition 💅

This is page ct_rpc(3) from the Erlang module definition collection, and she's here to make remote calls across your test nodes feel a whole lot less feral.

---

🌸 DESCRIPTION 🌸

ngl, this section is literally just vibes — the original page hands you the section header and then goes straight to the functions. no preamble, no lore, we're diving in. slay.

So like… scroll down, the good stuff is in FUNCTIONS. 🫶

---

✨ FUNCTIONS ✨

app_node/2 🌈

app_node(App, Candidates) -> CandidateNode
    when
        App :: atom(),
        Candidates :: [node()],
        CandidateNode :: node().

So you've got a whole little squad of candidate nodes and you need to know which one is actually running the application App. That's it, that's the job. She looks at your set of candidate nodes and picks the one running App.

BUT — and this is important bestie — if none of your candidate nodes is running App, she makes the test case that called her fail. no soft launch, no "oops", it just fails. 💀

Also she's literally the same as calling app_node(App, Candidates, true). same energy, fr fr.

app_node/3 💜

app_node(App, Candidates, FailOnBadRPC) -> CandidateNode
    when
        App :: atom(),
        Candidates :: [node()],
        FailOnBadRPC :: boolean(),
        CandidateNode :: node().

Same as ct_rpc:app_node/2, except now you get a say in whether the search for a candidate node stops if badrpc gets received at some point. That's what FailOnBadRPC is for. iconic, honestly.

app_node/4 🎀

app_node(App, Candidates, FailOnBadRPC, Cookie) -> CandidateNode
    when
        App :: atom(),
        Candidates :: [node()],
        FailOnBadRPC :: boolean(),
        Cookie :: atom() | [],
        CandidateNode :: node().

Same as ct_rpc:app_node/2, except that argument FailOnBadRPC determines if the search for a candidate node is to stop if badrpc is received at some point. (yes, same sentence as the /3 version, she said what she said 💅)

Extra thing though: the cookie on the client node is set to Cookie for this rpc operation, which is what you use to match the server node cookie. matching cookies = main character energy 🔥

call/5 ⭐

call(Node, Module, Function, Args, TimeOut) ->
        term() | {badrpc, Reason}
        when
            Node :: {Function, Args} | node(),
            Module :: module(),
            Function :: atom(),
            Args :: list(),
            TimeOut :: timeout(),
            Reason :: term().

She evaluates apply(Module, Function, Args) on the node Node. Then you get back either whatever Function returns, or {badrpc, Reason} if the remote procedure call fails. no cap.

And listen — if Node is {Fun, FunArgs}, then applying Fun to FunArgs is what returns a node name. cute little indirection moment 🦋

call/6 🌸

call(Node, Module, Function, Args, TimeOut, Cookie) ->
        term() | {badrpc, Reason}
        when
            Node :: {Function, Args} | node(),
            Module :: module(),
            Function :: atom(),
            Args :: list(),
            TimeOut :: timeout(),
            Cookie :: atom() | [],
            Reason :: term().

She evaluates apply(Module, Function, Args) on the node Node. Returns either whatever Function returns, or {badrpc, Reason} if the remote procedure call fails. And if Node is {Fun, FunArgs}, applying Fun to FunArgs is to return a node name. same as her /5 sister, obsessed.

✨ plus the glow-up: the cookie on the client node is set to Cookie for this rpc operation (used to match the server node cookie). iykyk 🍓

cast/4 🧚

cast(Node, Module, Function, Args) -> ok
    when
        Node :: {Function, Args} | node(),
        Module :: module(),
        Function :: atom(),
        Args :: list().

She evaluates apply(Module, Function, Args) on the node Node — but this is the chill one. No response is delivered, and the process that makes the call is not suspended until the evaluation is completed, unlike what happens in the case of call/3,4. you just yeet it and keep it moving 😌

And yeah, if Node is {Fun, FunArgs}, applying Fun to FunArgs is to return a node name.

cast/5 👑

cast(Node, Module, Function, Args, Cookie) -> ok
    when
        Node :: {Function, Args} | node(),
        Module :: module(),
        Function :: atom(),
        Args :: list(),
        Cookie :: atom() | [].

She evaluates apply(Module, Function, Args) on the node Node. No response is delivered and the process that makes the call is not suspended until the evaluation is completed as in the case of call/3,4. If Node is {Fun, FunArgs}, applying Fun to FunArgs is to return a node name. same as /4, yes bestie, we keep it consistent.

And the little extra: the cookie on the client node is set to Cookie for this rpc operation (used to match the server node cookie). 💖

---

lowkey a note for future you: this whole page is built and owned by Ericsson AB, and it ships as part of common_test version 1.31.1. that's the whole sign-off, muah 💋✨