autocore_std/

lib.rs

//! # AutoCore Standard Library
//!
//! The standard library for writing AutoCore control programs. This crate provides
//! everything you need to build real-time control applications that integrate with
//! the AutoCore server ecosystem.
//!
//! ## Overview
//!
//! AutoCore control programs run as separate processes that communicate with the
//! autocore-server via shared memory and IPC. This library handles all the low-level
//! details, allowing you to focus on your control logic.
//!
//! ```text
//! ┌─────────────────────────┐     ┌─────────────────────────┐
//! │   autocore-server       │     │   Your Control Program  │
//! │                         │     │                         │
//! │  ┌─────────────────┐    │     │  ┌─────────────────┐    │
//! │  │ Shared Memory   │◄───┼─────┼──│ ControlRunner   │    │
//! │  │ (GlobalMemory)  │    │     │  │                 │    │
//! │  └─────────────────┘    │     │  │ ┌─────────────┐ │    │
//! │                         │     │  │ │ Your Logic  │ │    │
//! │  ┌─────────────────┐    │     │  │ └─────────────┘ │    │
//! │  │ Tick Signal     │────┼─────┼──│                 │    │
//! │  └─────────────────┘    │     │  └─────────────────┘    │
//! └─────────────────────────┘     └─────────────────────────┘
//! ```
//!
//! ## Quick Start
//!
//! 1. Create a new control project using `acctl`:
//!    ```bash
//!    acctl clone <server-ip> <project-name>
//!    ```
//!
//! 2. Implement the [`ControlProgram`] trait:
//!    ```ignore
//!    use autocore_std::{ControlProgram, RTrig};
//!
//!    // GlobalMemory is generated from your project.json
//!    mod gm;
//!    use gm::GlobalMemory;
//!
//!    pub struct MyProgram {
//!        start_button: RTrig,
//!    }
//!
//!    impl MyProgram {
//!        pub fn new() -> Self {
//!            Self {
//!                start_button: RTrig::new(),
//!            }
//!        }
//!    }
//!
//!    impl ControlProgram for MyProgram {
//!        type Memory = GlobalMemory;
//!
//!        fn process_tick(&mut self, mem: &mut GlobalMemory, _cycle: u64) {
//!            // Detect rising edge on start button
//!            if self.start_button.call(mem.inputs.start_button) {
//!                mem.outputs.motor_running = true;
//!                autocore_std::log::info!("Motor started!");
//!            }
//!        }
//!    }
//!    ```
//!
//! 3. Use the [`autocore_main!`] macro for the entry point:
//!    ```ignore
//!    autocore_std::autocore_main!(MyProgram, "my_project_shm", "tick");
//!    ```
//!
//! ## Function Blocks (IEC 61131-3 Inspired)
//!
//! This library includes standard function blocks commonly used in PLC programming:
//!
//! - [`RTrig`] - Rising edge detector (false→true transition)
//! - [`FTrig`] - Falling edge detector (true→false transition)
//! - [`Ton`] - Timer On Delay (output after delay)
//!
//! ### Example: Edge Detection
//!
//! ```
//! use autocore_std::RTrig;
//!
//! let mut trigger = RTrig::new();
//!
//! // First call with false - no edge
//! assert_eq!(trigger.call(false), false);
//!
//! // Rising edge detected!
//! assert_eq!(trigger.call(true), true);
//!
//! // Still true, but no edge (already high)
//! assert_eq!(trigger.call(true), false);
//!
//! // Back to false
//! assert_eq!(trigger.call(false), false);
//!
//! // Another rising edge
//! assert_eq!(trigger.call(true), true);
//! ```
//!
//! ### Example: Timer
//!
//! ```
//! use autocore_std::Ton;
//! use std::time::Duration;
//!
//! let mut timer = Ton::new();
//! let delay = Duration::from_millis(100);
//!
//! // Timer not enabled - output is false
//! assert_eq!(timer.call(false, delay), false);
//!
//! // Enable timer - starts counting
//! assert_eq!(timer.call(true, delay), false);
//!
//! // Still counting...
//! std::thread::sleep(Duration::from_millis(50));
//! assert_eq!(timer.call(true, delay), false);
//! assert!(timer.et < delay); // Elapsed time < preset
//!
//! // After delay elapsed
//! std::thread::sleep(Duration::from_millis(60));
//! assert_eq!(timer.call(true, delay), true); // Output is now true!
//! ```
//!
//! ## Logging
//!
//! Control programs can send log messages to the autocore-server for display in the
//! web console. Logging is handled automatically when using [`ControlRunner`].
//!
//! ```ignore
//! use autocore_std::log;
//!
//! log::trace!("Detailed trace message");
//! log::debug!("Debug information");
//! log::info!("Normal operation message");
//! log::warn!("Warning condition detected");
//! log::error!("Error occurred!");
//! ```
//!
//! See the [`logger`] module for advanced configuration.
//!
//! ## Memory Synchronization
//!
//! The [`ControlRunner`] handles all shared memory synchronization automatically:
//!
//! 1. **Wait for tick** - Blocks until the server signals a new cycle
//! 2. **Read inputs** - Copies shared memory to local buffer (atomic snapshot)
//! 3. **Execute logic** - Your `process_tick` runs on the local buffer
//! 4. **Write outputs** - Copies local buffer back to shared memory
//!
//! This ensures your control logic always sees a consistent view of the data,
//! even when other processes are modifying shared memory.

