36 - Fibers: Lightweight, Supervised Concurrency

Previous · Next

A fiber is the running execution of an Effect. Effect.all and friends manage fibers implicitly; the primitives in this step expose them.

Use them when you need to start work now and collect the result later, race two strategies, interrupt a long-running task, or run a daemon that outlives its parent.

What you’ll work through

index.test.ts walks the fiber API in the order you’ll reach for it: Effect.forkChild + Fiber.join, then Fiber.await for failure-as-data, then Fiber.interrupt, then Effect.race, and finally Effect.forkDetach for work that should outlive its parent.

By the end you should be able to choose between fork, forkDaemon, and the high-level Effect.all for any “run this in the background” situation, and know why a forked fiber is supervised whereas a daemon is not.

Fiber Lifecycle

1
Effect    immutable description of work (nothing is running)
2
Fiber     a live execution of an Effect
3

4
  Effect.forkChild(effect)        ──▶ Effect<Fiber<A, E>>     starts a child fiber
5
  Effect.forkDetach(effect)  ──▶ Effect<Fiber<A, E>>     starts an untethered fiber
6
  Fiber.join(fiber)          ──▶ Effect<A, E>            wait, re-raise failure
7
  Fiber.await(fiber)         ──▶ Effect<Exit<A, E>>      wait, observe Exit
8
  Fiber.interrupt(fiber)     ──▶ Effect<Exit<A, E>>      cancel safely, finalizers run
9

10
Supervision
11
  fork        ──▶ child is bound to its parent; parent completing interrupts child.
12
  forkDaemon  ──▶ child is bound to the global scope; survives the parent.

The supervision contract is what separates Effect.forkChild from setTimeout. A forked fiber cannot leak; its parent is responsible for it.

`Effect.forkChild` and `Fiber.join`

1
import { Effect, Fiber } from "effect"
2

3
//      ┌─── Effect<string>
4
//      ▼
5
const program = Effect.gen(function* () {
6
  const fiber = yield* Effect.forkChild(
7
    Effect.sleep("100 millis").pipe(Effect.as("result")),
8
  )
9
  return yield* Fiber.join(fiber)
10
})

fork schedules the effect on a new fiber and returns immediately. join waits for the fiber’s result, re-raising any failure into the calling fiber.

Notice. fork is non-blocking — the parent fiber continues on the next line. The fiber doesn’t run because you forked it; it runs because the runtime scheduled it. Joining is the only synchronisation point.

`Fiber.await`: Observe Without Throwing

1
//      ┌─── Effect<Exit<number, string>>
2
//      ▼
3
const exit = Fiber.await(fiber)

Returns the Exit value directly so success and failure can be inspected as data. Use this when failure is expected and you want to branch on it.

`Fiber.interrupt`

Interrupts a fiber cooperatively: the runtime cancels the fiber at the next yield point, and all attached finalizers run before the interruption propagates.

1
//      ┌─── Effect<void>
2
//      ▼
3
const stop = Effect.gen(function* () {
4
  const fiber = yield* Effect.forkChild(Effect.sleep("10 seconds"))
5
  yield* Fiber.interrupt(fiber)
6
})

Interrupted fibers produce an Exit whose cause is Interrupt. Inspect it with Cause (step 42) when you need to distinguish interruption from failure.

`Effect.race`

Runs two effects in parallel, returns the first success, interrupts the loser.

1
//      ┌─── Effect<string>
2
//      ▼
3
const result = Effect.race(
4
  Effect.succeed("fast"),
5
  Effect.sleep("1 second").pipe(Effect.as("slow")),
6
)

Details

The loser is interrupted, not abandoned. Its finalizers run.

This is the difference from Promise.race, which leaves the loser running invisibly.

`Effect.forkDetach`: Untethered Background Work

1
//      ┌─── Effect<Fiber<void, never>>
2
//      ▼
3
const heartbeat = Effect.forkDetach(
4
  Effect.repeat(
5
    Effect.log("alive"),
6
    Schedule.fixed("1 second"),
7
  ),
8
)

A daemon fiber is bound to the global scope, not its parent. It survives the parent fiber and is shut down only when the runtime terminates.

When to Use

For housekeeping work whose lifetime should match the application, not whichever request forked it.

> interrupt it, it runs until the runtime exits. Reach for it only when the > work genuinely outlives its parent — and pair it with explicit shutdown.

The forget-to-join mistake

Effect.forkChild starts a child fiber and returns immediately with a handle. The child runs inside its parent scope — if the parent finishes before the child does, the runtime interrupts the child to clean up. Without Fiber.join, the parent never observes the child’s result, and a slow child may be killed before it produces one.

