🥮 mooncakes.io

    moonwheelkit

    A deterministic hierarchical timing wheel and virtual-time scheduler for MoonBit.

    scheduler
    timing-wheel
    virtual-time
    timer
    deterministic
    Download zip
    Version
    0.2.2
    License
    Apache-2.0
    Repository
    Last updated
    3 months ago
    Downloads
    49

    No dependencies

    #MoonWheelKit

    MoonWheelKit is a backend-neutral hierarchical timing wheel and deterministic virtual-time scheduler for MoonBit.

    #Install

    moon add brother-666/moonwheelkit

    Import the package as import "brother-666/moonwheelkit" @wheel.

    The core library does not read the system clock. Applications explicitly advance virtual time, which makes timer-heavy services, simulations and tests repeatable across native, JavaScript, WebAssembly and Wasm-GC backends.

    For recovery storms, advance_late_budgeted(target, max_fires) bounds total emissions across all due timers. Remaining due work stays pending and can be drained by calling the method again at the same target tick.

    ///|
    test "schedule with deterministic virtual time" {
      let wheel = @moonwheelkit.Wheel::new()
      ignore(wheel.schedule(@moonwheelkit.TimerSpec::once(3, "expire")))
      match wheel.advance_to(3) {
        @moonwheelkit.AdvanceResult::Advanced(report) => {
          assert_eq(report.fired.length(), 1)
          assert_eq(report.fired[0].payload, "expire")
        }
        @moonwheelkit.AdvanceResult::Rejected(_) =>
          fail("forward advance should succeed")
      }
    }

    match wheel.advance_late_budgeted(1000, 256) {
      @moonwheelkit.DrainResult::Drained(report) => {
        println(report.to_json())
        if report.exhausted {
          // Continue draining at tick 1000 in a later event-loop turn.
        }
      }
      @moonwheelkit.DrainResult::Rejected(_) => ()
    }

    See README.md for scheduling semantics, architecture, ecosystem comparison and reproducible verification commands.

    AdvanceReport

    source
    pub(all) struct AdvanceReport {
      from_tick : Int
      to_tick : Int
      scanned_ticks : Int
      cascades : Int
      fired : Array[FiredTask]
    } derive(Eq, 
    Debug    )

    AdvanceReport::to_json

    source
    fn AdvanceReport::to_json(self : AdvanceReport) -> String

    AdvanceResult

    source
    pub(all) enum AdvanceResult {
      Advanced(AdvanceReport)
      Rejected(ScheduleError)
    } derive(Eq, 
    Debug    )

    BucketEntry

    source
    type BucketEntry

    DrainReport

    source
    pub(all) struct DrainReport {
      from_tick : Int
      to_tick : Int
      budget : Int
      fired : Array[FiredTask]
      deferred_due : Int
      exhausted : Bool
    } derive(Eq, 
    Debug    )

    DrainReport::to_json

    source
    fn DrainReport::to_json(self : DrainReport) -> String

    DrainResult

    source
    pub(all) enum DrainResult {
      Drained(DrainReport)
      Rejected(ScheduleError)
    } derive(Eq, 
    Debug    )

    FiredTask

    source
    pub(all) struct FiredTask {
      timer_id : Int
      scheduled_at : Int
      observed_at : Int
      lateness : Int
      occurrence : Int
      payload : String
    } derive(Eq, 
    Debug    )

    FiredTask::to_json

    source
    fn FiredTask::to_json(self : FiredTask) -> String

    InternalTimer

    source
    type InternalTimer

    MaintenanceReport

    source
    pub(all) struct MaintenanceReport {
      removed_terminal_timers : Int
      removed_stale_entries : Int
      retained_pending_timers : Int
    } derive(Eq, 
    Debug    )

    RepeatMode

    source
    pub(all) enum RepeatMode {
      Once
      FixedDelay
      FixedRate
    } derive(Eq, 
    Debug    )

    ScheduleError

    source
    pub(all) enum ScheduleError {
      InvalidDelay
      InvalidPeriod
      InvalidConfiguration
      InvalidBudget
      UnknownTimer
      TimeWentBackwards
      SnapshotMismatch
    } derive(Eq, 
    Debug    )

    TimerInfo

    source
    pub(all) struct TimerInfo {
      id : Int
      deadline : Int
      period : Int
      repeat : RepeatMode
      payload : String
      state : TimerState
      sequence : Int
      generation : Int
      occurrence : Int
    } derive(Eq, 
    Debug    )

    TimerInfo::to_json

    source
    fn TimerInfo::to_json(self : TimerInfo) -> String

    TimerResult

    source
    pub(all) enum TimerResult {
      Accepted(Int)
      Rejected(ScheduleError)
    } derive(Eq, 
    Debug    )

    TimerSnapshot

    source
    pub(all) struct TimerSnapshot {
      now : Int
      next_id : Int
      next_sequence : Int
      fired_total : Int
      scheduled_total : Int
      cascades_total : Int
      config : WheelConfig
      timers : Array[TimerInfo]
    } derive(Eq, 
    Debug    )

    TimerSnapshot::to_json

    source
    fn TimerSnapshot::to_json(self : TimerSnapshot) -> String

    TimerSpec

    source
    pub(all) struct TimerSpec {
      delay : Int
      period : Int
      repeat : RepeatMode
      payload : String
    } derive(Eq, 
    Debug    )

    TimerSpec::fixed_delay

    source
    fn TimerSpec::fixed_delay(delay : Int, period : Int, payload : String) -> TimerSpec

    TimerSpec::fixed_rate

    source
    fn TimerSpec::fixed_rate(delay : Int, period : Int, payload : String) -> TimerSpec

    TimerSpec::once

    source
    fn TimerSpec::once(delay : Int, payload : String) -> TimerSpec

    TimerState

    source
    pub(all) enum TimerState {
      Pending
      Cancelled
      Fired
    } derive(Eq, 
    Debug    )

    ValidationIssue

    source
    pub(all) struct ValidationIssue {
      code : String
      timer_id : Int
      message : String
    } derive(Eq, 
    Debug    )

    Wheel

    source
    pub struct Wheel {
      config : WheelConfig
      current_tick : Int
      next_id : Int
      next_sequence : Int
      timers : Map[Int, InternalTimer]
      buckets : Array[Array[BucketEntry]]
      fired_total : Int
      scheduled_total : Int
      cascades_total : Int
    }

    Wheel::advance_by

    source
    fn Wheel::advance_by(self : Wheel, delta : Int) -> AdvanceResult

    Wheel::advance_late_budgeted

    source
    fn Wheel::advance_late_budgeted(self : Wheel, target : Int, max_fires : Int) -> DrainResult

    Jumps virtual time while bounding the total number of emitted tasks.

    Due timers are selected globally by (deadline, timer_id). When the budget is exhausted, remaining due timers stay pending and can be drained by calling this method again with the same target.

    Wheel::advance_late_to

    source
    fn Wheel::advance_late_to(self : Wheel, target : Int) -> AdvanceResult

    Wheel::advance_to

    source
    fn Wheel::advance_to(self : Wheel, target : Int) -> AdvanceResult

    Wheel::cancel

    source
    fn Wheel::cancel(self : Wheel, id : Int) -> Bool

    Wheel::compact

    source
    fn Wheel::compact(self : Wheel) -> MaintenanceReport

    Wheel::config

    source
    fn Wheel::config(self : Wheel) -> WheelConfig

    Wheel::get

    source
    fn Wheel::get(self : Wheel, id : Int) -> TimerInfo?

    Wheel::new

    source
    fn Wheel::new(config? : WheelConfig) -> Wheel

    Wheel::now

    source
    fn Wheel::now(self : Wheel) -> Int

    Wheel::pending

    source
    fn Wheel::pending(self : Wheel) -> Int

    Wheel::reschedule

    source
    fn Wheel::reschedule(self : Wheel, id : Int, delay : Int) -> TimerResult

    Wheel::restore

    source
    fn Wheel::restore(snapshot : TimerSnapshot) -> Wheel?

    Wheel::schedule

    source
    fn Wheel::schedule(self : Wheel, spec : TimerSpec) -> TimerResult

    Wheel::snapshot

    source
    fn Wheel::snapshot(self : Wheel) -> TimerSnapshot

    Wheel::stats

    source
    fn Wheel::stats(self : Wheel) -> WheelStats

    Wheel::timers

    source
    fn Wheel::timers(self : Wheel) -> Array[TimerInfo]

    Wheel::validate

    source
    fn Wheel::validate(self : Wheel) -> Array[ValidationIssue]

    WheelConfig

    source
    pub(all) struct WheelConfig {
      tick_ms : Int
      slots_per_level : Int
      levels : Int
      max_catch_up : Int
    } derive(Eq, 
    Debug    )

    WheelConfig::is_valid

    source
    fn WheelConfig::is_valid(self : WheelConfig) -> Bool

    WheelConfig::standard

    source
    fn WheelConfig::standard() -> WheelConfig

    WheelStats

    source
    pub(all) struct WheelStats {
      now : Int
      pending : Int
      cancelled : Int
      fired_total : Int
      scheduled_total : Int
      cascades_total : Int
      levels : Int
      slots_per_level : Int
    } derive(Eq, 
    Debug    )

    WheelStats::to_json

    source
    fn WheelStats::to_json(self : WheelStats) -> String

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io