Real-Time Scheduler Guide

use r4w_core::rt_scheduler::{ScheduledEvent, EventAction, RadioState};
use std::time::Duration;

// Schedule a TX start with guard condition
let event = ScheduledEvent::new(
    scheduler.now_ns() + 1_000_000,  // 1ms from now
    EventAction::StartTx,
)
.with_priority(0)                    // Highest priority
.with_guard(|state| state.can_transmit())  // Only if TX allowed
.with_source("my_protocol");         // For logging/cancellation

use r4w_core::rt_scheduler::{RealTimeScheduler, ClockSource};
use std::time::Duration;

let scheduler = RealTimeScheduler::builder()
    .clock_source(ClockSource::System)
    .tx_rx_turnaround(Duration::from_micros(100))  // 100μs TX→RX
    .rx_tx_turnaround(Duration::from_micros(100))  // 100μs RX→TX
    .deadline_tolerance(Duration::from_micros(500)) // 500μs late = missed
    .build()
    .unwrap();

use r4w_core::rt_scheduler::{ScheduledEvent, EventAction};

// Schedule a single TX start
let event = ScheduledEvent::new(
    scheduler.now_ns() + 10_000_000,  // 10ms from now
    EventAction::StartTx,
);
scheduler.schedule(event);

// Schedule multiple events atomically
scheduler.schedule_batch(vec![
    ScheduledEvent::new(100_000_000, EventAction::StartTx),
    ScheduledEvent::new(110_000_000, EventAction::StopTx),
]);

// Process all due events (non-blocking)
let results = scheduler.process();

for result in results {
    match result {
        Ok(event) => println!("Executed: {:?}", event.action),
        Err(e) => eprintln!("Failed: {}", e),
    }
}

// Or run continuously in a loop
std::thread::spawn(move || {
    scheduler.run().unwrap();
});

// Stop from another thread
scheduler.stop();

// Schedule 10ms TX burst starting in 5ms
let (start_id, stop_id) = scheduler.schedule_tx_burst(
    scheduler.now_ns() + 5_000_000,  // Start time
    Duration::from_millis(10),        // Duration
);

// Can cancel if needed
scheduler.cancel(start_id);

// Listen for 50ms starting in 1ms
let (start_id, stop_id) = scheduler.schedule_rx_window(
    scheduler.now_ns() + 1_000_000,
    Duration::from_millis(50),
);

let frequencies = vec![
    902_000_000,  // 902 MHz
    915_000_000,  // 915 MHz
    928_000_000,  // 928 MHz
];

// Hop every 10ms
let event_ids = scheduler.schedule_hop_sequence(
    scheduler.now_ns(),
    Duration::from_millis(10),
    &frequencies,
);

// Cancel all hops from a source
scheduler.cancel_from_source("fhss");

// 4 slots, 10ms each, we transmit in slot 2
let event_ids = scheduler.schedule_tdma_frame(
    scheduler.now_ns(),
    Duration::from_millis(10),  // Slot duration
    2,                          // Our TX slot (0-indexed)
    4,                          // Total slots
);

// Beacon every 100ms, transmit for 5ms
let beacon_id = scheduler.schedule_beacon(
    scheduler.now_ns(),
    Duration::from_millis(100),  // Repeat interval
    Duration::from_millis(5),    // TX duration
);

// Cancel beacon
scheduler.cancel(beacon_id);

// Schedule a callback
let callback_id = scheduler.schedule_callback(
    scheduler.now_ns() + 1_000_000,
    |state| {
        println!("Callback fired! State: {:?}", state);
    },
);

// Or register callback and schedule separately
let id = scheduler.register_callback(|state| {
    // Handle event
});

let event = ScheduledEvent::new(
    deadline_ns,
    EventAction::Callback { callback_id: id },
);
scheduler.schedule(event);

// These will be serialized automatically
scheduler.schedule(ScheduledEvent::new(0, EventAction::StartTx)
    .with_guard(|s| s.can_transmit()));

