Struct HyperclockEngine

pub struct HyperclockEngine { /* private fields */ }

The main Hyperclock engine.

This struct is the central point of control. It holds the system’s configuration, manages all active listeners and tasks, and drives the event loop. The Engine is designed to be cloned and shared across tasks, providing a handle to the running instance.

Implementations

impl HyperclockEngine

pub fn new(config: HyperclockConfig) -> Self

Creates a new HyperclockEngine with the given configuration.

pub async fn run(&self) -> Result<()>

Runs the engine’s main loop until a shutdown signal is received.

This method will:

1. Spawn the SystemClock task.
2. Spawn the main dispatcher task that listens for ticks and fires events.
3. Wait for a Ctrl+C signal to initiate a graceful shutdown.

impl HyperclockEngine

pub async fn on_interval( &self, phase_to_watch: PhaseId, interval: Duration, task_logic: impl FnMut() + Send + Sync + 'static, ) -> ListenerId

Registers a task to be executed at a regular interval.

The task’s interval timer will only advance during the specified phase. The provided task_logic closure will be executed each time the interval elapses.

Arguments

• phase_to_watch - The PhaseId during which this interval is active.
• interval - The Duration between task executions.
• task_logic - A closure to execute when the interval fires.

Returns

A ListenerId which can be used to later remove this watcher.

pub async fn on_conditional( &self, condition: impl Fn() -> bool + Send + Sync + 'static, task_logic: impl FnMut() + Send + Sync + 'static, is_one_shot: bool, ) -> ListenerId

Registers a task to be executed whenever a given condition is met.

The condition closure is checked on every tick of the engine. If it returns true, the task_logic closure is executed.

Arguments

• condition - A closure that returns true when the task should fire.
• task_logic - A closure to execute when the condition is met.
• is_one_shot - If true, the watcher will be automatically removed after firing once.

Returns

A ListenerId which can be used to later remove this watcher.

pub async fn add_lifecycle_loop( &self, phase_to_watch: PhaseId, interval: Duration, steps: Vec<LifecycleStep>, repetition_policy: RepetitionPolicy, ) -> TaskId

Adds a new LifecycleLoop to the engine.

This creates a complex automation that executes a sequence of steps, with each step advancing after the specified interval.

Returns

A TaskId for the created lifecycle loop.

pub async fn remove_interval_listener(&self, id: ListenerId) -> bool

Removes an interval listener from the engine.

Returns true if the listener was found and removed.

pub async fn remove_conditional_listener(&self, id: ListenerId) -> bool

Removes a conditional listener from the engine.

Returns true if the listener was found and removed.

pub async fn remove_lifecycle_loop(&self, id: TaskId) -> bool

Removes a lifecycle loop from the engine.

This also removes the internal interval watcher that drives the loop. Returns true if the loop was found and removed.

pub fn subscribe_tick_events(&self) -> Receiver<Arc<TickEvent>>

Subscribes to the raw TickEvent stream.

This provides access to the highest-frequency event in the engine, firing directly from the SystemClock before phase processing. This is a power-user feature for tasks that need to react to every single tick without regard for the phase cycle.

Most users should prefer subscribe_phase_events.

pub fn subscribe_system_events(&self) -> Receiver<SystemEvent>

Subscribes to the SystemEvent stream.

pub fn subscribe_phase_events(&self) -> Receiver<PhaseEvent>

Subscribes to the PhaseEvent stream.

pub fn subscribe_gong_events(&self) -> Receiver<GongEvent>

Subscribes to the GongEvent stream.

pub fn subscribe_task_events(&self) -> Receiver<TaskEvent>

Subscribes to the TaskEvent stream.

pub fn subscribe_automation_events(&self) -> Receiver<AutomationEvent>

Subscribes to the AutomationEvent stream.

pub fn subscribe_conditional_events(&self) -> Receiver<ConditionalEvent>

Subscribes to the ConditionalEvent stream.

pub fn subscribe_user_events(&self) -> Receiver<UserEvent>

Subscribes to the UserEvent stream.

pub fn broadcast_user_event(&self, event: UserEvent)

Broadcasts a custom UserEvent to all subscribers.

Trait Implementations

impl Clone for HyperclockEngine

fn clone(&self) -> HyperclockEngine

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.