hyperclock/
lib.rs

1//! # Hyperclock
2//!
3//! A high-performance, event-driven, phased time engine for Rust.
4//!
5//! Hyperclock provides the core engine for time-based, phased event processing.
6//! It is designed to be a library that an application uses to manage complex,
7//! time-sensitive logic in a structured and decoupled way.
8//!
9//! ## Core Concepts
10//!
11//! - **SystemClock**: A high-frequency ticker that acts as the single source of time.
12//! - **Phased Cycle**: On every tick, the engine executes a configurable sequence of
13//!   phases (e.g., "observe", "decide", "act"), allowing for structured logic
14//!   that mirrors cognitive or industrial processes.
15//! - **Event-Driven**: All logic is executed in response to strongly-typed events.
16//!   Your application subscribes to event streams (`GongEvent`, `TaskEvent`, etc.)
17//!   to perform work.
18//! - **Configuration-Driven**: The engine's speed, phase sequence, and calendar
19//!   events are defined at startup via a `HyperclockConfig` object, often loaded
20//!   from a file.
21//!
22//! ## Example Usage
23//!
24//! ```rust,no_run
25//! use hyperclock::prelude::*;
26//! use std::time::Duration;
27//! use tokio::sync::broadcast;
28//!
29//! #[tokio::main]
30//! async fn main() -> anyhow::Result<()> {
31//!     // 1. Create a default configuration.
32//!     let config = HyperclockConfig::default();
33//!
34//!     // 2. Create the engine.
35//!     let engine = HyperclockEngine::new(config);
36//!
37//!     // 3. Subscribe to an event stream before starting the engine.
38//!     let mut system_events = engine.subscribe_system_events();
39//!     tokio::spawn(async move {
40//!         while let Ok(event) = system_events.recv().await {
41//!             println!("Received System Event: {:?}", event);
42//!         }
43//!     });
44//!
45//!     // 4. Register listeners.
46//!     let _listener_id = engine.on_interval(
47//!         PhaseId(0),
48//!         Duration::from_secs(5),
49//!         || println!("5 seconds have passed in phase 0!")
50//!     ).await;
51//!
52//!     // 5. Run the engine. It will shut down on Ctrl+C.
53//!     engine.run().await?;
54//!
55//!     Ok(())
56//! }
57//! ```
58
59pub const ENGINE_NAME: &str = "[ HYPER_ENGINE ]";
60pub const VERSION: &str = env!("CARGO_PKG_VERSION");
61
62
63// Declare all the modules in the crate.
64pub mod common;
65pub mod components;
66pub mod config;
67pub mod engine;
68pub mod events;
69pub mod time;
70
71/// A prelude module for easy importing of the most common Hyperclock types.
72pub mod prelude {
73    pub use crate::common::{ListenerId, PhaseId, TaskId};
74    pub use crate::config::{ClockResolution, HyperclockConfig};
75    pub use crate::engine::HyperclockEngine;
76    pub use crate::events::{
77        AutomationEvent, ConditionalEvent, GongEvent, PhaseEvent, SystemEvent, TaskEvent,
78        UserEvent,
79    };
80    pub use crate::time::TickEvent;
81}
82
83// A temporary default implementation for the config for the example.
84impl Default for config::HyperclockConfig {
85    fn default() -> Self {
86        Self {
87            resolution: config::ClockResolution::Low,
88            phases: vec![config::PhaseConfig {
89                id: common::PhaseId(0),
90                label: "default".to_string(),
91            }],
92            gong_config: config::GongConfig::default(),
93        }
94    }
95}
hyperclock/lib.rs

hyperclock/
lib.rs
