Supervisor

A Supervisor<A> is a utility for managing fibers in Effect, allowing you to track their lifecycle (creation and termination) and producing a value of type A that reflects this supervision. Supervisors are useful when you need insight into or control over the behavior of fibers within your application.

To create a supervisor, you can use the Supervisor.track function. This generates a new supervisor that keeps track of its child fibers, maintaining them in a set. This allows you to observe and monitor their status during execution.

You can supervise an effect by using the Effect.supervised function. This function takes a supervisor as an argument and returns an effect where all child fibers forked within it are supervised by the provided supervisor. This enables you to capture detailed information about these child fibers, such as their status, through the supervisor.

Example (Monitoring Fiber Count)

In this example, we’ll periodically monitor the number of fibers running in the application using a supervisor. The program calculates a Fibonacci number, spawning multiple fibers in the process, while a separate monitor tracks the fiber count.

1
import { Effect, Supervisor, Schedule, Fiber, FiberStatus } from "effect"
2

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

8
  // Start a Fibonacci calculation, supervised by the supervisor
9
  const fibFiber = yield* fib(20).pipe(
10
    Effect.supervised(supervisor),
11
    // Fork the Fibonacci effect into a fiber
12
    Effect.fork,
13
  )
14

15
  // Define a schedule to periodically monitor the fiber count every 500ms
16
  const policy = Schedule.spaced("500 millis").pipe(
17
    Schedule.whileInputEffect((_) =>
18
      Fiber.status(fibFiber).pipe(
19
        // Continue while the Fibonacci fiber is not done
20
        Effect.andThen((status) => status !== FiberStatus.done),
21
      ),
22
    ),
23
  )
24

25
  // Start monitoring the fibers, using the supervisor to track the count
26
  const monitorFiber = yield* monitorFibers(supervisor).pipe(
27
    // Repeat the monitoring according to the schedule
28
    Effect.repeat(policy),
29
    // Fork the monitoring into its own fiber
30
    Effect.fork,
31
  )
32

33
  // Join the monitor and Fibonacci fibers to ensure they complete
34
  yield* Fiber.join(monitorFiber)
35
  const result = yield* Fiber.join(fibFiber)
36

37
  console.log(`fibonacci result: ${result}`)
38
})
39

40
// Function to monitor and log the number of active fibers
41
const monitorFibers = (
42
  supervisor: Supervisor.Supervisor<Array<Fiber.RuntimeFiber<any, any>>>,
43
): Effect.Effect<void> =>
44
  Effect.gen(function* () {
45
    const fibers = yield* supervisor.value // Get the current set of fibers
46
    console.log(`number of fibers: ${fibers.length}`)
47
  })
48

49
// Recursive Fibonacci calculation, spawning fibers for each recursive step
50
const fib = (n: number): Effect.Effect<number> =>
51
  Effect.gen(function* () {
52
    if (n <= 1) {
53
      return 1
54
    }
55
    yield* Effect.sleep("500 millis") // Simulate work by delaying
56

57
    // Fork two fibers for the recursive Fibonacci calls
58
    const fiber1 = yield* Effect.fork(fib(n - 2))
59
    const fiber2 = yield* Effect.fork(fib(n - 1))
60

61
    // Join the fibers to retrieve their results
62
    const v1 = yield* Fiber.join(fiber1)
63
    const v2 = yield* Fiber.join(fiber2)
64

65
    return v1 + v2 // Combine the results
66
  })
67

68
Effect.runPromise(program)
69
/*
70
Output:
71
number of fibers: 0
72
number of fibers: 2
73
number of fibers: 6
74
number of fibers: 14
75
number of fibers: 30
76
number of fibers: 62
77
number of fibers: 126
78
number of fibers: 254
79
number of fibers: 510
80
number of fibers: 1022
81
number of fibers: 2034
82
number of fibers: 3795
83
number of fibers: 5810
84
number of fibers: 6474
85
number of fibers: 4942
86
number of fibers: 2515
87
number of fibers: 832
88
number of fibers: 170
89
number of fibers: 18
90
number of fibers: 0
91
fibonacci result: 10946
92
*/