sched

Scheduled events and timers on the event loop. Arm a timer that fires a callback or posts a tick to a channel — after a relative duration, at an absolute tz-aware instant, on a recurring cadence (fixed-delay or fixed-rate), against a recurrence rule, or on a cron schedule — then cancel it or observe its state. Timers can be made durable so they survive a process restart (persisted to a journal and re-armed via restore), apply a catch-up policy for occurrences missed while down, and run under a manual test clock that advances virtual time deterministically. It composes time, journal, and the shared event loop, adding no calendar grammar, persistence mechanism, or new capability of its own.

sched:after

[$sched:after] -> element — Fire an event once after a relative duration; returns a cancelable timer handle.

            [?lib 'cx-stdlib/sched']
[?lib 'cx-stdlib/time']
[?let [= $ch [?channel name="ticks" buffer=4]]
[= $t [$sched:after [$time:duration-m 10] $ch]]
[= $s0 [$sched:timer-state $t]]
[= $_ [$sched:test-clock-advance [$time:duration-m 10]]]
[seq $s0 [$sched:timer-state $t] [?receive from=$ch]]]
          
            [seq 'armed' 'fired' [tick timer=timer-1]]

sched:at

[$sched:at] -> element — Fire an event once at an absolute tz-aware instant; a past instant fires on the next loop turn.

            [?lib 'cx-stdlib/sched']
[?lib 'cx-stdlib/time']
[?let [= $ch [?channel name="t" buffer=4]]
[= $t [$sched:at [$time:datetime 1970 1 1 0 10 0] $ch]]
[= $s0 [$sched:timer-state $t]]
[= $_ [$sched:test-clock-advance [$time:duration-m 10]]]
[seq $s0 [$sched:timer-state $t] [?receive from=$ch]]]
          
            [seq 'armed' 'fired' [tick timer=timer-1]]

sched:every

[$sched:every] -> element — Fire repeatedly on a recurring cadence (fixed-delay or fixed-rate) until canceled.

            [?lib 'cx-stdlib/sched']
[?lib 'cx-stdlib/time']
[?let [= $ch [?channel name="t" buffer=16]]
[= $t [$sched:every [$time:duration-m 1] $ch]]
[= $_ [$sched:test-clock-advance [$time:duration-m 5]]]
[= $a [?receive from=$ch]]
[= $b [?receive from=$ch]]
[= $c [?receive from=$ch]]
[= $d [?receive from=$ch]]
[= $e [?receive from=$ch]]
[seq [$sched:timer-state $t] $a $b $c $d $e]]
          
            [seq 'armed' [tick timer=timer-1] [tick timer=timer-1] [tick timer=timer-1] [tick timer=timer-1] [tick timer=timer-1]]

sched:recur

[$sched:recur] -> element — Fire on each occurrence of a time recurrence rule, stopping at its COUNT/UNTIL bound.

            [?lib 'cx-stdlib/sched']
[?lib 'cx-stdlib/time']
[?let [= $ch [?channel name="t" buffer=16]]
[= $r [$time:recurrence :daily '1970-01-01T00:00:00Z' 'UTC' {count: 3}]]
[= $t [$sched:recur $r $ch {on-missed: :fire-all}]]
[= $_ [$sched:test-clock-advance [$time:duration-d 10]]]
[= $a [?receive from=$ch]]
[= $b [?receive from=$ch]]
[= $c [?receive from=$ch]]
[seq [$sched:timer-state $t] $a $b $c]]
          
            [seq 'fired' [tick timer=timer-1] [tick timer=timer-1] [tick timer=timer-1]]

sched:cron

[$sched:cron] -> element — Fire on a cron schedule by parsing the expression into a recurrence rule, then behaving as recur.

            [?lib 'cx-stdlib/sched']
[?lib 'cx-stdlib/time']
[?let [= $ch [?channel name="t" buffer=4]]
[= $t [$sched:cron "0 0 * * *" $ch]]
[= $_ [$sched:test-clock-advance [$time:duration-d 1]]]
[seq [$sched:timer-state $t] [?receive from=$ch]]]
          
            [seq 'armed' [tick timer=timer-1]]

sched:cancel

[$sched:cancel] -> bool — Cancel an armed timer, returning true iff a fire was prevented; idempotent.

            [?lib 'cx-stdlib/sched']
[?lib 'cx-stdlib/time']
[?let [= $ch [?channel name="t" buffer=4]]
[= $t [$sched:after [$time:duration-m 10] $ch]]
[= $c [$sched:cancel $t]]
[= $_ [$sched:test-clock-advance [$time:duration-m 10]]]
[seq $c [$sched:timer-state $t]]]
          
            [seq true 'canceled']

sched:timer-state

[$sched:timer-state] -> string — Read a timer's current state — armed, fired, or canceled.

            [?lib 'cx-stdlib/sched']
[?lib 'cx-stdlib/time']
[?let [= $ch [?channel name="ticks" buffer=4]]
[= $t [$sched:after [$time:duration-m 10] $ch]]
[= $s0 [$sched:timer-state $t]]
[= $_ [$sched:test-clock-advance [$time:duration-m 10]]]
[seq $s0 [$sched:timer-state $t] [?receive from=$ch]]]
          
            [seq 'armed' 'fired' [tick timer=timer-1]]

sched:restore

[$sched:restore] -> element — Re-arm durable timers from a journal after a restart, binding fire values from a registry.

            [?lib 'cx-stdlib/sched']
[?lib 'cx-stdlib/journal']
[?lib 'cx-stdlib/time']
[?let [= $ch [?channel name="t" buffer=4]]
[= $jr [$journal:open "mem://sched" "tenant"]]
[= $t [$sched:after [$time:duration-m 10] $ch {name: 'win' durable: $jr}]]
[$sched:restore $jr {'win': $ch}]]
          
            [restore-report rearmed=1 skipped=0 orphaned=0]

sched:test-clock-advance

[$sched:test-clock-advance] -> null — Advance the manual virtual clock and fire every timer now due, in deadline order.

            [?lib 'cx-stdlib/sched']
[?lib 'cx-stdlib/time']
[?let [= $ch [?channel name="ticks" buffer=4]]
[= $t [$sched:after [$time:duration-m 10] $ch]]
[= $s0 [$sched:timer-state $t]]
[= $_ [$sched:test-clock-advance [$time:duration-m 10]]]
[seq $s0 [$sched:timer-state $t] [?receive from=$ch]]]
          
            [seq 'armed' 'fired' [tick timer=timer-1]]

sched:clock-mode

[$sched:clock-mode] -> string — Read the loop's current clock source — wall or manual.

            [?lib 'cx-stdlib/sched']
[$sched:clock-mode]
          
            ':manual'