Jido.Signal.Bus.State (Jido Signal v2.2.0)

View Source

Defines the state structure for the signal bus.

This module contains the type definitions and operations for managing the internal state of the signal bus, including signal logs, subscriptions, snapshots, and router configuration. It provides functions for manipulating and querying this state.

Summary

Types

t()

Functions

add_route(state, route)

Adds a route to the router in the bus state.

add_subscription(state, subscription_id, subscription)

Adds a subscription to the bus state and creates a corresponding route.

append_signals(state, signals)

Merges a list of recorded signals into the existing log. Signals are added to the log keyed by their IDs. If a signal with the same ID already exists, it will be overwritten.

append_uuid_signal_pairs(state, uuid_signal_pairs)

Appends pre-generated {log_id, signal} pairs into the state log.

clear_log(state)

Clears all signals from the log.

get_subscription(state, subscription_id)

Retrieves a subscription from the bus state.

has_subscription?(state, subscription_id)

Checks if a subscription exists in the bus state.

log_entries_to_list(state)

Converts the signal log from a map to a list of {log_id, signal} tuples sorted by recorded log key chronology.

log_to_list(state)

Converts the signal log from a map to a list sorted by recorded log key.

new(name, opts \\ [])

Creates a new BusState with the given name and options.

remove_route(state, route)

Removes a route from the router in the bus state.

remove_subscription(state, subscription_id, opts \\ [])

Removes a subscription from the bus state and its corresponding route.

schema()

Returns the Zoi schema for State

truncate_log(state, max_size)

Truncates the signal log to the specified maximum size. Keeps the most recent signals and discards older ones.

Types

t()

@type t() :: %Jido.Signal.Bus.State{
  child_supervisor: nil | nil | any(),
  gc_timer_ref: nil | nil | any(),
  jido: nil | nil | atom(),
  journal_adapter: nil | nil | atom(),
  journal_owned?: nil | boolean(),
  journal_pid: nil | nil | any(),
  log: nil | map(),
  log_ttl_ms: nil | nil | integer(),
  max_log_size: nil | integer(),
  middleware: nil | [any()],
  middleware_timeout_ms: nil | integer(),
  name: atom(),
  partition_count: nil | integer(),
  partition_pids: nil | [any()],
  partition_supervisor: nil | nil | any(),
  publish_inflight: nil | nil | any(),
  publish_queue: nil | [any()],
  router: nil | nil | any(),
  snapshots: nil | map(),
  subscriptions: nil | map()
}

Functions

add_route(state, route)

@spec add_route(t(), Jido.Signal.Router.Route.t()) :: {:ok, t()} | {:error, term()}

Adds a route to the router in the bus state.

Parameters

  • state: The current bus state
  • route: The route to add to the router

Returns

  • {:ok, new_state} if successful
  • {:error, reason} if the route addition fails

add_subscription(state, subscription_id, subscription)

@spec add_subscription(t(), String.t(), Jido.Signal.Bus.Subscriber.t()) ::
  {:ok, t()} | {:error, atom()}

Adds a subscription to the bus state and creates a corresponding route.

Parameters

  • state: The current bus state
  • subscription_id: The unique ID for the subscription
  • subscription: The subscription struct to add

Returns

  • {:ok, new_state} if successful
  • {:error, :subscription_exists} if a subscription with this ID already exists

append_signals(state, signals)

@spec append_signals(t(), [Jido.Signal.t() | {:ok, Jido.Signal.t()} | map()]) ::
  {:ok, t(), [{String.t(), Jido.Signal.t()}]} | {:error, term()}

Merges a list of recorded signals into the existing log. Signals are added to the log keyed by their IDs. If a signal with the same ID already exists, it will be overwritten.

Parameters

  • state: The current bus state
  • signals: List of recorded signals to merge

Returns

  • {:ok, new_state, recorded_signals} with signals merged into log
  • {:error, reason} if there was an error processing the signals

append_uuid_signal_pairs(state, uuid_signal_pairs)

@spec append_uuid_signal_pairs(t(), [{String.t(), Jido.Signal.t()}]) ::
  {:ok, t()} | {:error, term()}

Appends pre-generated {log_id, signal} pairs into the state log.

clear_log(state)

@spec clear_log(t()) :: {:ok, t()}

Clears all signals from the log.

get_subscription(state, subscription_id)

@spec get_subscription(t(), String.t()) :: Jido.Signal.Bus.Subscriber.t() | nil

Retrieves a subscription from the bus state.

Parameters

  • state: The current bus state
  • subscription_id: The ID of the subscription to retrieve

Returns

The subscription struct if found, nil otherwise

has_subscription?(state, subscription_id)

@spec has_subscription?(t(), String.t()) :: boolean()

Checks if a subscription exists in the bus state.

Parameters

  • state: The current bus state
  • subscription_id: The ID of the subscription to check

Returns

true if the subscription exists, false otherwise

log_entries_to_list(state)

@spec log_entries_to_list(t()) :: [{String.t(), Jido.Signal.t()}]

Converts the signal log from a map to a list of {log_id, signal} tuples sorted by recorded log key chronology.

log_to_list(state)

@spec log_to_list(t()) :: [Jido.Signal.t()]

Converts the signal log from a map to a list sorted by recorded log key.

Parameters

  • state: The current bus state

Returns

A list of signals sorted by recorded log key chronology.

Examples

iex> state = %Jido.Signal.Bus.State{log: %{"2" => signal2, "1" => signal1}}
iex> signals = Jido.Signal.Bus.State.log_to_list(state)
iex> length(signals)
2
iex> Enum.map(signals, & &1.id)
["1", "2"]

new(name, opts \\ [])

@spec new(
  atom(),
  keyword()
) :: t()

Creates a new BusState with the given name and options.

Automatically initializes the router to Router.new!() if not provided.

Examples

iex> state = Jido.Signal.Bus.State.new(:my_bus)
iex> state.name
:my_bus

remove_route(state, route)

@spec remove_route(t(), Jido.Signal.Router.Route.t() | String.t()) ::
  {:ok, t()} | {:error, :route_not_found}

Removes a route from the router in the bus state.

Parameters

  • state: The current bus state
  • route: The route to remove (can be a Route struct or path string)

Returns

  • {:ok, new_state} if successful
  • {:error, :route_not_found} if the route doesn't exist

remove_subscription(state, subscription_id, opts \\ [])

@spec remove_subscription(t(), String.t(), keyword()) :: {:ok, t()} | {:error, atom()}

Removes a subscription from the bus state and its corresponding route.

Parameters

  • state: The current bus state
  • subscription_id: The ID of the subscription to remove
  • opts: Options including:
    • :delete_persistence - Whether to delete persistence artifacts (default: false)

Returns

  • {:ok, new_state} if successful
  • {:error, :subscription_not_found} if the subscription doesn't exist

schema()

Returns the Zoi schema for State

truncate_log(state, max_size)

@spec truncate_log(t(), non_neg_integer()) :: {:ok, t()}

Truncates the signal log to the specified maximum size. Keeps the most recent signals and discards older ones.