1
import { Effect } from "effect"
2

3
// ✗ Parent finishes immediately; child gets interrupted before it can run.
4
const lossy = Effect.gen(function* () {
5
  const fiber = yield* Effect.forkChild(slowWork)
6
  // returning here without yield* Fiber.join(fiber)
7
})
8

9
// ✓ Join the child — parent waits for the result and re-raises failure.
10
const correct = Effect.gen(function* () {
11
  const fiber = yield* Effect.forkChild(slowWork)
12
  return yield* Fiber.join(fiber)
13
})

If you genuinely want fire-and-forget background work that outlives the parent, use Effect.forkDetach (covered in the daemon beat). Forking without joining inside an ordinary scope is almost always a bug.

Your turn read the lossy test and confirm the child's effect never lands. Then complete the partner test by inserting `yield* Fiber.join(...)` so the result is observed.

Composite Example: Race With Cleanup

1
//      ┌─── Effect<string>
2
//      ▼
3
const program = Effect.race(
4
  fetchFromCache(key),
5
  fetchFromDb(key),
6
)

If the cache wins, the in-flight DB query is interrupted and its connection released, for free, because the loser’s scope closes.

Rules of thumb

Fork only what should outlive the caller. For sequential work, stay in gen — forking adds bookkeeping you don’t need.
Every fork needs a join or interrupt. A forked fiber that no-one waits on or cancels is a leak. Prefer Effect.forkScoped to tie a fiber’s lifetime to a Scope.
Fibers are cheap. Spawn thousands. The cost model is closer to async tasks than to OS threads.

Common Pitfalls

1, Using Fiber.join when failure is expected. join re-raises; the calling fiber fails. For observation, use Fiber.await.

2, Confusing fork and forkDaemon. A forked fiber is interrupted when its parent completes. If you want background work that survives the request scope, use forkDaemon, but then you are responsible for shutdown.

3, Reaching for Effect.forkChild when Effect.all would do. For N independent tasks where you want all results, Effect.all with { concurrency: "unbounded" } is the higher-level API. Use explicit fibers when you need fine-grained control.

4, Forgetting that interruption is cooperative. A fiber stuck in a tight synchronous loop with no yield points cannot be interrupted. Insert Effect.yieldNow or split the work.

continues immediately after `fork` and only blocks at `join`. - [ ] Switch to `Fiber.await` and inspect the `Exit` — failure should be data, not a thrown error. Step 37 builds on this distinction. - [ ] Use `Fiber.interrupt` on a long-running fiber and observe the `Exit` carries an `Interrupt` cause, not a `Fail`. - [ ] Race two effects with `Effect.race` and confirm the loser is *interrupted*, not abandoned. - [ ] Finish with `Effect.forkDetach` — the daemon must be interrupted explicitly because it is not bound to the parent scope.

The full test suite

The index.test.ts for this lesson, verbatim from steps/36-fibers/.

1
import { describe, it, expect } from "vite-plus/test"
2
import { Effect, Fiber, Ref } from "effect"
3

4
// =============================================================================
5
// 40 - Fibers: Lightweight, Supervised Concurrency
6
// =============================================================================
7
//
8
// Effect.forkChild        Effect<A, E, R> => Effect<Fiber<A, E>, never, R>
9
// Effect.forkDetach  fiber bound to the global scope, survives the parent
10
// Fiber.join         wait for result, re-raise failure
11
// Fiber.await        wait for Exit, observe success/failure as a value
12
// Fiber.interrupt    cancel safely, finalizers run
13
// Effect.race        first success wins, loser is interrupted
14