#![warn(missing_docs)]
#![warn(rustdoc::missing_crate_level_docs)]
#![doc(html_root_url = "https://docs.rs/autocore-std/3.3.0")]

use anyhow::{anyhow, Result};
use async_trait::async_trait;
use log::LevelFilter;
use mechutil::ipc::{CommandMessage, IpcClient, ModuleHandler};
use raw_sync::events::{Event, EventInit, EventState};
use raw_sync::Timeout;
use shared_memory::ShmemConf;
use std::collections::HashMap;
use std::sync::atomic::{fence, Ordering};
use std::time::{Duration, Instant};

/// UDP logger for sending log messages to autocore-server.
///
/// This module provides a non-blocking logger implementation that sends log messages
/// via UDP to the autocore-server. Messages are batched and sent asynchronously to
/// avoid impacting control loop timing.
///
/// # Example
///
/// ```ignore
/// use autocore_std::logger;
/// use log::LevelFilter;
///
/// // Initialize the logger (done automatically by ControlRunner)
/// logger::init_udp_logger("127.0.0.1", 39101, LevelFilter::Info, "control")?;
///
/// // Now you can use the log macros
/// log::info!("System initialized");
/// ```
pub mod logger;

// Re-export log crate for convenience - control programs can use autocore_std::log::info!() etc.
pub use log;

// ============================================================================
// Standard Library Function Blocks (IEC 61131-3 Inspired)
// ============================================================================

/// Rising Edge Trigger (R_TRIG)
///
/// Detects a rising edge (false → true transition) on the input signal.
/// The output `q` is `true` for exactly one cycle when the input `clk`
/// transitions from `false` to `true`.
///
/// This is equivalent to the IEC 61131-3 R_TRIG function block.
///
/// # Example
///
/// ```
/// use autocore_std::RTrig;
///
/// let mut trigger = RTrig::new();
///
/// // No edge yet
/// assert_eq!(trigger.call(false), false);
///
/// // Rising edge detected!
/// assert_eq!(trigger.call(true), true);
///
/// // Signal still high, but edge already passed
/// assert_eq!(trigger.call(true), false);
/// assert_eq!(trigger.call(true), false);
///
/// // Signal goes low
/// assert_eq!(trigger.call(false), false);
///
/// // Another rising edge
/// assert_eq!(trigger.call(true), true);
/// ```
///
/// # Timing Diagram
///
/// ```text
/// clk: _____|‾‾‾‾‾‾‾‾‾|_____|‾‾‾‾‾
///   q: _____|‾|_____________|‾|____
/// ```
///
/// # Use Cases
///
/// - Detecting button presses (trigger on press, not hold)
/// - Counting events (increment counter on each rising edge)
/// - State machine transitions
#[derive(Debug, Clone)]
pub struct RTrig {
    /// Current input value
    pub clk: bool,
    /// Output: true for one cycle on rising edge
    pub q: bool,
    /// Internal memory of previous input state
    m: bool,
}

impl RTrig {
    /// Creates a new rising edge trigger with all values initialized to `false`.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::RTrig;
    ///
    /// let trigger = RTrig::new();
    /// assert_eq!(trigger.q, false);
    /// ```
    pub fn new() -> Self {
        Self {
            clk: false,
            q: false,
            m: false,
        }
    }

