rtsched 0.2.0

A no_std runtime scheduler for Cortex-M thread management
Documentation
#![cfg_attr(not(test), no_std)]

//! Runtime scheduler primitives for `no_std` embedded applications.
//!
//! `rtsched` provides the core pieces needed to create, queue, block, wake, and
//! context-switch application threads on a single microcontroller core. It
//! combines CFS-style background scheduling with soft real-time scheduling built
//! on kernel timers ordered by deadline.
//!
//! Board crates own the hardware setup: clocks, timer interrupts,
//! architecture-specific context-switch entry points, stack storage, and
//! concrete thread storage. A typical board initializes the timer queue with
//! [`init_ktimer_queue`], configures CFS with [`init_cfs`], creates
//! [`CfsThread`] and [`RtThread`] values with their builders, and starts the
//! idle thread with [`spawn_main_thread`].
//!
//! The crate is `no_std` for embedded builds. Host-only test support provides
//! scheduler state serialization so the same core data structures can be
//! exercised by unit tests.
//!
//! # Scheduling Model
//!
//! - [`CfsThread`] uses a red-black-tree run queue ordered by virtual runtime.
//! - [`RtThread`] uses an [`RtKTimer`] entry for deadline-based scheduling.
//! - Waiting threads move through a wait queue and can be resumed by timer
//!   expiry or scheduler wake-up paths.
//! - [`handle_sched_tick`] advances timers and requests dispatch from the
//!   target-specific context-switch path.
//! - [`MessageQueue`] transfers copied FIFO messages between threads, with
//!   bounded inline storage and blocking or nonblocking send/receive operations.
//!
//! # Safety
//!
//! This crate exposes low-level scheduler entry points that operate on raw
//! pointers, intrusive queue links, global scheduler state, and
//! architecture-specific stack frames. Public `unsafe` functions document their
//! caller obligations individually. Board code must ensure thread and stack
//! storage outlives all scheduler use and that initialization happens before
//! scheduler interrupts can observe the global state.
//!
/// Crate version taken from Cargo metadata at compile time.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

mod arch;

/// Run `f` while scheduler globals are protected from interrupt or test-thread
/// interleaving.
///
/// On Cortex-M this delegates to the architecture platform interface, which
/// masks interrupts in a nest-safe way. Host tests use a reentrant mutex-backed
/// critical section so nested scheduler calls do not deadlock and parallel
/// tests still serialize global state access.
pub(crate) fn critical_section<R>(f: impl FnOnce() -> R) -> R {
    crate::arch::platform::critical_section(f)
}

mod clock;
mod diagnostics;
mod ktimer;
mod messageq;
#[doc(hidden)]
pub mod print;
mod rbtree;
mod runq;
mod sched;
mod sync;
mod thread;
mod waitq;

#[cfg(feature = "host")]
#[doc(hidden)]
pub mod test_support;

/// Re-exports of core scheduler primitives for convenient use in application code.
pub use thread::{
    AlignedStack, CfsSchedInfo, CfsThread, CfsThreadBuilder, IdleThread, RtThread, RtThreadBuilder,
    ThreadCtx, ThreadEntry, ThreadHandle, ThreadId, ThreadKind, ThreadRef, ThreadSpawnError,
    ThreadStart, ThreadState, current_rt_thread_runtime, current_thread, current_thread_id,
    msleepyi, yieldyi,
};

pub use clock::{sys_clk_freq, ticks_per_ms, update_sys_clk_freq};

pub use messageq::{MessageQueue, MessageQueueStatus};

pub use print::set_print_fn;

#[cfg(all(target_arch = "arm", not(feature = "host")))]
pub use arch::platform::CortexMPlatform;
#[cfg(feature = "host")]
pub use arch::platform::HostPlatform;

pub use arch::platform::{
    ContextSwitchPort, CriticalSectionPort, CycleCounterPort, DefaultPlatform,
    InitialThreadContext, Platform, SchedulerTimerPort, ThreadStackPort, dwt_cycle_count,
    get_elapse_cycles, get_elapse_msec, get_elapse_msec_since, init_dwt_cycle_counter,
    reset_elapse_counter, spawn_main_thread,
};

pub use ktimer::{RtKTimer, RtTiming, init_ktimer_queue, is_active_ktimer, next_ktimer_reload};

pub use diagnostics::ktimer::{traverse_ktimer_queue, traverse_ktimer_queue_fn};

pub use diagnostics::runq::traverse_run_queue_fn;

pub use sched::{handle_sched_tick, init_cfs, register_idle_thread};

pub use diagnostics::sched::traverse_idle_thread_fn;

pub use sync::{
    BinarySemaphore, CountingSemaphore, Mutex, MutexError, MutexGuard, SemaphoreError, SyncType,
};

pub use diagnostics::trace::{
    SchedIsrTiming, TraceCounters, TraceEvent, TraceFn, TraceThread, clear_trace_fn,
    mark_sched_tick_to_pendsv_start, reset_sched_tick_to_pendsv_max_ticks,
    reset_sched_tick_to_pendsv_min_max_ticks, reset_sched_tick_to_pendsv_min_ticks,
    reset_sched_tick_to_pendsv_timing, reset_trace_counters, sched_tick_to_pendsv_timing,
    set_trace_fn, trace_counters,
};

pub use diagnostics::waitq::traverse_wait_queue_fn;

pub use waitq::WaitQueueError;