Expand description
§rrkernel — a preemptive round-robin RTOS kernel with a no_std core
Zero dependencies. One API. Two kinds of machine:
- Bare metal (
no_std, Cortex-M): SysTick as the cycle-exact slice timer,PendSVfor the context switch, hand-written Thumb assembly for the register frame, and a user-chosen slice down to ~100 cycles. - Desktop (
std): identical ring, counters and life cycle on top of OS primitives — a one-shot timer plus real thread suspension on Windows,setitimer/SIGALRMplus hand-written x86-64 fiber switching on POSIX.
§The developer API
There is no scheduler_run(), no explicit yield, and no manual loop/exit
handling. Initialising the scheduler starts the timer engine immediately;
spawning links a task into the live ring and switches to it; returning from
a task’s function unlinks it and switches away.
use rrkernel::{scheduler, thread, Slice, SchedulerConfig};
fn main() {
// Choose the slice first: this is the timing contract.
scheduler::init_with(SchedulerConfig::embedded(Slice::Millis(1), 168_000_000)).unwrap();
// Task 1: CPU-bound, preempted automatically every slice.
thread::spawn(|| loop {
core::hint::spin_loop();
});
// Task 2: finishes its work, then the trampoline unlinks it, updates the
// pointers/counters and switches to the next task immediately.
thread::spawn(|| do_work());
}
fn do_work() {
// Tasks may spawn tasks at any time; the child is inserted into the
// running ring and gets the CPU on the next switch.
thread::spawn(|| { /* child task */ });
}§Scheduling contract
- Pure round robin. Every task has identical priority; the only knob is
the slice, which is set by the user at init (and can be retuned later with
scheduler::set_slice). - Fixed, full slices. Every switch re-arms the timer, so a task that exits early or a spawn that kicks the scheduler never shortens the next task’s slice and the period never drifts.
- O(1) unlink on completion.
(*prev).next = next; (*next).prev = prev,active_threads -= 1, then an immediate context switch. Dead tasks never accumulate in the ring, and their stacks are recycled by the deferred-free path on the next switch.
§Honest limits
Cycle-exact slices are a bare-metal property. On a desktop OS the slice
is bounded by the OS timer resolution (0.5–1 ms on Windows) and the jitter
by the OS scheduler — scheduler::stats and the jitter_bench example
measure it instead of pretending otherwise. On bare metal the switch costs
roughly 0.5–1 µs at 168 MHz and the jitter is a handful of cycles. There are
no priorities (so no priority inheritance) and no blocking primitives by
design, which also means a task’s worst-case lateness is (N-1) slices.
Re-exports§
pub use app_support::configure;pub use app_support::log_with;pub use time::deadline_add;pub use time::deadline_after;pub use time::now;pub use time::sleep;pub use time::sleep_hours;pub use time::sleep_minutes;pub use time::sleep_ms;pub use time::sleep_ns;pub use time::sleep_secs;pub use time::sleep_until;pub use time::sleep_us;pub use time::tick_ns;pub use time::ticks_for;pub use config::ConfigError;pub use config::PlatformLimits;pub use config::SchedulerConfig;pub use config::Slice;pub use event::park;pub use event::wait_until;pub use event::wake;pub use event::Signal;pub use event::Timeout;pub use event::WaitQueue;pub use event::WakeReason;pub use scheduler::block_for_ticks;pub use scheduler::block_until_tick;pub use scheduler::block_until_tick_if;pub use scheduler::current_id;pub use scheduler::deadline_after_ticks;pub use scheduler::main_body;pub use scheduler::sleep_until_tick;pub use scheduler::wake_first_blocked_on;pub use scheduler::wake_task;pub use scheduler::yield_now;pub use scheduler::BlockOutcome;pub use scheduler::SchedulerStats;pub use scheduler::TaskId;pub use scheduler::TaskInfo;pub use smp::CpuArch;pub use sync::LockError;pub use sync::LockId;pub use sync::Mutex;pub use sync::MutexGuard;pub use tcb::IdlePolicy;pub use tcb::KernelConfig;pub use tcb::Measure;pub use tcb::TaskControlBlock;pub use tcb::TaskState;pub use thread::spawn;pub use thread::spawn_with_stack;pub use thread::try_spawn;pub use thread::SpawnError;pub use thread::DEFAULT_STACK_SIZE;pub use tcb::KERNEL;
Modules§
- app_
support - The
app!facade: everything a Cortex-M application should not have to write. - arch
- Architecture / platform ports.
- arena
- Stack / TCB / closure arena with O(1)-ish recycling.
- closure
- Closure placement without a heap and without
alloc. - config
- User-facing scheduler configuration: the time slice you choose at init, plus the knobs the port needs.
- critical
- Critical sections: the one primitive every ring mutation depends on.
- event
- Events and waiting:
event::park,event::Signal,event::WaitQueue, and theevent::wait_untilpoll-yield fallback. Everything an I/O or async layer needs to block a task without burning its slice. Events:park,Signal,WaitQueue, and the poll-yield fallback. - exec
- The async layer:
exec::block_on, the taskWaker,Sleep. A.awaitthat returnsPendinggives up the slice exactly like a blocking call does. The async layer:block_on, the taskWaker, and async sleeps. - hal
embedded-hal/embedded-hal-asyncadapters: delays, the blocking facade over an async driver, and a kernel-mutex device for a bus shared between tasks.embedded-haladapters: delays, the blocking facade over an async driver, and a kernel-mutex device for a bus shared between tasks.- io
embedded-io/embedded-io-asyncbyte streams on top of an ISR-drivenevent::Signal.embedded-iobyte streams driven by an interrupt, without burning a slice while idle.- ring
- The automated doubly-linked circular task ring.
- scheduler
- Scheduler policy: who runs next, what the counters say, and how a finished task’s memory gets reclaimed.
- smp
- Architecture-agnostic multi-core support: core identity, cross-core interlocks and inter-processor interrupts.
- sync
- Sleeping locks need at least a word-wide atomic read-modify-write: the id allocator
and every lock’s owner word are atomics. Targets without one (Cortex-M0, AVR,
riscv32imc) simply do not get this layer — a mutex whose owner field cannot be updated atomically is not a mutex. Sleeping locks, static lock-order enforcement, and timeout/back-off recovery. - tcb
- Task Control Block and global kernel control state.
- thread
thread::spawn— the entire task-creation surface.- time
- Sleeping with units:
sleep,sleep_ms,sleep_secs, … built on absolute deadlines against the kernel’s global tick. Sleeping, with units. - trampoline
- Task life cycle: run the body, then tear the task down automatically.
Structs§
- Duration
core’sDuration, re-exported so an application needs one import for timekeeping:rrkernel::Duration::from_millis(250). ADurationtype to represent a span of time, typically used for system timeouts.
Functions§
- scheduler_
init - Start the scheduler with the default 1 ms slice — the convenient form of
scheduler::init_with. - scheduler_
init_ with - Start the scheduler with an explicit time slice (and other port knobs).
Attribute Macros§
- rrkernel
- Turn a
cortex-m-rtmaininto the kernel’s task 0.