macula_lifetime_announcer (macula v11.4.0)

View Source

Announces a supervised wrapper's start fact and its end fact from a process of its own.

A wrapper, such as macula_stream_sink, calls start/2 once its operation has begun. The announcer monitors the wrapper, publishes the start fact, and waits for the wrapper to hand over its end payload with announce_end/2, which it publishes under the end topic. A wrapper that goes down before it hands over its end, for example because it was killed, has its end fact published for it, with the end fields plus outcome failed and the reason it went down for. Either way exactly one end fact goes out.

An end fact carries its reason's name, from macula_reason_name, and none of the reason's terms; a reason that is more than a name goes to the local log, printed within bounds.

Publishing never fails or ends the wrapper: a publish that raises or returns anything but ok is logged, and the announcer goes on. The publish function must return in bounded time, since the announcer outlives its wrapper for as long as its last publish takes; macula:publish/4 returns within 5.5 seconds. The announcer touches nothing but its publish function, and it ends once it has published the end fact.

Summary

Functions

Hands the announcer the wrapper's end payload, to publish under the end topic. Returns at once; with undefined it does nothing.

With Announce true, starts the announcer of the calling process and returns its pid once it monitors the caller; the announcer then publishes the start fact. With Announce false nothing starts and undefined is returned.

Types

facts/0

-type facts() ::
          #{publish := publish(),
            pool := macula:pool(),
            realm := macula:realm(),
            started := {macula:topic(), map()},
            ended := {macula:topic(), map()}}.

publish/0

-type publish() :: fun((macula:pool(), macula:realm(), macula:topic(), map()) -> term()).

Functions

announce_end(Announcer, Payload)

-spec announce_end(pid() | undefined, map()) -> ok.

Hands the announcer the wrapper's end payload, to publish under the end topic. Returns at once; with undefined it does nothing.

start(_, Facts)

-spec start(boolean(), facts()) -> pid() | undefined.

With Announce true, starts the announcer of the calling process and returns its pid once it monitors the caller; the announcer then publishes the start fact. With Announce false nothing starts and undefined is returned.