Raxol.Core.Runtime.Subscription (Raxol v0.2.0)

View Source

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)
  • System events (window resize, focus change)
  • External data streams (file changes, network events)

Types of Subscriptions

  • :interval - Regular time-based updates
  • :events - System or component events
  • :file_watch - File system changes
  • :custom - Custom event sources

Examples 

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

# Listen for specific events
Subscription.events([:key_press, :mouse_click])

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

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

Summary

Types

t()

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 system or component events.

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 system or component events.

Event Types

  • :key_press - Keyboard events
  • :mouse_click - Mouse click events
  • :mouse_move - Mouse movement events
  • :window_resize - Terminal window resize
  • :focus_change - Terminal focus change
  • :component - Component-specific events

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

Creates a subscription that watches for file system changes.

Event Types

  • :modify - File content changes
  • :delete - File deletion
  • :create - File creation
  • :rename - File rename
  • :attrib - Attribute changes

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

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

Options

  • :start_immediately - Send first message immediately (default: false)
  • :jitter - Add random jitter to interval (default: 0)

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.

Returns {:ok, subscription_id} or {:error, reason}.

stop(subscription_id)

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