Byte Engine Docs

Alley and lanes

Look up how an alley dispatch runs its lanes, what each collective section does, which lane runs it, what a lane waits for, and the limits and failure rules.

An alley runs one function on several lanes at once. One such run is a dispatch, and inside it the lanes meet in collective sections. This page specifies how a dispatch runs, what each section does, which lane runs it, what a lane waits for, and the limits and failure rules. For how the alley does this inside and why, read the Alley design note.

Dispatch

RuleBehavior
LanesA dispatch runs its function once on each lane. Lanes are numbered from 0. The alley's parallelism sets the lane count. A phased dispatch can run fewer lanes, and a dispatch that binds mutable resources runs at most one lane for each resource.
Calling threadRuns lane 0 unless the caller has work of its own in the dispatch, so the dispatch wakes one worker fewer. Lane 0 has no other role.
One laneRuns on the calling thread and meets no other lane.
ResultsOne value for each lane, in lane order. Results without size allocate nothing.
AllocationA dispatch allocates nothing for its sections.
OverlapA dispatch holds the alley until every lane and the caller finished, so dispatches never overlap.
Mutable resourcesEach resource bound to a dispatch belongs to one lane, which alone reaches it, without waiting for any other lane.
Idle workersBetween dispatches, a worker keeps checking for work for 100 µs, then sleeps until a dispatch wakes it.

Sections

SectionRuns its workWaitsReturns
EachEvery lane.At the end, every lane until every lane arrived.Every lane's value, in lane order.
Shared stageEvery lane, with shared access to the dispatch's resource.At the end, every lane until every lane arrived. No lane waits to enter.Every lane's value, in lane order.
Keyed stageEvery lane, with shared access, while every lane works on the same key, such as one batch.As a shared stage.As a shared stage.
BroadcastThe first lane to reach it.Every other lane, until the lane that runs it finished.Its value, on every lane.
Exclusive broadcastThe first lane to reach it, with exclusive access to the resource.As a broadcast.As a broadcast.
ClaimThe first lanes to reach it, as many as its limit. A limit of 0 runs it on no lane, and a limit of at least the lane count on every lane.No lane.Nothing.

Every lane must run the same sections in the same order, with the same kind, value type, key, and claim limit.

Progress

RuleBehavior
No leaderNo lane leads a dispatch. A lane never waits for a particular lane. It waits only where the section table says.
First to arriveThe first lanes to reach a broadcast or a claim run it, so a busy lane holds up a broadcast only while every lane is busy.
Entering a stageA lane starts its share of a shared or keyed stage as soon as it reaches it.
DriftLanes can be any number of broadcasts and claims apart. They meet again at the end of the next each section or stage.
WaitingA waiting lane checks for about 10 µs, then yields its thread between checks.

Agreement and failure

RuleBehavior
Exclusive and shared accessAn exclusive broadcast never runs while a lane has shared access to the resource. Lanes that would overlap fail the dispatch instead.
KeysLanes with different keys never run a keyed stage at the same time. They fail the dispatch instead.
MismatchLanes that run different sections, kinds, value types, keys, or numbers of sections fail the dispatch where they meet: at the end of an each section or stage, or at a broadcast. A lane that only passes broadcasts and claims after the other lanes finished can finish without noticing.
PanicA panic in a lane fails the dispatch.
Result of a failureThe dispatch returns once every lane and the caller finished, with the panic of the lane that failed it first.
After a failureA lane that catches the failure runs no further section. The alley stays usable.

Limits

LimitValue
Section value64 bytes at most, aligned to 64 bytes at most.
Sections with values32 in each dispatch. Sections whose value has no size don't count, so a dispatch runs any number of them.
Lanes in one claim65,535.
Claims when lanes driftA lane that reaches a claim after a lane ahead took a later broadcast or claim doesn't run it. Fewer lanes than the limit can run it then, but always at least one.

On this page