    /// Executes the rising edge detection logic.
    ///
    /// Call this method once per control cycle with the current input value.
    /// Returns `true` for exactly one cycle when a rising edge is detected.
    ///
    /// # Arguments
    ///
    /// * `clk` - The current state of the input signal
    ///
    /// # Returns
    ///
    /// `true` if a rising edge (false → true transition) was detected, `false` otherwise.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::RTrig;
    ///
    /// let mut trigger = RTrig::new();
    ///
    /// let button_pressed = true;
    /// if trigger.call(button_pressed) {
    ///     println!("Button was just pressed!");
    /// }
    /// ```
    pub fn call(&mut self, clk: bool) -> bool {
        self.clk = clk;
        self.q = self.clk && !self.m;
        self.m = self.clk;
        self.q
    }
}

impl Default for RTrig {
    fn default() -> Self {
        Self::new()
    }
}


/// Falling Edge Trigger (F_TRIG)
///
/// Detects a falling edge (true → false transition) on the input signal.
/// The output `q` is `true` for exactly one cycle when the input `clk`
/// transitions from `true` to `false`.
///
/// This is equivalent to the IEC 61131-3 F_TRIG function block.
///
/// # Example
///
/// ```
/// use autocore_std::FTrig;
///
/// let mut trigger = FTrig::new();
///
/// // Signal starts low
/// assert_eq!(trigger.call(false), false);
///
/// // Signal goes high
/// assert_eq!(trigger.call(true), false);
///
/// // Falling edge detected!
/// assert_eq!(trigger.call(false), true);
///
/// // Signal still low, edge already passed
/// assert_eq!(trigger.call(false), false);
/// ```
///
/// # Timing Diagram
///
/// ```text
/// clk: _____|‾‾‾‾‾‾‾‾‾|_____|‾‾‾‾‾
///   q: _______________|‾|________
/// ```
///
/// # Use Cases
///
/// - Detecting button releases
/// - Detecting signal loss
/// - Triggering actions when a condition ends
#[derive(Debug, Clone)]
pub struct FTrig {
    /// Current input value
    pub clk: bool,
    /// Output: true for one cycle on falling edge
    pub q: bool,
    /// Internal memory of previous input state
    m: bool,
}

impl FTrig {
    /// Creates a new falling edge trigger with all values initialized to `false`.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::FTrig;
    ///
    /// let trigger = FTrig::new();
    /// assert_eq!(trigger.q, false);
    /// ```
    pub fn new() -> Self {
        Self {
            clk: false,
            q: false,
            m: false,
        }
    }

    /// Executes the falling edge detection logic.
    ///
    /// Call this method once per control cycle with the current input value.
    /// Returns `true` for exactly one cycle when a falling edge is detected.
    ///
    /// # Arguments
    ///
    /// * `clk` - The current state of the input signal
    ///
    /// # Returns
    ///
    /// `true` if a falling edge (true → false transition) was detected, `false` otherwise.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::FTrig;
    ///
    /// let mut trigger = FTrig::new();
    ///
    /// // Simulate button release
    /// trigger.call(true);  // Button held
    /// if trigger.call(false) {  // Button released
    ///     println!("Button was just released!");
    /// }
    /// ```
    pub fn call(&mut self, clk: bool) -> bool {
        self.clk = clk;
        self.q = !self.clk && self.m;
        self.m = self.clk;
        self.q
    }
}

impl Default for FTrig {
    fn default() -> Self {
        Self::new()
    }
}


