macula_feeder behaviour (macula v13.2.2)

View Source

Behaviour for supervised content feeders (the share side).

start_link/4,5,6 returns immediately with a pid, shares the bytes from this node (macula:share_content/4, D27: the node keeps and serves what it shares), delivers the root content id to Module:handle_fed/2, and publishes sharing.put_started_v1 / sharing.put_completed_v1 mesh facts around it, including outcome => cancelled when cancel/1 lands before the share resolves. A cancelled share is withdrawn: the root content id is known from the bytes before anything is sent, and it is unshared, so a cancel never leaves content shared behind the caller's back.

This is content sharing, not general-purpose RPC streaming; see macula_streamer / macula_stream_sink for that.

Start options

share and unshare, as macula:share_content/4 and macula:unshare_content/3 (the defaults); share_opts, passed to share (name, org); fact_publish, macula:publish/4 by default. A function of another shape is refused with function_clause, in the caller.

Example

   -module(doc_feeder).
   -behaviour(macula_feeder).
   -export([init/1, handle_fed/2]).
  
   init(Parent) -> {ok, Parent}.
  
   handle_fed(Result, Parent) ->
       Parent ! {fed, Result},
       {stop, normal, Parent}.
   {ok, Pid} = macula_feeder:start_link(doc_feeder, Pool, Realm,
       Bytes, self()).

Summary

Types

start_opts/0

Callbacks

handle_fed/2
init/1

Functions

cancel(Pid)

Cancel an in-flight feed. Publishes sharing.put_completed_v1 with outcome => cancelled and withdraws the share if it had not resolved yet.

start_link(Module, Pool, Realm, Bytes)

Start a feeder sharing Bytes in Realm through Pool.

start_link(Module, Pool, Realm, Bytes, Args)

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

start_link(Module, Pool, Realm, Bytes, Args, Opts)

As start_link/5, with start options (see "Start options" above).

Types

start_opts/0

-type start_opts() ::
          #{share =>
                fun((macula:pool(), macula:realm(), binary(), map()) ->
                        {ok, macula:mcid()} | {error, term()}),
            unshare => fun((macula:pool(), macula:realm(), macula:mcid()) -> ok),
            share_opts => map(),
            fact_publish => macula_lifetime_announcer:publish()}.

Callbacks

handle_fed/2

-callback handle_fed(Result :: {ok, macula:mcid()} | {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 feed. Publishes sharing.put_completed_v1 with outcome => cancelled and withdraws the share if it had not resolved yet.

start_link(Module, Pool, Realm, Bytes)

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

Start a feeder sharing Bytes in Realm through Pool.

start_link(Module, Pool, Realm, Bytes, Args)

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

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

start_link(Module, Pool, Realm, Bytes, Args, Opts)

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

As start_link/5, with start options (see "Start options" above).