Module shard 

Shard state.

A shard owns a slice of the workflow ID space, one log and the state derived from it. ShardCore::apply is the only state transition: it is called for every record as it is appended, and again for every record read back during recovery, so live state and recovered state cannot drift.

The core does no I/O and reads no clock. It emits Events for the host (a timer fired, a signal matched a wait, a run started or finished) and queues Outputs that may leave the process only once the record that produced them is durable: ShardCore::release hands them out as the durable position advances.

Runs are either loaded (full state and journal in memory) or parked (a 32-byte entry in the RunTable pointing at its frame in the run store, with its earliest timer). Suspended and finished runs are parked so memory does not grow with idle work; the host loads a parked run back whenever a record for it must be appended.

Timers. The wheel holds only timers due within HORIZON_MS. A later timer waits in its run’s table entry, and each chunk of 4,096 entries is a time bucket that knows its earliest waiting timer. Once that comes within the horizon, the sweep walks the chunk and moves what is due within it into a wheel (loaded runs into the timer wheel, parked runs into a wheel of loads). So a sleeping population costs its table entries and nothing per timer, and no work until its timers approach.

Structs

BlobRef

Location of a blob in the run store.

LoadedRun

A run held in memory.

Mode

NewestFirst

A shard’s runs from the highest run number down: the newest start first, since a shard numbers its runs in the order they start. (After a reshard, runs that had to be renumbered count as newer than they are.)

ParkedRun

A parked run as its table entry describes it. Everything else (its last LSN included) is in its frame.

ShardCore

TimerKey

UpdateSlot

An accepted update of a loaded run.

Enums

Event

Something the host must act on.

Found

What a run lookup by workflow ID found.

Output

Something that may leave the process once its record is durable.

TimerKind

Constants

CANCEL_SIGNAL

The reserved signal name ctx.cancelWorkflow sends.

HORIZON_MS

Timers due later than this wait in their run’s table entry instead of a wheel. A sweep walks the table once per half horizon.

SPARE_RUNS_IDLE

Emptied runs kept once a shard is idle.

TIMER_CHUNK

At most this many due timers fire per ShardCore::poll_timers. The rest stay due for the next call, so a mass wake is loaded, driven and flushed in chunks instead of loading every run before the first one continues.

Functions

send_dedup

Dedup key for a signal sent by a workflow, stable across resends. Never 0, which means “no key”.

shard_of

The shard a workflow ID belongs to.