scheduler.schedule(ScheduledEvent::new(1_000_000, EventAction::StartRx)
    .with_guard(|s| s.can_receive()));

// The RX will wait until TX completes + turnaround

let scheduler = RealTimeScheduler::builder()
    .tx_rx_turnaround(Duration::from_micros(50))   // TX→RX: 50μs
    .rx_tx_turnaround(Duration::from_micros(100))  // RX→TX: 100μs
    .build()?;

use r4w_core::rt_scheduler::RadioState;

// Check current state
let state = scheduler.state();
if state.can_transmit() {
    // Safe to TX
}

// Direct state manipulation (use carefully!)
scheduler.atomic_state().set(RadioState::Idle);

// Atomic transition with guard
let result = scheduler.atomic_state().transition_if(
    RadioState::Transmitting,
    |s| matches!(s, RadioState::Idle | RadioState::RxTurnaround),
);

use r4w_core::rt_scheduler::{EventHandler, ScheduledEvent, RadioState, EventError};
use std::sync::Arc;

struct MyHandler;

impl EventHandler for MyHandler {
    fn handle(&self, event: &ScheduledEvent, state: &RadioState) -> Result<(), EventError> {
        match &event.action {
            EventAction::SetFrequency { hz } => {
                println!("Tuning to {} Hz", hz);
                // Actually tune your hardware here
                Ok(())
            }
            EventAction::Custom { id, data } => {
                println!("Custom event {}: {:?}", id, data);
                Ok(())
            }
            _ => Ok(()),  // Let default handling proceed
        }
    }

    fn name(&self) -> &str {
        "my_handler"
    }
}

scheduler.add_handler(Arc::new(MyHandler));

let stats = scheduler.stats();

println!("Events scheduled: {}", stats.events_scheduled);
println!("Events executed: {}", stats.events_executed);
println!("Deadlines missed: {}", stats.deadlines_missed);
println!("Guards blocked: {}", stats.guards_blocked);
println!("Max latency: {}ns", stats.max_latency_ns);
println!("Avg latency: {}ns", stats.avg_latency_ns);
println!("State transitions: {}", stats.state_transitions);

// Reset statistics
scheduler.reset_stats();

// TDD frame: 5ms downlink, 5ms uplink, repeating
fn schedule_tdd_frame(scheduler: &RealTimeScheduler, frame_start: u64) {
    let slot_duration = Duration::from_millis(5);

    // Downlink (we TX)
    scheduler.schedule_tx_burst(frame_start, slot_duration);

    // Uplink (we RX)
    let uplink_start = frame_start + slot_duration.as_nanos() as u64;
    scheduler.schedule_rx_window(uplink_start, slot_duration);

    // Schedule next frame
    let next_frame = frame_start + 2 * slot_duration.as_nanos() as u64;
    scheduler.schedule_callback(next_frame, move |_| {
        schedule_tdd_frame(scheduler, next_frame);
    });
}

// 100 hops/second with TX/RX alternation
fn schedule_sincgars_net(
    scheduler: &RealTimeScheduler,
    hop_freqs: &[u64],
    our_slot: usize,
    total_slots: usize,
) {
    let hop_interval = Duration::from_millis(10);  // 100 hops/sec
    let slot_duration = hop_interval / total_slots as u32;

    for (hop_idx, &freq) in hop_freqs.iter().enumerate() {
        let hop_start = scheduler.now_ns() + (hop_idx as u64 * hop_interval.as_nanos() as u64);

        // Schedule frequency change
        scheduler.schedule(ScheduledEvent::new(
            hop_start,
            EventAction::SetFrequency { hz: freq },
        ).with_priority(0));  // Highest priority

        // Schedule our TX slot within this hop
        let our_slot_start = hop_start + (our_slot as u64 * slot_duration.as_nanos() as u64);
        scheduler.schedule_tx_burst(our_slot_start, slot_duration);

        // RX during other slots
        for slot in 0..total_slots {
            if slot != our_slot {
                let slot_start = hop_start + (slot as u64 * slot_duration.as_nanos() as u64);
                scheduler.schedule_rx_window(slot_start, slot_duration);
            }
        }
    }
}

