Tracking Fibers

Effect provides two structured-concurrency primitives for tracking groups of fibers: FiberSet for an unkeyed collection and FiberMap for a collection keyed by an arbitrary value. Both automatically remove fibers when they complete and interrupt any remaining fibers when their owning Scope closes.

Tracking Fibers with FiberSet

A FiberSet<A, E> collects fibers so they can be observed, joined, or interrupted together. You add fibers to it with FiberSet.run (fork an effect and track the resulting fiber) or FiberSet.add (track a fiber you already forked), and inspect it with FiberSet.size or by iterating over it directly.

Example (Monitoring Fiber Count)

In this example, we periodically monitor the number of fibers running in the application while calculating a Fibonacci number. The program forks two child fibers for every recursive step, adding each to a shared FiberSet, while a separate monitor fiber logs the set’s size on a schedule until the calculation finishes.

1
import { Console, Effect, Fiber, FiberSet, Schedule } from "effect"
2

3
// Main program that monitors fibers while calculating a Fibonacci number
4
const program = Effect.gen(function* () {
5
  // Create a FiberSet to track child fibers
6
  const set = yield* FiberSet.make<number>()
7

8
  // Start a Fibonacci calculation, forking every recursive step into the set
9
  const fibFiber = yield* Effect.forkChild(fib(10, set))
10

11
  // Start monitoring the fibers, logging the FiberSet's size every 20ms
12
  const monitorFiber = yield* Effect.forkChild(
13
    monitorFibers(set).pipe(Effect.repeat(Schedule.spaced("20 millis"))),
14
  )
15

16
  // Wait for the Fibonacci calculation to finish, then stop the monitor
17
  const result = yield* Fiber.join(fibFiber)
18
  yield* Fiber.interrupt(monitorFiber)
19

20
  console.log(`fibonacci result: ${result}`)
21
  // The final result is deterministic even though the intermediate
22
  // "number of fibers" logs above are racy and vary between runs
23
  result // => 55
24
}).pipe(Effect.scoped)
25

26
// Function to monitor and log the number of active fibers
27
const monitorFibers = (set: FiberSet.FiberSet<number>) =>
28
  Effect.gen(function* () {
29
    const count = yield* FiberSet.size(set) // Get the current number of tracked fibers
30
    console.log(`number of fibers: ${count}`)
31
  })
32

33
// Recursive Fibonacci calculation, adding a fiber to the set for each recursive step
34
const fib = (
35
  n: number,
36
  set: FiberSet.FiberSet<number>,
37
): Effect.Effect<number> =>
38
  Effect.gen(function* () {
39
    if (n <= 1) {
40
      return n
41
    }
42
    yield* Effect.sleep("30 millis") // Simulate work by delaying
43

44
    // Fork two fibers for the recursive Fibonacci calls, tracked by the FiberSet
45
    const fiber1 = yield* FiberSet.run(set, fib(n - 2, set))
46
    const fiber2 = yield* FiberSet.run(set, fib(n - 1, set))
47

48
    // Join the fibers to retrieve their results
49
    const v1 = yield* Fiber.join(fiber1)
50
    const v2 = yield* Fiber.join(fiber2)
51

52
    return v1 + v2 // Combine the results
53
  })
54

55
await Effect.runPromise(program)
56
/*
57
Example Output:
58
number of fibers: 0
59
number of fibers: 0
60
number of fibers: 2
61
number of fibers: 6
62
number of fibers: 6
63
number of fibers: 14
64
number of fibers: 30
65
number of fibers: 30
66
number of fibers: 55
67
number of fibers: 62
68
number of fibers: 62
69
number of fibers: 35
70
number of fibers: 8
71
number of fibers: 8
72
*/

Tracking Fibers with FiberMap

FiberMap<K, A, E> behaves like FiberSet, but each fiber is tracked under a key. This is useful when you need to look up, replace, or interrupt a specific fiber later, for example, one fiber per connected client, keyed by client ID. Setting a new fiber under a key that’s already in use interrupts the previous one first.

For the full FiberMap API, see the FiberMap module reference.