15
describe("40 - Fibers", () => {
16
  // @beat
17
  //   id: fork-and-join
18
  //   shape: one-todo
19
  //   title: Fork a child fiber and join its result
20
  //   teaches: Effect.forkChild starts a child fiber; Fiber.join waits for the result and re-raises failure.
21
  //   hint: yield* Effect.forkChild(effect) returns a Fiber; yield* Fiber.join(fiber) collects the result
22
  describe("Effect.forkChild and Fiber.join", () => {
23
    it("forks a child fiber and joins its result", async () => {
24
      const program = /* @stub */ Effect.gen(function* () {
25
        const fiber = yield* Effect.forkChild(Effect.succeed(42))
26
        return yield* Fiber.join(fiber)
27
      }) /* @end */
28

29
      expect(await Effect.runPromise(program)).toBe(42)
30
    })
31

32
    it("runs the child concurrently with the parent", async () => {
33
      const log: Array<string> = []
34

35
      await Effect.runPromise(
36
        Effect.gen(function* () {
37
          const fiber = yield* Effect.forkChild(Effect.sync(() => log.push("background")))
38
          log.push("main")
39
          yield* Fiber.join(fiber)
40
        }),
41
      )
42

43
      expect(log).toContain("main")
44
      expect(log).toContain("background")
45
    })
46
  })
47

48
  // @end-beat
49

50
  // @beat
51
  //   id: await-and-interrupt
52
  //   shape: multi-todo
53
  //   title: Observe Exit and cancel safely
54
  //   teaches: Fiber.await returns an Exit (no throw on failure); Fiber.interrupt cancels cooperatively and runs finalizers.
55
  //   hint: Fiber.await for branching on _tag; Fiber.interrupt to cancel a sleeping fiber
56
  describe("Fiber.await", () => {
57
    it("returns an Exit without throwing on failure", async () => {
58
      const program = /* @stub */ Effect.gen(function* () {
59
        const ok = yield* Effect.forkChild(Effect.succeed(1))
60
        const bad = yield* Effect.forkChild(Effect.fail("oops"))
61
        return {
62
          ok: (yield* Fiber.await(ok))._tag,
63
          bad: (yield* Fiber.await(bad))._tag,
64
        }
65
      }) /* @end */
66

67
      const result = await Effect.runPromise(program)
68
      expect(result.ok).toBe("Success")
69
      expect(result.bad).toBe("Failure")
70
    })
71
  })
72

73
  describe("Fiber.interrupt", () => {
74
    it("cancels a running fiber and produces a Failure Exit", async () => {
75
      const program = /* @stub */ Effect.gen(function* () {
76
        const fiber = yield* Effect.forkChild(
77
          Effect.sleep("10 seconds").pipe(Effect.as("done")),
78
        )
79
        yield* Fiber.interrupt(fiber)
80
        const exit = yield* Fiber.await(fiber)
81
        return exit._tag
82
      }) /* @end */
83

84
      expect(await Effect.runPromise(program)).toBe("Failure")
85
    })
86
  })
87
  // @end-beat
88

89
  // @beat
90
  //   id: race
91
  //   shape: one-todo
92
  //   title: Race two effects, interrupt the loser
93
  //   teaches: Effect.race returns the first success; the losing fiber is interrupted and its scope closes — not abandoned like Promise.race.
94
  //   hint: Effect.race(slow, fast) returns "fast" and interrupts the slow branch
95
  describe("Effect.race", () => {
96
    it("returns the first success and interrupts the loser", async () => {
97
      const program = /* @stub */ Effect.race(
98
        Effect.sleep("100 millis").pipe(Effect.as("slow")),
99
        Effect.succeed("fast"),
100
      ) /* @end */
101

102
      expect(await Effect.runPromise(program)).toBe("fast")
103
    })
104
  })
105
  // @end-beat
106

107
  // @beat
108
  //   id: daemon
109
  //   shape: read-run
110
  //   title: forkDaemon outlives the parent scope
111
  //   teaches: Effect.forkDetach binds the child to the global scope — a regular fork inside Effect.scoped is interrupted when the scope closes; a daemon fiber survives and can be joined afterwards.
112
  //   hint: read both tests — scoped closes and interrupts the regular fork; the daemon's Fiber.join still resolves
113
  describe("Effect.forkChild vs Effect.all", () => {
114
    it("Effect.all is the high-level API for parallel results", async () => {
115
      const result = await Effect.runPromise(
116
        Effect.all([Effect.succeed(1), Effect.succeed(2), Effect.succeed(3)], {
117
          concurrency: "unbounded",
118
        }),
119
      )
120

121
      expect(result).toEqual([1, 2, 3])
122
    })
123

124
    it("fork/join gives fine-grained control — start now, join later", async () => {
125
      const program = Effect.gen(function* () {
126
        const a = yield* Effect.forkChild(Effect.succeed(10))
127
        const b = yield* Effect.forkChild(Effect.succeed(20))
128
        return (yield* Fiber.join(a)) + (yield* Fiber.join(b))
129
      })
130

131
      expect(await Effect.runPromise(program)).toBe(30)
132
    })
133
  })
134

135
  describe("Effect.forkDetach", () => {
136
    it("daemon fiber survives the scope that spawned it and can be joined later", async () => {
137
      // A regular fork inside Effect.scoped would be interrupted when the scope closes.
138
      // A forkDaemon is attached to the global scope instead, so it outlives its parent.
139
      const result = await Effect.runPromise(
140
        Effect.gen(function* () {
141
          const completed = yield* Ref.make(false)
142

143
          const daemonFiber = yield* Effect.scoped(
144
            Effect.gen(function* () {
145
              return yield* Effect.forkDetach(
146
                Effect.gen(function* () {
147
                  yield* Effect.sleep("5 millis")
148
                  yield* Ref.set(completed, true)
149
                }),
150
              )
151
            }),
152
          )
153

154
          // The scope has closed — the daemon is still running. Join to wait for it.
155
          yield* Fiber.join(daemonFiber)
156
          return yield* Ref.get(completed)
157
        }),
158
      )
159

160
      expect(result).toBe(true)
161
    })
162

163
    it("forkDaemon is the choice when a background task must outlive the current scope", async () => {
164
      // Contrast: with a regular fork you'd join *inside* the scope; with forkDaemon
165
      // the fiber is bound to the global scope and can be observed from anywhere.
166
      const log: Array<string> = []
167

168
      const program = Effect.gen(function* () {
169
        const fiber = yield* Effect.forkDetach(
170
          Effect.gen(function* () {
171
            log.push("daemon start")
172
            yield* Effect.sleep("5 millis")
173
            log.push("daemon end")
174
          }),
175
        )
176
        log.push("parent end")
177
        return fiber
178
      })
179

180
      const daemonFiber = await Effect.runPromise(program)
181
      await Effect.runPromise(Fiber.join(daemonFiber))
182

183
      expect(log).toContain("parent end")
184
      expect(log).toContain("daemon end")
185
    })
186
  })
187
  // @end-beat
188

189
  // @beat
190
  //   id: forget-to-join
191
  //   shape: multi-todo
192
  //   title: Fork starts the fiber — join collects its result
193
  //   teaches: Effect.forkChild starts a child fiber that is interrupted when the parent scope ends. Without Fiber.join, the parent cannot receive the child's result and the child may be interrupted before it finishes.
194
  //   hint: yield* Effect.forkChild(effect) returns a Fiber — yield* Fiber.join(fiber) waits for its result and returns the value
195

196
  describe("fork without join", () => {
197
    it("a forked fiber is interrupted when the parent exits without joining (read this)", async () => {
198
      const log: Array<string> = []
199

200
      await Effect.runPromise(
201
        Effect.gen(function* () {
202
          yield* Effect.forkChild(
203
            Effect.gen(function* () {
204
              yield* Effect.sleep("10 seconds") // long — would take forever
205
              log.push("background")           // never reached: parent exits first
206
            }),
207
          )
208
          // Parent returns here — structured concurrency interrupts the child
209
        }),
210
      )
211

212
      // Child was interrupted before appending to log
213
      expect(log).toEqual([])
214
    })
215

216
    it("Fiber.join keeps the parent alive until the child completes", async () => {
217
      const log: Array<string> = []
218

219
      await Effect.runPromise(
220
        /* @stub */ Effect.gen(function* () {
221
          const fiber = yield* Effect.forkChild(
222
            Effect.sync(() => {
223
              log.push("background")
224
            }),
225
          )
226
          yield* Fiber.join(fiber)
227
        }) /* @end */,
228
      )
229

230
      expect(log).toEqual(["background"])
231
    })
232
  })
233
  // @end-beat
234
})

07·02Fibers

36 - Fibers: Lightweight, Supervised Concurrency

What you’ll work through

Fiber Lifecycle

`Effect.forkChild` and `Fiber.join`

`Fiber.await`: Observe Without Throwing

`Fiber.interrupt`

`Effect.race`

`Effect.forkDetach`: Untethered Background Work

The forget-to-join mistake

Composite Example: Race With Cleanup

Rules of thumb

Common Pitfalls

See Also

The full test suite

07·02Fibers

36 - Fibers: Lightweight, Supervised Concurrency

What you’ll work through

Fiber Lifecycle

Effect.forkChild and Fiber.join

Fiber.await: Observe Without Throwing

Fiber.interrupt

Effect.race

Effect.forkDetach: Untethered Background Work

The forget-to-join mistake

Composite Example: Race With Cleanup

Rules of thumb

Common Pitfalls

See Also

The full test suite

`Effect.forkChild` and `Fiber.join`

`Fiber.await`: Observe Without Throwing

`Fiber.interrupt`

`Effect.race`

`Effect.forkDetach`: Untethered Background Work