/// Timer On Delay (TON)
///
/// A timer that delays turning on the output. The output `q` becomes `true`
/// after the enable input `en` has been continuously `true` for the preset
/// time `pt`. The elapsed time is available in `et`.
///
/// This is equivalent to the IEC 61131-3 TON function block.
///
/// # Behavior
///
/// - When `en` becomes `true`, the timer starts counting from zero
/// - While counting, `et` shows the elapsed time and `q` is `false`
/// - When `et` reaches `pt`, `q` becomes `true` and `et` is clamped to `pt`
/// - When `en` becomes `false`, the timer resets: `q` = `false`, `et` = 0
///
/// # Example
///
/// ```
/// use autocore_std::Ton;
/// use std::time::Duration;
///
/// let mut timer = Ton::new();
/// let delay = Duration::from_secs(5);
///
/// // Timer disabled - output is false
/// assert_eq!(timer.call(false, delay), false);
/// assert_eq!(timer.et, Duration::ZERO);
///
/// // Enable timer - starts counting
/// timer.call(true, delay);
/// assert_eq!(timer.q, false);  // Not done yet
/// // timer.et is now counting up...
///
/// // Disable resets the timer
/// timer.call(false, delay);
/// assert_eq!(timer.et, Duration::ZERO);
/// ```
///
/// # Timing Diagram
///
/// ```text
///  en: _____|‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾|_____
///   q: _____________|‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾|_____
///  et: 0---|++++++++|PT----------------|0----
///          ^        ^                  ^
///          |        |                  |
///      en rises   et=pt             en falls
/// ```
///
/// # Use Cases
///
/// - Motor start delay (allow contactors to engage)
/// - Debouncing switches (ignore brief transitions)
/// - Timeout detection (alarm if condition persists too long)
#[derive(Debug, Clone)]
pub struct Ton {
    /// Input: Enable the timer (true = counting, false = reset)
    pub en: bool,
    /// Input: Preset time (duration before output activates)
    pub pt: Duration,
    /// Output: Timer done (true when elapsed time >= preset time)
    pub q: bool,
    /// Output: Elapsed time since timer was enabled
    pub et: Duration,

    start_time: Option<Instant>,
    active: bool,
}

impl Ton {
    /// Creates a new timer with default values.
    ///
    /// The timer starts in the disabled state with zero elapsed time.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::Ton;
    ///
    /// let timer = Ton::new();
    /// assert_eq!(timer.q, false);
    /// assert_eq!(timer.et, std::time::Duration::ZERO);
    /// ```
    pub fn new() -> Self {
        Self {
            en: false,
            pt: Duration::default(),
            q: false,
            et: Duration::default(),
            start_time: None,
            active: false,
        }
    }

    /// Executes the timer logic.
    ///
    /// Call this method once per control cycle. The timer counts real elapsed
    /// time (not cycles), so the output timing is independent of scan rate.
    ///
    /// # Arguments
    ///
    /// * `en` - Enable input: `true` to run timer, `false` to reset
    /// * `pt` - Preset time: duration before output activates
    ///
    /// # Returns
    ///
    /// The current state of the output `q` (true if timer has elapsed).
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::Ton;
    /// use std::time::Duration;
    ///
    /// let mut timer = Ton::new();
    ///
    /// // Use in a control loop
    /// let motor_request = true;
    /// let start_delay = Duration::from_millis(500);
    ///
    /// let motor_enabled = timer.call(motor_request, start_delay);
    /// // motor_enabled will be true after 500ms of motor_request being true
    /// ```
    pub fn call(&mut self, en: bool, pt: Duration) -> bool {
        self.en = en;
        self.pt = pt;

        if !self.en {
            // Reset
            self.q = false;
            self.et = Duration::ZERO;
            self.start_time = None;
            self.active = false;
        } else {
            if !self.active {
                // Rising edge of EN - start timing
                self.start_time = Some(Instant::now());
                self.active = true;
                self.et = Duration::ZERO;
                self.q = false;
            } else {
                // Timer running
                if let Some(start) = self.start_time {
                    self.et = start.elapsed();
                    if self.et >= self.pt {
                        self.et = self.pt; // Clamp ET to PT
                        self.q = true;
                    }
                }
            }
        }
        self.q
    }

    /// Resets the timer to its initial state.
    ///
    /// This is equivalent to calling `call(false, ...)`.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::Ton;
    /// use std::time::Duration;
    ///
    /// let mut timer = Ton::new();
    /// timer.call(true, Duration::from_secs(1));
    /// // ... timer is running ...
    ///
    /// timer.reset();
    /// assert_eq!(timer.q, false);
    /// assert_eq!(timer.et, Duration::ZERO);
    /// ```
    pub fn reset(&mut self) {
        self.q = false;
        self.et = Duration::ZERO;
        self.start_time = None;
        self.active = false;
    }
}

impl Default for Ton {
    fn default() -> Self {
        Self::new()
    }
}

// ============================================================================
// Core Framework
// ============================================================================

/// Marker trait for generated GlobalMemory structs.
///
/// This trait is implemented by the auto-generated `GlobalMemory` struct
/// that represents the shared memory layout. It serves as a marker for
/// type safety in the control framework.
///
/// You don't need to implement this trait yourself - it's automatically
/// implemented by the code generator.
pub trait AutoCoreMemory {}

