Raxol.Core.Runtime.Subscription (Raxol v2.8.0)

Provides a way to subscribe to recurring updates and external events.

Subscriptions allow applications to receive messages over time without explicitly requesting them. This is useful for:

Timer-based updates (animation, polling)
Events dispatched through Raxol.Core.Events.EventManager
External data streams (file changes, network events)

Types of Subscriptions

:interval - Regular time-based updates
:events - Events dispatched through Raxol.Core.Events.EventManager. EventManager is one process per node, so a subscription receives every event of its types from every session on the node (see events/1)
:file_watch - File system changes
:custom - Custom event sources

Examples

# Update every second
Subscription.interval(1000, :tick)

# Listen for specific EventManager events
Subscription.events([:theme_changed, :accessibility_enabled])

# Watch a file for changes
Subscription.file_watch("config.json", [:modify, :delete])

# Custom subscription
Subscription.custom(MyEventSource, :start_listening)

Summary

Functions

custom(source_module, init_args)

Creates a custom subscription using a provided event source. The event source should implement the Raxol.Core.Runtime.EventSource behaviour.

events(event_types)

Creates a subscription for events dispatched through Raxol.Core.Events.EventManager (EventManager.dispatch/1,2 or EventManager.notify/3).

file_watch(path, event_types \\ [:modify])

Creates a subscription that watches for file system changes.

interval(interval_ms, msg, opts \\ [])

Creates a subscription that will send a message at regular intervals.

new(type, data)

Creates a new subscription. This is the low-level constructor, prefer using the specific subscription constructors unless you need custom behavior.

start(subscription, context)

Starts a subscription within the given context. This is used by the runtime system and should not be called directly by applications.

stop(subscription_id)

Stops a subscription. This is used by the runtime system and should not be called directly by applications.

Types

t()

@type t() :: %Raxol.Core.Runtime.Subscription{
  data: term(),
  type: :interval | :events | :file_watch | :custom
}

Functions

custom(source_module, init_args)

Creates a custom subscription using a provided event source. The event source should implement the Raxol.Core.Runtime.EventSource behaviour.

events(event_types)

Creates a subscription for events dispatched through Raxol.Core.Events.EventManager (EventManager.dispatch/1,2 or EventManager.notify/3).

Each matching event reaches the app's update/2 as {:event, event_type, event_data}, once per event even when several declared subscriptions list its type.

Delivery stops if EventManager restarts: the subscription lived in the stopped EventManager and is not re-established with the new one.

EventManager is node-global: every session on the node (SSH, LiveView, headless) whose app subscribes to a type receives every event of that type, whichever session or process dispatched it. Nothing filters by session.

Only EventManager-dispatched events arrive this way. Terminal input (key presses, mouse, resize, focus) is not routed through EventManager: it reaches update/2 as a Raxol.Core.Events.Event struct without any subscription. Events the framework dispatches include :theme_changed, :high_contrast_changed, :accessibility_enabled, :accessibility_disabled and :accessibility_preference_changed.

:screen_reader_announcement, :activate and :dismiss also go through EventManager, but they carry other sessions' data: the announcement queue and keyboard navigator that dispatch them are node-global singletons with no session identity, so a subscriber receives the announcement text and focused component ids of every session on the node. Do not subscribe to them in an app served to more than one user.