Skip to content

feat: high-resolution timer wheel for scheduled Soroban executions (#56)#91

Merged
elizabetheonoja-art merged 1 commit into
Utility-Protocol:mainfrom
real-venus:feat/timer-wheel-scheduler
Jun 26, 2026
Merged

feat: high-resolution timer wheel for scheduled Soroban executions (#56)#91
elizabetheonoja-art merged 1 commit into
Utility-Protocol:mainfrom
real-venus:feat/timer-wheel-scheduler

Conversation

@real-venus

Copy link
Copy Markdown
Contributor

High-Resolution Timer Wheel for Scheduled Soroban Executions (#56)

Closes #56

What's included

File Responsibility
src/types/scheduler.ts Invariants (1024 slots × 100 ms ≈ 102.4 s span, 1,000-job cap, ±50 ms tolerance, 200 ms fallback), job/meta/status types, the SAB Int32 layout, and the worker protocol.
src/utils/sharedBuffer.ts SharedArrayBuffer creation + atomic drift/heartbeat/command accessors, COOP/COEP availability check, and futexWait/futexNotify that degrade safely on a non-shared buffer.
src/utils/timerWheelCore.ts The pure hashed wheel: jobs hashed into slots with a rounds counter for >1-rotation targets, and a pending set so sub-slot jobs are never skipped. schedule/cancel/advance with recurrence, drift correction, missed-fire detection, and the 1,000-job cap.
src/workers/timerWheel.worker.ts Holds the wheel and sleeps each tick on Atomics.wait(HEARTBEAT, …, 100ms) (woken early by command notifies; timed-loop fallback without SAB), advances using Date.now(), and posts fired jobs.
src/services/timerWheel.ts Main-thread facade: worker path or a 200 ms polling fallback, plus a requestAnimationFrame loop that writes a drift correction into the buffer while the tab is hidden.
src/hooks/useScheduledExecution.ts Wraps the service, mirrors metadata into the store, and auto-cancels on unmount.
src/store/slices/scheduleSlice.ts Job metadata (next fire, status, missed count) with selectors.
src/components/dashboard/SchedulerDashboard.tsx Jobs table (name / next fire / interval / status / missed / cancel).
tests/unit/* Wheel ordering, rounds, recurrence (no catch-up storm), cancel, capacity, precision/missed, drift; atomic buffer round-trips; and the schedule store.

…tility-Protocol#56)

Schedules up to 1,000 recurring contract executions with ms precision that keeps
firing while the tab is throttled, via a Web Worker ticking on a SharedArrayBuffer.

- types/scheduler.ts: wheel invariants (1024 slots x 100ms, 1000-job cap, +/-50ms
  tolerance, 200ms fallback), job/meta/status types, SAB Int32 layout, worker
  protocol
- utils/sharedBuffer.ts: SharedArrayBuffer creation + atomic drift/heartbeat/
  command helpers, availability check (COOP/COEP), futexWait/notify with
  non-shared fallback
- utils/timerWheelCore.ts: pure hashed wheel (rounds + pending set so sub-slot
  jobs are never skipped); schedule/cancel/advance with recurrence, drift
  correction, missed-fire detection, and the 1000-job cap
- workers/timerWheel.worker.ts: holds the wheel, sleeps each tick on
  Atomics.wait(HEARTBEAT, 100ms) (timed-loop fallback), advances and posts fired
  jobs; command channel via postMessage + Atomics.notify
- services/timerWheel.ts: main-thread facade — worker path or 200ms polling
  fallback, requestAnimationFrame drift loop writing correction while hidden
- hooks/useScheduledExecution.ts: wraps the service, mirrors metadata to the
  store, auto-cancels on unmount
- store/slices/scheduleSlice.ts: job metadata (next fire, status, missed count)
- components/dashboard/SchedulerDashboard.tsx: jobs table + cancel (component
  rather than src/pages since this is an App Router project)
- tests for the wheel (ordering, rounds, recurrence, cancel, cap, precision,
  drift), the atomic buffer helpers, and the schedule store
@elizabetheonoja-art elizabetheonoja-art merged commit c6847be into Utility-Protocol:main Jun 26, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

High-Resolution Timer Wheel for Scheduled Soroban Contract Executions with SharedArrayBuffer Timekeeping

2 participants