/// The trait that defines a control program's logic.
///
/// Implement this trait to create your control program. The associated `Memory`
/// type should be the generated `GlobalMemory` struct from your project.
///
/// # Memory Type Requirements
///
/// The `Memory` type must implement `Copy` to allow efficient synchronization
/// between shared memory and local buffers. This is automatically satisfied
/// by the generated `GlobalMemory` struct.
///
/// # Lifecycle
///
/// 1. `initialize` is called once at startup
/// 2. `process_tick` is called repeatedly in the control loop
///
/// # Example
///
/// ```ignore
/// use autocore_std::ControlProgram;
///
/// mod gm;
/// use gm::GlobalMemory;
///
/// pub struct MyController {
///     cycle_counter: u64,
/// }
///
/// impl MyController {
///     pub fn new() -> Self {
///         Self { cycle_counter: 0 }
///     }
/// }
///
/// impl ControlProgram for MyController {
///     type Memory = GlobalMemory;
///
///     fn initialize(&mut self, mem: &mut GlobalMemory) {
///         // Set initial output states
///         mem.outputs.ready = true;
///         log::info!("Controller initialized");
///     }
///
///     fn process_tick(&mut self, mem: &mut GlobalMemory, cycle: u64) {
///         self.cycle_counter = cycle;
///
///         // Your control logic here
///         if mem.inputs.start && !mem.inputs.estop {
///             mem.outputs.running = true;
///         }
///     }
/// }
/// ```
pub trait ControlProgram {
    /// The shared memory structure type (usually the generated `GlobalMemory`).
    ///
    /// Must implement `Copy` to allow efficient memory synchronization.
    type Memory: Copy;

    /// Called once when the control program starts.
    ///
    /// Use this to initialize output states, reset counters, or perform
    /// any one-time setup. The default implementation does nothing.
    ///
    /// # Arguments
    ///
    /// * `mem` - Mutable reference to the shared memory. Changes are written
    ///           back to shared memory after this method returns.
    fn initialize(&mut self, _mem: &mut Self::Memory) {}

    /// The main control loop - called once per scan cycle.
    ///
    /// This is where your control logic lives. Read inputs from `mem`,
    /// perform calculations, and write outputs back to `mem`.
    ///
    /// # Arguments
    ///
    /// * `mem` - Mutable reference to a local copy of the shared memory.
    ///           Changes made here are written back to shared memory after
    ///           this method returns.
    /// * `cycle` - The current cycle number (increments each tick, starting at 1).
    ///
    /// # Timing
    ///
    /// This method should complete within the scan cycle time. Long-running
    /// operations will cause cycle overruns.
    fn process_tick(&mut self, mem: &mut Self::Memory, cycle: u64);
}

/// Configuration for the [`ControlRunner`].
///
/// Specifies connection parameters, shared memory names, and logging settings.
/// Use [`Default::default()`] for typical configurations.
///
/// # Example
///
/// ```
/// use autocore_std::RunnerConfig;
/// use log::LevelFilter;
///
/// let config = RunnerConfig {
///     ipc_address: "192.168.1.100:9100".to_string(),
///     module_name: "my_controller".to_string(),
///     shm_name: "my_project_shm".to_string(),
///     tick_signal_name: "tick".to_string(),
///     busy_signal_name: Some("busy".to_string()),
///     log_level: LevelFilter::Debug,
///     ..Default::default()
/// };
/// ```
#[derive(Debug, Clone)]
pub struct RunnerConfig {
    /// IPC server address in "host:port" format (default: "127.0.0.1:9100")
    pub ipc_address: String,
    /// Module name for registration with the server (default: "control")
    pub module_name: String,
    /// Shared memory segment name (must match server configuration)
    pub shm_name: String,
    /// Name of the tick signal in shared memory (triggers each scan cycle)
    pub tick_signal_name: String,
    /// Optional name of the busy signal (set when cycle completes)
    pub busy_signal_name: Option<String>,
    /// Minimum log level to send to the server (default: Info)
    pub log_level: LevelFilter,
    /// UDP port for sending logs to the server (default: 39101)
    pub log_udp_port: u16,
}

impl Default for RunnerConfig {
    fn default() -> Self {
        Self {
            ipc_address: "127.0.0.1:9100".to_string(),
            module_name: "control".to_string(),
            shm_name: "autocore_cyclic".to_string(),
            tick_signal_name: "tick".to_string(),
            busy_signal_name: None,
            log_level: LevelFilter::Info,
            log_udp_port: logger::DEFAULT_LOG_UDP_PORT,
        }
    }
}

