ExAgent.PubSub behaviour (ExAgent v0.5.0)

Copy Markdown View Source

Behaviour for broadcasting ExAgent.Events.

ExAgent never depends on a concrete PubSub implementation. The default is ExAgent.PubSub.None (no side-effects, for one-shot use and tests that don't observe events). ExAgent.PubSub.Local ships an in-process Registry-backed implementation that works out of the box. ExAgent.PubSub.Phoenix delegates to Phoenix.PubSub dynamically, with no hard dependency on Phoenix. A custom implementation just implements this behaviour.

A PubSub is referenced as {module, config} where config is opaque to ExAgent (e.g. a PubSub server name for Phoenix, or [] for Local/None). The helper normalize/1 turns the friendly option forms into that tuple.

Summary

Callbacks

broadcast(config, topic, event)

Broadcast event to all subscribers of topic.

subscribe(config, topic)

Subscribe the calling process to topic. Implementations that can't subscribe (e.g. None) should return {:error, {:subscribe_unsupported, mod}}.

Functions

broadcast(arg, topic, event)

Broadcast via the resolved {module, config} tuple.

normalize(mod)

Resolve a PubSub option into a {module, config} tuple.

subscribe(arg, topic)

Subscribe via the resolved tuple.

Callbacks

broadcast(config, topic, event)

@callback broadcast(config :: term(), topic :: String.t(), event :: ExAgent.Event.t()) ::
  :ok | {:error, term()}

Broadcast event to all subscribers of topic.

subscribe(config, topic)

@callback subscribe(config :: term(), topic :: String.t()) :: :ok | {:error, term()}

Subscribe the calling process to topic. Implementations that can't subscribe (e.g. None) should return {:error, {:subscribe_unsupported, mod}}.

Functions

broadcast(arg, topic, event)

@spec broadcast({module(), term()}, String.t(), ExAgent.Event.t()) ::
  :ok | {:error, term()}

Broadcast via the resolved {module, config} tuple.

normalize(mod)

@spec normalize(term()) :: {module(), term()}

Resolve a PubSub option into a {module, config} tuple.

Accepts:

  • nil / :none → {ExAgent.PubSub.None, []}
  • :local → {ExAgent.PubSub.Local, []}
  • module → {module, []}
  • {module, conf} → as-is

The resolved module must implement this behaviour.

subscribe(arg, topic)

@spec subscribe(
  {module(), term()},
  String.t()
) :: :ok | {:error, term()}

Subscribe via the resolved tuple.