Fibers
A fiber is one running generator. Every dispatch has a root fiber, whose id is the action's ActionId, and every element of a parallel or parallelSettled yield runs as a branch. A fiber ends completed, errored or cancelled.
Usage
Concurrency inside an action is parallel and parallelSettled, and nothing a branch starts outlives the yield that started it; other work is a start. The patterns stop stale work by replacing its entity and cleanup that must survive a stop belongs to a resource build on this page.
parallel and parallelSettled
yield* parallel(g1, g2, ...) runs each generator as a branch, and resumes with their results in order once every branch has ended:
const [users, posts] = yield* parallel(loadUsers(), loadPosts());A failing branch stops the others, and parallel rethrows once they have ended. A stopped branch runs its finally blocks and nothing else, and one not yet started never starts. So a catch around the parallel can rely on every branch having ended, its finally blocks included.
yield* parallelSettled(g1, g2, ...) is for branches that must all finish. No failure stops another, and the action resumes with one outcome per branch, in order, typed IBranchOutcome<R>: { ok: true, value } or { ok: false, error }.
const [users, posts] = yield* parallelSettled(loadUsers(), loadPosts());
if (users.ok) draft.Users = users.value;
if (!posts.ok) draft.PostsFailed = true;Stopping
A fiber is stopped, told to end, when:
- its action's entity leaves the tree, or
runtime.dispose()runs (removal); - a
latestarrival replaces its action; - a sibling branch of a
parallelfailed.
A stop is silent: the runtime never throws into the generator, so no catch sees an AbortError, and a stop takes no failure route. In try { ... } catch { ... } finally { ... }, the catch never runs for a stop and the finally does. A finally in an action doesn't yield (the close).
Work entities
Work whose end must clean up state gets an entity of its own, and the work is started on it, so it is owned by, and ends with, that row:
export function* startUpload(draft: IUploads, name: string): IActionGenerator {
const upload = yield* entity<IUpload>({ Name: name, Progress: 0 });
draft.Uploads.push(upload);
yield* start(runUpload, upload);
}
export function* runUpload(draft: IUpload): IActionGenerator {
draft.Progress = yield* sendFile(draft.Name);
yield* publishToNearest(draft, "Upload/Done", { UploadId: draft.$Id });
}
export function* cancelUpload(draft: IUploads, uploadId: string): IActionGenerator {
draft.Uploads = draft.Uploads.filter((u) => u.$Id !== uploadId);
}Cancelling is the removal: the cascade stops runUpload, abandons any ask the row owns, and drops its timers and resources. The worker writes only its own row, so everything it seated goes with it. What it hands elsewhere, a message or a start on another entity, belongs to whoever receives it.
Rules
Records
The records name fibers: action:start and action:end for a root, branch:start and branch:end for a branch, with ParentBranchId and BranchId (records).
Fan-out results
parallel's error is the first branch's to fail; each failing branch's error stays on itsbranch:endrecord.- A
parallelSettledbranch's failure is only an outcome: it takes no route unless the action rethrows it. - A fiber waiting on either stops its branches when it is stopped, and theirs in turn. A branch can start branches of its own the same way.
Branches and the hold
Branches run under the action's hold, and read and write the draft. Only the action's own branches can change what a branch read across its wait.
A branch runs inside
open(...)or not, as its fan-out does, and can't change that.parallelandparallelSettledtake only generators withoutopen's marker, and anopen(...)typedanyin a branch throws a refusal before its body runs. A branch can't ask either.Inside
open(parallel(...)), each branch's first step runs under the hold, so each reads what it needs before its wait. From the first wait until theopenends, a branch's draft throwsDraftInsideOpenError, as the action's own does. So the branches of an open fan-out return what they read, and the action writes after:tsconst [preview, parts] = yield* open(parallelSettled(fetchPreview(id), fetchParts(id))); if (preview.ok) doc.Preview = preview.value; if (parts.ok) doc.Parts = parts.value;The fan-outs are runtime operations: no implementation or stub can take their names. Test the branches' own effects instead.
What a stop does
A fiber is also stopped when the fiber waiting on its fan-out was stopped, and when the resource running its r.run retires (live sources).
A stopped fiber stops waiting and closes a microtask later. Nothing after the wait runs, a rejection never reaches a catch, and the close runs its finally blocks. It ends cancelled, and a root's promise resolves undefined.
A throw from a stopped action's finally depends on whether its entity is still in the tree. After a latest replacement it is, so the throw takes the action's failure route, with Status: "cancelled" and Close: true on the failure event. After the entity's removal nothing can take it: it reports action/unrouted-throw, the failure event says Taken: false, and the promise still resolves undefined (failure).
- An effect in flight is left running, and its result goes nowhere. Its context's
signalfires, and the implementation decides what that means for its work (effects). Itseffectrecord gets noresponse. - An ask the fiber waits on is abandoned with
Reason: "cancelled", ahead of the close. - A stop doesn't undo writes the fiber already made, doesn't stop actions it started or receivers its messages reached, and never fires on completion or on the action's own throw.
The close
A stop, and a throw that reaches a fiber outside its own code, close its generator with return(), which runs its finally blocks innermost first. Nothing dispatches in a close.
yield* transient(...)returns the transient without yielding. With the owner gone, it returns a throwaway, so writes through it reach nothing.- Any other yield reports
cancel/finally-yieldand is answered with anotherreturn(), so the rest of thatfinallyblock is skipped and the blocks outside it still run. - A
finallythat throws leaves the blocks outside it to run. - Draft writes in the close are allowed, journaled as one
steprecord stampedCancelling: true. In a stopped fiber they reach the nodes it last held, gone or not, withoutDraftDetachedError(held references). While the action is let go insideopen(...), a draft write throwsDraftInsideOpenError. - The close is one unit for the tree rule: a
finallythat breaks it undoes every block in the close, and the refusal is reported as a throw from the close.
The treflex/no-yield-in-finally lint rule reports a yield in a finally in the source.
| How the fiber ends | catch runs | finally runs |
|---|---|---|
| The body returns | No | In the body's own step |
| The action's own code throws, an effect's rejection included | Yes | In the body's own step |
| A stop | No | In the close |
A throw outside the action's code after a step, such as a view effect outside any TreflexProvider throwing in the step's flush | No | In the close, and the fiber ends errored |
Cleanup belongs to the survivors
Before writing cleanup that runs when an action is stopped, ask who can see it. A stop from removal has no audience: the entity has left the tree, no view renders it, and a "mark it cancelled" write in a finally is unobservable. A cancel-conditional guard in a finally, such as if (draft.Status === "running") draft.Status = "cancelled", is the sign.
- Compensation, notifications and status belong to the live actor that caused the removal, or to a surviving ancestor.
- Progress a survivor might need goes into state as the work proceeds, not into locals.
- Something live is a resource, closed where its ending is handled.
A finally shared by completion and failure is fine. Errors never need cancel logic: a catch always starts as live code, where effects dispatch normally.
Work entity rules
- The row is state, and the started action is not. A restore brings the row back without the action, so the owner sweeps or re-drives it (restart). Write progress to the row as the work goes, and a restored row says how far it got.
- A pause is state too. Nothing makes a fiber wait from outside, and fibers don't survive a restore, so a pause is a flag in the tree the orchestrator checks before starting the next piece. A task graph is the same shape: each node's run is a work entity, its completion is a message, and the run's receiver starts each node whose inputs are done.
- A mark that only says work is running on an entity that outlives the work is a transient or
inFlight, not a work entity.
What reports a broken rule
| Rule | Reported by |
|---|---|
| A branch can't open | The compiler, and a refusal for open(...) typed any |
| A branch can't ask | AskRefusedError |
| A branch of an open fan-out doesn't use the draft after its wait | DraftInsideOpenError |
| Nothing replaces a fan-out | Registering or stubbing parallel or parallelSettled throws |
A finally in an action doesn't yield | treflex/no-yield-in-finally lint, and cancel/finally-yield during a close |
A stopped branch's finally throws | action/unrouted-throw |
| Cleanup on a stop belongs to the survivors | Nothing: a write nobody can see is a valid write |
| An implementation that loops checks its signal | Nothing |
Caveats
- A throw from a stopped branch's
finallyisn't routed: it is reported asaction/unrouted-throw(failure). - A late rejection from an effect a stop left running is absorbed.
- Get a transient before the
try, so thefinallydoesn't yield at all: a stop that lands during the fiber's own step, such as from a view reacting to its write, isn't a close yet, so it takes atransientyield in afinallyas an ordinary yield and skips the rest of that block, unreported. - After 100 yields in a close the generator is abandoned with
cancel/finally-yield-limit, the rest of itsfinallyblocks unrun. - The yield in a
finallydispatches normally on completion and on the action's own throw, so the runtime can only report it during a close. Turn ontreflex/no-yield-in-finally. - A branch stopped by a sibling's failure dies while its entity lives, so its
finallywrites are visible. Even then, prefer the action that catches the fan-out's failure. - A message a worker sent before its removal is still delivered. An owner that must ignore a removed worker's results checks the sender against the rows it holds, as
ctx.publisher.Idin its receiver case. - The cost of a work entity is an index entry and a cascade per item.