/// Internal handler for IPC setup phase.
/// The control program only uses IPC during initialization to get the memory layout.
struct ControlSetupHandler {
    domain: String,
}

impl ControlSetupHandler {
    fn new(domain: &str) -> Self {
        Self {
            domain: domain.to_string(),
        }
    }
}

#[async_trait]
impl ModuleHandler for ControlSetupHandler {
    async fn handle_message(&mut self, msg: CommandMessage) -> CommandMessage {
        // We don't expect to handle any messages during setup
        msg.into_error_response("Control module does not handle external messages")
    }

    async fn on_initialize(&mut self) -> Result<(), anyhow::Error> {
        Ok(())
    }

    async fn on_finalize(&mut self) -> Result<(), anyhow::Error> {
        Ok(())
    }

    fn domain(&self) -> &str {
        &self.domain
    }

    fn version(&self) -> &str {
        "1.0.0"
    }
}

/// The main execution engine for control programs.
///
/// `ControlRunner` handles all the infrastructure required to run a control program:
///
/// - Connecting to the autocore-server via IPC
/// - Opening and mapping shared memory
/// - Setting up synchronization signals
/// - Running the real-time control loop
/// - Sending log messages to the server
///
/// # Usage
///
/// ```ignore
/// use autocore_std::{ControlRunner, RunnerConfig};
///
/// let config = RunnerConfig {
///     shm_name: "my_project_shm".to_string(),
///     tick_signal_name: "tick".to_string(),
///     ..Default::default()
/// };
///
/// ControlRunner::new(MyProgram::new())
///     .config(config)
///     .run()?;  // Blocks forever
/// ```
///
/// # Control Loop
///
/// The runner executes a synchronous control loop:
///
/// 1. **Wait** - Blocks until the tick signal is set by the server
/// 2. **Read** - Copies shared memory to a local buffer (acquire barrier)
/// 3. **Execute** - Calls your `process_tick` method
/// 4. **Write** - Copies local buffer back to shared memory (release barrier)
/// 5. **Signal** - Sets the busy signal (if configured) to indicate completion
///
/// This ensures your code always sees a consistent snapshot of the data
/// and that your writes are atomically visible to other processes.
pub struct ControlRunner<P: ControlProgram> {
    config: RunnerConfig,
    program: P,
}

impl<P: ControlProgram> ControlRunner<P> {
    /// Creates a new runner for the given control program.
    ///
    /// Uses default configuration. Call [`.config()`](Self::config) to customize.
    ///
    /// # Arguments
    ///
    /// * `program` - Your control program instance
    ///
    /// # Example
    ///
    /// ```ignore
    /// let runner = ControlRunner::new(MyProgram::new());
    /// ```
    pub fn new(program: P) -> Self {
        Self {
            config: RunnerConfig::default(),
            program,
        }
    }

    /// Sets the configuration for this runner.
    ///
    /// # Arguments
    ///
    /// * `config` - The configuration to use
    ///
    /// # Example
    ///
    /// ```ignore
    /// ControlRunner::new(MyProgram::new())
    ///     .config(RunnerConfig {
    ///         shm_name: "custom_shm".to_string(),
    ///         ..Default::default()
    ///     })
    ///     .run()?;
    /// ```
    pub fn config(mut self, config: RunnerConfig) -> Self {
        self.config = config;
        self
    }

