macula_download behaviour (macula v13.3.0)

View Source

Behaviour for supervised content downloads (the get/fetch side).

start_link/4,5,6 returns immediately with a pid, fetches the content from a node that shares it (macula:get_content/4, D27), delivers the outcome to Module:handle_downloaded/2, and publishes sharing.get_started_v1 / sharing.get_completed_v1 mesh facts around the fetch, including outcome => cancelled when cancel/1 lands before the fetch resolves.

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

Start options

fetch, the function the content is fetched with, as macula:get_content/4 (the default); fetch_opts, passed to it (max_bytes, max_chunks, ...); fact_publish, the function the facts are published with, macula:publish/4 by default. A test gives its own functions this way instead of replacing a module. A function of another shape is refused with function_clause, in the caller.

Example

   -module(doc_download).
   -behaviour(macula_download).
   -export([init/1, handle_downloaded/2]).
  
   init(Parent) -> {ok, Parent}.
  
   handle_downloaded(Result, Parent) ->
       Parent ! {downloaded, Result},
       {stop, normal, Parent}.
   {ok, Pid} = macula_download:start_link(doc_download, Pool, Realm,
       MCID, self()).

Summary

Types

start_opts/0

Callbacks

handle_downloaded/2
init/1

Functions

cancel(Pid)

Cancel an in-flight download. Publishes sharing.get_completed_v1 with outcome => cancelled if the fetch had not resolved yet.

start_link(Module, Pool, Realm, MCID)

Start a download of MCID in Realm through Pool.

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

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

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

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

Types

start_opts/0

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

Callbacks

handle_downloaded/2

-callback handle_downloaded(Result :: {ok, binary()} | {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 download. Publishes sharing.get_completed_v1 with outcome => cancelled if the fetch had not resolved yet.

start_link(Module, Pool, Realm, MCID)

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

Start a download of MCID in Realm through Pool.

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

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

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

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

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

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