Jido.Signal.Dispatch (Jido v1.1.0-rc)

A flexible signal dispatching system that routes signals to various destinations using configurable adapters.

The Dispatch module serves as the central hub for signal delivery in the Jido system. It provides a unified interface for sending signals to different destinations through various adapters. Each adapter implements specific delivery mechanisms suited for different use cases.

Built-in Adapters

The following adapters are provided out of the box:

:pid - Direct delivery to a specific process (see Jido.Signal.Dispatch.PidAdapter)
:bus - Delivery to an event bus (see Jido.Signal.Dispatch.Bus)
:named - Delivery to a named process (see Jido.Signal.Dispatch.Named)
:pubsub - Delivery via PubSub mechanism (see Jido.Signal.Dispatch.PubSub)
:logger - Log signals using Logger (see Jido.Signal.Dispatch.LoggerAdapter)
:console - Print signals to console (see Jido.Signal.Dispatch.ConsoleAdapter)
:noop - No-op adapter for testing/development (see Jido.Signal.Dispatch.NoopAdapter)

Configuration

Each adapter requires specific configuration options. A dispatch configuration is a tuple of {adapter_type, options} where:

adapter_type - One of the built-in adapter types above or a custom module implementing the Jido.Signal.Dispatch.Adapter behaviour
options - Keyword list of options specific to the chosen adapter

Multiple dispatch configurations can be provided as a list to send signals to multiple destinations.

Examples

# Send to a specific PID
config = {:pid, [target: {:pid, destination_pid}, delivery_mode: :async]}
Jido.Signal.Dispatch.dispatch(signal, config)

# Send to multiple destinations
config = [
  {:bus, [target: {:bus, :default}, stream: "events"]},
  {:logger, [level: :info]},
  {:pubsub, [target: :audit, topic: "audit"]}
]
Jido.Signal.Dispatch.dispatch(signal, config)

# Using a custom adapter
config = {MyCustomAdapter, [custom_option: "value"]}
Jido.Signal.Dispatch.dispatch(signal, config)

Custom Adapters

To implement a custom adapter, create a module that implements the Jido.Signal.Dispatch.Adapter behaviour. The module must implement:

validate_opts/1 - Validates the adapter-specific options
deliver/2 - Handles the actual signal delivery

See Jido.Signal.Dispatch.Adapter for more details.

Summary

Types

adapter()

dispatch_config()

dispatch_configs()

Functions

dispatch(signal, config)

Dispatches a signal using the provided configuration.

validate_opts(config)

Validates a dispatch configuration.

Types

adapter()

@type adapter() ::
  :pid | :bus | :named | :pubsub | :logger | :console | :noop | nil | module()

dispatch_config()

@type dispatch_config() :: {adapter(), Keyword.t()}

dispatch_configs()

@type dispatch_configs() :: dispatch_config() | [dispatch_config()]

Functions

dispatch(signal, config)

@spec dispatch(Jido.Signal.t(), dispatch_configs()) :: :ok | {:error, term()}

Dispatches a signal using the provided configuration.

Parameters

signal - The signal to dispatch
config - Either a single dispatch configuration tuple or a list of configurations

Examples

# Single destination
iex> config = {:pid, [target: {:pid, pid}, delivery_mode: :async]}
iex> Jido.Signal.Dispatch.dispatch(signal, config)
:ok

# Multiple destinations
iex> config = [
...>   {:bus, [target: {:bus, :default}, stream: "events"]},
...>   {:pubsub, [target: :audit, topic: "audit"]}
...> ]
iex> Jido.Signal.Dispatch.dispatch(signal, config)
:ok

validate_opts(config)

@spec validate_opts(dispatch_configs()) ::
  {:ok, dispatch_configs()} | {:error, term()}

Validates a dispatch configuration.

Parameters

config - Either a single dispatch configuration tuple or a list of dispatch configurations

Returns

{:ok, config} if the configuration is valid
{:error, reason} if the configuration is invalid

Examples

# Single config
iex> config = {:pid, [target: {:pid, self()}, delivery_mode: :async]}
iex> Jido.Signal.Dispatch.validate_opts(config)
{:ok, ^config}

# Multiple configs
iex> config = [
...>   {:bus, [target: {:bus, :default}, stream: "events"]},
...>   {:pubsub, [target: {:pubsub, :audit}, topic: "audit"]}
...> ]
iex> Jido.Signal.Dispatch.validate_opts(config)
{:ok, ^config}