    /// Starts the control loop.
    ///
    /// This method blocks indefinitely, running the control loop until
    /// an error occurs or the process is terminated.
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` only if the loop exits cleanly (which typically
    /// doesn't happen). Returns an error if:
    ///
    /// - IPC connection fails
    /// - Shared memory cannot be opened
    /// - Signal offsets cannot be found
    /// - A critical error occurs during execution
    ///
    /// # Example
    ///
    /// ```ignore
    /// fn main() -> anyhow::Result<()> {
    ///     ControlRunner::new(MyProgram::new())
    ///         .config(config)
    ///         .run()
    /// }
    /// ```
    pub fn run(mut self) -> Result<()> {
        // Initialize UDP logger FIRST (before any log statements)
        // Extract host from ipc_address (format: "host:port")
        let log_host = self.config.ipc_address
            .split(':')
            .next()
            .unwrap_or("127.0.0.1");

        if let Err(e) = logger::init_udp_logger(
            log_host,
            self.config.log_udp_port,
            self.config.log_level,
            "control",
        ) {
            eprintln!("Warning: Failed to initialize UDP logger: {}", e);
            // Continue anyway - logging will just go nowhere
        }

        // We use a dedicated runtime for the setup phase
        let rt = tokio::runtime::Builder::new_current_thread()
            .enable_all()
            .build()?;

        rt.block_on(async {
            log::info!("AutoCore Control Runner Starting...");

            // 1. Connect IPC using the new ModuleHandler API
            let handler = ControlSetupHandler::new(&self.config.module_name);
            let client = IpcClient::connect(&self.config.ipc_address, handler).await
                .map_err(|e| anyhow!("Failed to connect to server: {}", e))?;
            log::info!("IPC Connected.");

            // 2. Get Layout to find signal offsets
            // Use the request method with a timeout
            let response = client.request("gm.get_layout", serde_json::Value::Null, Duration::from_secs(5)).await
                .map_err(|e| anyhow!("Failed to get layout: {}", e))?;

            if !response.success {
                return Err(anyhow!("Failed to get layout: {}", response.error_message));
            }

            let layout: HashMap<String, serde_json::Value> = serde_json::from_value(response.data)?;

            // 3. Find Signal Offsets
            let tick_offset = self.find_offset(&layout, &self.config.tick_signal_name)?;
            let busy_offset = if let Some(name) = &self.config.busy_signal_name {
                Some(self.find_offset(&layout, name)?)
            } else {
                None
            };

            // Shutdown the IPC client - we don't need it anymore
            client.shutdown();

            // 4. Open Shared Memory
            let shmem = ShmemConf::new().os_id(&self.config.shm_name).open()?;
            let base_ptr = shmem.as_ptr();
            log::info!("Shared Memory '{}' mapped.", self.config.shm_name);

            // 5. Setup Pointers
            // SAFETY: We trust the server's layout matches the generated GlobalMemory struct.
            let gm = unsafe { &mut *(base_ptr as *mut P::Memory) };

            // EventInit::from_existing returns (Box<dyn EventImpl>, usize)
            let (tick_event, _) = unsafe {
                Event::from_existing(base_ptr.add(tick_offset))
                    .map_err(|e| anyhow!("Failed to open tick event: {}", e))?
            };

            let busy_event = if let Some(offset) = busy_offset {
                let (event, _) = unsafe {
                    Event::from_existing(base_ptr.add(offset))
                        .map_err(|e| anyhow!("Failed to open busy event: {}", e))?
                };
                Some(event)
            } else {
                None
            };

            // 6. Initialize local memory buffer and user program
            // We use a local copy for the control loop to ensure:
            // - Consistent snapshot of inputs at start of cycle
            // - Atomic commit of outputs at end of cycle
            // - Proper memory barriers for cross-process visibility
            let mut local_mem: P::Memory = unsafe { std::ptr::read_volatile(gm) };
            fence(Ordering::Acquire); // Ensure we see all prior writes from other processes

            self.program.initialize(&mut local_mem);

            // Write back any changes from initialize
            fence(Ordering::Release);
            unsafe { std::ptr::write_volatile(gm, local_mem) };

            log::info!("Entering Control Loop...");
            let mut cycle_count: u64 = 0;

            loop {
                // Wait for Tick
                if let Err(e) = tick_event.wait(Timeout::Infinite) {
                    eprintln!("Tick wait error: {}", e);
                    break;
                }

                cycle_count += 1;

                // === INPUT PHASE ===
                // Read all variables from shared memory into local buffer.
                // This gives us a consistent snapshot of inputs for this cycle.
                // Acquire fence ensures we see all writes from other processes (server, modules).
                local_mem = unsafe { std::ptr::read_volatile(gm) };
                fence(Ordering::Acquire);

                // === EXECUTE PHASE ===
                // Execute user logic on the local copy.
                // All reads/writes during process_tick operate on local_mem.
                self.program.process_tick(&mut local_mem, cycle_count);

                // === OUTPUT PHASE ===
                // Write all variables from local buffer back to shared memory.
                // Release fence ensures our writes are visible to other processes.
                fence(Ordering::Release);
                unsafe { std::ptr::write_volatile(gm, local_mem) };

                // Signal Busy/Done
                if let Some(ref busy) = busy_event {
                    let _ = busy.set(EventState::Signaled);
                }
            }

            Ok(())
        })
    }