// LoRa Class B: Listen for beacon, then open RX windows
fn schedule_class_b_windows(
    scheduler: &RealTimeScheduler,
    beacon_time: u64,
    ping_slots: &[u64],  // Offsets from beacon
) {
    // Open RX window for beacon
    scheduler.schedule_rx_window(
        beacon_time - Duration::from_millis(10).as_nanos() as u64,
        Duration::from_millis(20),
    );

    // Schedule ping slot windows
    for &offset in ping_slots {
        let window_start = beacon_time + offset;
        scheduler.schedule_rx_window(
            window_start,
            Duration::from_millis(30),  // Ping slot duration
        );
    }
}

use std::sync::Arc;

// Prevent two radios from TX simultaneously (co-site interference)
struct CoSiteCoordinator {
    radio1: Arc<RealTimeScheduler>,
    radio2: Arc<RealTimeScheduler>,
}

impl CoSiteCoordinator {
    fn schedule_tx(&self, radio: usize, start_ns: u64, duration: Duration) {
        let (sched, other) = match radio {
            1 => (&self.radio1, &self.radio2),
            2 => (&self.radio2, &self.radio1),
            _ => panic!("Invalid radio"),
        };

        // Guard: Only TX if other radio is not transmitting
        let other_state = other.atomic_state();
        let event = ScheduledEvent::new(start_ns, EventAction::StartTx)
            .with_guard(move |_| {
                !matches!(other_state.get(), RadioState::Transmitting)
            });

        sched.schedule(event);

        // Schedule stop
        sched.schedule(ScheduledEvent::new(
            start_ns + duration.as_nanos() as u64,
            EventAction::StopTx,
        ));
    }
}

use r4w_core::scheduler::TickScheduler;
use r4w_core::rt_scheduler::RealTimeScheduler;

// Use TickScheduler for protocol development
let sim_scheduler = TickScheduler::builder()
    .resolution(TickResolution::Millisecond(1))
    .build();

// Test your protocol logic with virtual time...

// Then switch to RealTimeScheduler for production
let rt_scheduler = RealTimeScheduler::builder()
    .clock_source(ClockSource::System)
    .build()?;

// Same events, just scheduled on real-time scheduler

use std::sync::Arc;
use std::thread;

let scheduler = Arc::new(RealTimeScheduler::builder().build()?);

// Scheduler thread
let sched_clone = scheduler.clone();
let handle = thread::spawn(move || {
    sched_clone.run().unwrap();
});

// Other threads can schedule events
let sched_clone = scheduler.clone();
thread::spawn(move || {
    loop {
        sched_clone.schedule(ScheduledEvent::new(
            sched_clone.now_ns() + 1_000_000,
            EventAction::StartTx,
        ).with_guard(|s| s.can_transmit()));

        thread::sleep(Duration::from_millis(100));
    }
});

// Stop from main thread
scheduler.stop();
handle.join().unwrap();

let scheduler = RealTimeScheduler::builder()
    // Tight timing (FHSS, TDMA)
    .deadline_tolerance(Duration::from_micros(100))
    // Relaxed timing (beacons, periodic TX)
    .deadline_tolerance(Duration::from_millis(5))
    .build()?;

use r4w_core::rt_scheduler::{EventError, RadioStateError};

let results = scheduler.process();
for result in results {
    match result {
        Ok(event) => { /* Success */ }
        Err(EventError::GuardBlocked) => {
            // Guard condition prevented execution
            // Event was consumed, may need to reschedule
        }
        Err(EventError::DeadlineMissed { deadline_ns, actual_ns }) => {
            // Event executed late
            let lateness = actual_ns - deadline_ns;
            eprintln!("Event late by {}ns", lateness);
        }
        Err(EventError::StateError(RadioStateError::InvalidTransition { from, to })) => {
            // State machine prevented transition
            eprintln!("Cannot go from {:?} to {:?}", from, to);
        }
        Err(e) => {
            eprintln!("Other error: {}", e);
        }
    }
}