macula_request behaviour (macula v9.2.0)

View Source

Behaviour for supervised RPC requests.

call/5 is a plain blocking call in the caller's own process — there is no addressable pid to cancel it from outside. This is the consumer-side counterpart to macula_response: start_link/6,7 returns immediately with a pid, runs macula:call/5 in a linked worker, delivers the outcome to Module:handle_reply/2, and publishes rpc.sent_v1 / rpc.completed_v1 mesh facts around the request — including outcome => cancelled if the request is cancelled before a reply arrives.

Example

   -module(add_caller).
   -behaviour(macula_request).
   -export([init/1, handle_reply/2]).
  
   init(Parent) -> {ok, Parent}.
  
   handle_reply(Result, Parent) ->
       Parent ! {add_result, Result},
       {stop, normal, Parent}.
   {ok, Pid} = macula_request:start_link(add_caller, Pool, Realm,
       <<"math.add_v1">>, #{a => 2, b => 3}, 30_000, self()).

Summary

Callbacks

handle_reply/2
init/1

Functions

cancel(Pid)

Cancel an in-flight request. Publishes rpc.completed_v1 with outcome => cancelled if no reply had arrived yet.

start_link(Module, Pool, Realm, Procedure, Payload, TimeoutMs)

Start a request. Calls Procedure on (Pool, Realm) with Payload, timing out after TimeoutMs; Args is passed to Module:init/1.

start_link(Module, Pool, Realm, Procedure, Payload, TimeoutMs, Args)

As start_link/6, with Args passed to Module:init/1.

Callbacks

handle_reply/2

-callback handle_reply(Result :: {ok, term()} | {error, term()}, State :: term()) ->
                          {noreply, NewState :: term()} | {stop, Reason :: term(), NewState :: term()}.

init/1

-callback init(Args :: term()) -> {ok, State :: term()} | {stop, Reason :: term()}.

Functions

cancel(Pid)

-spec cancel(pid()) -> ok.

Cancel an in-flight request. Publishes rpc.completed_v1 with outcome => cancelled if no reply had arrived yet.

start_link(Module, Pool, Realm, Procedure, Payload, TimeoutMs)

-spec start_link(module(), macula:pool(), macula:realm(), macula:procedure(), term(), pos_integer()) ->
                    {ok, pid()} | {error, term()}.

Start a request. Calls Procedure on (Pool, Realm) with Payload, timing out after TimeoutMs; Args is passed to Module:init/1.

start_link(Module, Pool, Realm, Procedure, Payload, TimeoutMs, Args)

-spec start_link(module(),
                 macula:pool(),
                 macula:realm(),
                 macula:procedure(),
                 term(),
                 pos_integer(),
                 term()) ->
                    {ok, pid()} | {error, term()}.

As start_link/6, with Args passed to Module:init/1.