    fn find_offset(&self, layout: &HashMap<String, serde_json::Value>, name: &str) -> Result<usize> {
        let info = layout.get(name).ok_or_else(|| anyhow!("Signal '{}' not found in layout", name))?;
        info.get("offset")
            .and_then(|v| v.as_u64())
            .map(|v| v as usize)
            .ok_or_else(|| anyhow!("Invalid offset for '{}'", name))
    }
}

/// Generates the standard `main` function for a control program.
///
/// This macro reduces boilerplate by creating a properly configured `main`
/// function that initializes and runs your control program.
///
/// # Arguments
///
/// * `$prog_type` - The type of your control program (must implement [`ControlProgram`])
/// * `$shm_name` - The shared memory segment name (string literal)
/// * `$tick_signal` - The tick signal name in shared memory (string literal)
///
/// # Example
///
/// ```ignore
/// mod gm;
/// use gm::GlobalMemory;
///
/// pub struct MyProgram;
///
/// impl MyProgram {
///     pub fn new() -> Self { Self }
/// }
///
/// impl autocore_std::ControlProgram for MyProgram {
///     type Memory = GlobalMemory;
///
///     fn process_tick(&mut self, mem: &mut GlobalMemory, _cycle: u64) {
///         // Your logic here
///     }
/// }
///
/// // This generates the main function
/// autocore_std::autocore_main!(MyProgram, "my_project_shm", "tick");
/// ```
///
/// # Generated Code
///
/// The macro expands to:
///
/// ```ignore
/// fn main() -> anyhow::Result<()> {
///     let config = autocore_std::RunnerConfig {
///         ipc_address: "127.0.0.1:9100".to_string(),
///         module_name: "control".to_string(),
///         shm_name: "my_project_shm".to_string(),
///         tick_signal_name: "tick".to_string(),
///         busy_signal_name: None,
///         log_level: log::LevelFilter::Info,
///         log_udp_port: autocore_std::logger::DEFAULT_LOG_UDP_PORT,
///     };
///
///     autocore_std::ControlRunner::new(MyProgram::new())
///         .config(config)
///         .run()
/// }
/// ```
#[macro_export]
macro_rules! autocore_main {
    ($prog_type:ty, $shm_name:expr, $tick_signal:expr) => {
        fn main() -> anyhow::Result<()> {
            let config = autocore_std::RunnerConfig {
                ipc_address: "127.0.0.1:9100".to_string(),
                module_name: "control".to_string(),
                shm_name: $shm_name.to_string(),
                tick_signal_name: $tick_signal.to_string(),
                busy_signal_name: None,
                log_level: log::LevelFilter::Info,
                log_udp_port: autocore_std::logger::DEFAULT_LOG_UDP_PORT,
            };

            autocore_std::ControlRunner::new(<$prog_type>::new())
                .config(config)
                .run()
        }
    };
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_rtrig_rising_edge() {
        let mut trigger = RTrig::new();

        // No edge initially
        assert_eq!(trigger.call(false), false);

        // Rising edge
        assert_eq!(trigger.call(true), true);

        // No edge while high
        assert_eq!(trigger.call(true), false);
        assert_eq!(trigger.call(true), false);

        // No edge on falling
        assert_eq!(trigger.call(false), false);

        // Rising edge again
        assert_eq!(trigger.call(true), true);
    }

    #[test]
    fn test_ftrig_falling_edge() {
        let mut trigger = FTrig::new();

        // No edge initially
        assert_eq!(trigger.call(false), false);

        // No edge on rising
        assert_eq!(trigger.call(true), false);

        // Falling edge
        assert_eq!(trigger.call(false), true);

        // No edge while low
        assert_eq!(trigger.call(false), false);

        // Rising, then falling edge
        assert_eq!(trigger.call(true), false);
        assert_eq!(trigger.call(false), true);
    }

    #[test]
    fn test_ton_basic() {
        let mut timer = Ton::new();
        let pt = Duration::from_millis(50);

        // Disabled
        assert_eq!(timer.call(false, pt), false);
        assert_eq!(timer.et, Duration::ZERO);

        // Enable
        assert_eq!(timer.call(true, pt), false);
        assert!(timer.et < pt);

        // Wait for timer
        std::thread::sleep(Duration::from_millis(60));
        assert_eq!(timer.call(true, pt), true);
        assert_eq!(timer.et, pt);

        // Reset
        timer.reset();
        assert_eq!(timer.q, false);
        assert_eq!(timer.et, Duration::ZERO);
    }
}