macula_request behaviour (macula v10.1.1)
View SourceBehaviour 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()).Direct-dial
start_link/6,7 routes through the pool's existing links — first success across whichever are healthy, the same gossip-propagated routing call/5 always used. start_link_direct/6,7 is the direct-dial counterpart: it resolves the procedure's procedure_advertisement from the DHT (published by macula_response:advertise_direct/6 on the provider side), resolves that record's serving_station to a dialable endpoint via the station's own station_endpoint record (every macula-station publishes its own automatically), and calls there in one hop via macula:call_station/6 — instead of depending on advertise-gossip having propagated a route between arbitrary stations. Requires the provider to have advertised via advertise_direct/6, not plain advertise/5 — a plain advertise publishes no discoverable record.
Summary
Functions
Cancel an in-flight request. Publishes rpc.completed_v1 with outcome => cancelled if no reply had arrived yet.
Start a request. Calls Procedure on (Pool, Realm) with Payload, timing out after TimeoutMs; Args is passed to Module:init/1.
As start_link/6, with Args passed to Module:init/1.
As start_link/6, but resolves and dials the serving station directly instead of routing through the pool's existing links. See the "Direct-dial" section above.
As start_link_direct/6, with Args passed to Module:init/1.
As start_link_direct/7, with Opts forwarded to macula_direct_dial:call/6 — e.g. verify_cert_chain => {RealmCaPem, Org} (Slice 7c Direction B; managed realms only. See macula_direct_dial's module doc, "Trust model").
Callbacks
Functions
-spec cancel(pid()) -> ok.
Cancel an in-flight request. Publishes rpc.completed_v1 with outcome => cancelled if no reply had arrived yet.
-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.
-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.
-spec start_link_direct(module(), macula:pool(), macula:realm(), macula:procedure(), term(), pos_integer()) -> {ok, pid()} | {error, term()}.
As start_link/6, but resolves and dials the serving station directly instead of routing through the pool's existing links. See the "Direct-dial" section above.
-spec start_link_direct(module(), macula:pool(), macula:realm(), macula:procedure(), term(), pos_integer(), term()) -> {ok, pid()} | {error, term()}.
As start_link_direct/6, with Args passed to Module:init/1.
-spec start_link_direct(module(), macula:pool(), macula:realm(), macula:procedure(), term(), pos_integer(), term(), map()) -> {ok, pid()} | {error, term()}.
As start_link_direct/7, with Opts forwarded to macula_direct_dial:call/6 — e.g. verify_cert_chain => {RealmCaPem, Org} (Slice 7c Direction B; managed realms only. See macula_direct_dial's module doc, "Trust model").