37 - Interruption

Previous · Next

Effect’s concurrency model is structured: when a fiber is cancelled, the work it was running stops, and any resources it acquired are released. The mechanism is interruption.

You’ve already met it implicitly — when Effect.race picks a winner, the loser is interrupted; when a timeout fires, the inner work is interrupted. This step makes interruption the topic so you can use it explicitly.

What you’ll work through

index.test.ts covers five beats in order: Fiber.interrupt, Effect.ensuring, observing interruption via Cause.hasInterruptsOnly, Effect.onInterrupt, and Effect.uninterruptible.

By the end you should be able to distinguish cancellation from failure in an Exit, attach the right cleanup combinator for the case at hand, and protect short atomic regions with uninterruptible without strangling cancellation.

Mental Model

1
parent
2
  ├── fork ──► child (running)
3
  │             │
4
  │             ▼
5
  │           Effect.interrupt
6
  │             │
7
  │             ▼
8
  │           finalizers run (LIFO)
9
  │             │
10
  │             ▼
11
  │           Exit.Failure(Cause.interrupt)
12
  ▼
13
parent observes the exit via Fiber.await

Three guarantees:

Interruption is cooperative but immediate. A running computation is suspended at the next opportunity (a yield*, a flatMap, a sleep).
Finalizers run before the fiber dies. Acquired resources are released in reverse order via Effect.ensuring / Effect.acquireRelease (covered in step 46 Scope).
An interrupted fiber’s Exit is a Failure whose cause is Interrupt — not a regular E-channel value. You can distinguish it with Cause.hasInterruptsOnly.

Effect.uninterruptible declares a region that ignores interruption requests — use it sparingly, only when you need an operation to complete atomically (release a lock, flush a buffer).

`Fiber.interrupt` — cancelling a running fiber

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

3
const program = Effect.gen(function* () {
4
  const fiber = yield* Effect.forkChild(Effect.sleep("1 hour"))
5
  yield* Fiber.interrupt(fiber)
6
  return yield* Fiber.await(fiber)
7
})

A forked fiber can be interrupted at any time by its parent. The fiber suspends, any in-flight finalizers run, and the resulting Exit describes the interruption.

Long-running effects (a sleep, a tryPromise waiting on a slow request) are interrupted immediately — Effect does not wait for them to finish. Synchronous CPU loops with no yield* between iterations are the one shape that interruption can’t preempt; insert Effect.yieldNow() if you need a cancellation point.

Rule of thumb. Fiber.interrupt is itself an Effect — and it awaits the fiber’s exit. By the time it returns, all finalizers have finished and the fiber is gone. Reach for Fiber.interruptFork if you want fire-and-forget cancellation.

Your turn fork a long sleep with `Effect.forkChild`, call `Fiber.interrupt(fiber)`, and read the `Exit` from `Fiber.await(fiber)`. The exit will be a `Failure` whose cause is `Interrupt`, not a typed `E`.

`Effect.ensuring` — finalizers fire on interruption

1
import { Effect } from "effect"
2

3
const flush: Array<string> = []
4

5
const work = Effect.sleep("1 hour").pipe(
6
  Effect.ensuring(Effect.sync(() => flush.push("released"))),
7
)

Effect.ensuring(release) attaches a finalizer to a workflow. The finalizer runs on success, on failure, and on interruption — exactly the cleanup guarantee try/finally gives you in plain JS, but composable.

This is the foundation of Scope (step 46): an Effect can acquire a resource and the runtime guarantees release.

> default — the runtime won't let cleanup be cancelled mid-flight. That's > the correct default for releasing locks and connections, but it means a > slow finalizer can delay fiber death.

Rule of thumb. Reach for ensuring for all-paths cleanup (the JS finally shape). When you want different behaviour on the interrupted path, use onInterrupt (two beats down). When you want different behaviour on the success path, use Effect.tap.

Your turn wrap the long-sleeping work with `Effect.ensuring(Effect.sync(() => flush.push("released")))`, interrupt the fiber, and assert `flush` contains `"released"` — proof the finalizer ran even though the work was cancelled.

Observing interruption — `Cause.hasInterruptsOnly`

1
import { Effect, Exit, Cause } from "effect"
2

3
const exit = await Effect.runPromise(Fiber.await(fiber))
4
if (Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause)) {
5
  // The fiber was cancelled, not failed with a typed error.
6
}

An interrupted fiber’s Exit is a Failure, but its Cause is Interrupt, not Fail. Don’t reach for catch to handle it — that catches failures.

Use Cause.hasInterruptsOnly (or Effect.onInterrupt) when you specifically need to detect cancellation.

1
Exit.Failure
2
   ├─ Cause.Fail(e)        ← catch / catchTag react
3
   ├─ Cause.Die(defect)    ← unrecoverable, see step 48
4
   └─ Cause.Interrupt(id)  ← only Cause.hasInterruptsOnly detects this

> The latter is true even for failures that *also* contain an interrupt > (rare but real — e.g. a parallel `Effect.all` where one branch failed > and the rest were cancelled). The "Only" variant returns true when the > cause is *exclusively* interruption.

Your turn call `Effect.runPromise(Fiber.await(fiber))` to get the `Exit`, then guard with `Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause)` to confirm cancellation rather than a typed E-channel failure.

`Effect.onInterrupt` — cleanup that only runs on cancellation

1
import { Effect } from "effect"
2

3
const auditing = (work: Effect.Effect<void>) =>
4
  work.pipe(
5
    Effect.onInterrupt(() => Effect.logWarning("cancelled — auditing")),
6
  )

onInterrupt is the narrower sibling of ensuring: it fires only when the workflow is interrupted, not on success or failure. Useful for cancellation metrics, audit logs, or compensating actions you want only on the cancelled path.

Combinator	Success	Failure	Interrupt
`Effect.tap`	✓	—	—
`Effect.onError`	—	✓	—
`Effect.onInterrupt`	—	—	✓
`Effect.ensuring`	✓	✓	✓

Rule of thumb. Pick the narrowest combinator that fits — it makes intent obvious at the call site. A cancellation-only metric should announce itself as onInterrupt, not hide inside an ensuring with an if over Exit.

Your turn attach `Effect.onInterrupt(() => Effect.sync(() => ...))` to the workflow and run two cases — one that completes normally (no side effect) and one that's interrupted (side effect fires). The contrast between the two assertions is the lesson.

`Effect.uninterruptible` — a region that cannot be cancelled

1
import { Effect } from "effect"
2

3
const critical = Effect.gen(function* () {
4
  yield* acquireLock()
5
  yield* doDelicateWork()
6
  yield* releaseLock()
7
}).pipe(Effect.uninterruptible)

Sometimes a region must complete atomically — release a lock, flush a buffer, commit a transaction. Wrap it in Effect.uninterruptible and interruption requests are deferred until the region exits.

Use sparingly: a long uninterruptible region is a denial-of-service against your own cancellation system. Prefer Effect.uninterruptibleMask when you need to poke an interruptible hole inside a larger uninterruptible region.

Your turn wrap a region in `uninterruptible`, interrupt the fiber, and prove the region still completed before the fiber died.

A Full Example

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

3
const audit: Array<string> = []
4

5
const work = Effect.gen(function* () {
6
  audit.push("started")
7
  yield* Effect.sleep("1 hour")
8
  audit.push("finished") // never reached if interrupted
9
}).pipe(
10
  Effect.ensuring(Effect.sync(() => audit.push("released"))),
11
  Effect.onInterrupt(() => Effect.sync(() => audit.push("cancelled"))),
12
)
13

14
const program = Effect.gen(function* () {
15
  const fiber = yield* Effect.forkChild(work)
16
  yield* Effect.sleep("10 millis")
17
  yield* Fiber.interrupt(fiber)
18
  return yield* Fiber.await(fiber)
19
})
20

21
const exit = await Effect.runPromise(program)
22
// audit === ["started", "cancelled", "released"]
23
// Exit.isFailure(exit) === true
24
// Cause.hasInterruptsOnly(exit.cause) === true

ensuring covers all exit paths. onInterrupt narrows to the cancellation path only.

The exit is a Failure with an Interrupt cause — not a regular typed E.

Common Pitfalls

1, Treating interruption as a failure. catch and catchTag ignore interruption. If you need to react to cancellation, use onInterrupt or inspect the Cause with Cause.hasInterruptsOnly.

2, Long uninterruptible regions. They defeat structured concurrency. Keep them as small as the atomic operation requires.

3, Forgetting that finalizers can themselves be interrupted. By default, they are not — Effect makes finalizer execution uninterruptible so cleanup runs to completion. Long finalizers can delay fiber death.

4, Assuming tryPromise can be cancelled mid-promise. Effect can interrupt the waiting, but it cannot cancel the underlying Promise (JS doesn’t allow that). For true cancellation pass an AbortSignal down.

Rules of thumb

Cleanup goes in ensuring — covers success, failure, interruption.
onInterrupt is for cancellation-only side effects like audit logs.
Reach for uninterruptible only when the operation must be atomic. Smaller is safer.
An interrupt is not a failure. It’s its own exit kind. Use Cause.hasInterruptsOnly to detect it.

confirm the exit is a `Failure` with an `Interrupt` cause. - [ ] Add `Effect.ensuring` to the work and confirm the finalizer fires even though the fiber was cancelled. - [ ] Branch on `Cause.hasInterruptsOnly` to distinguish cancellation from a typed failure — `catch` won't help here. - [ ] Use `Effect.onInterrupt` for cancellation-only cleanup and prove it does *not* fire on the happy path. - [ ] Wrap a critical region in `Effect.uninterruptible` and confirm the region completes before the fiber dies.

The full test suite

The index.test.ts for this lesson, verbatim from steps/37-interruption/.

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

4
// =============================================================================
5
// 37 - Interruption
6
// =============================================================================
7
//
8
// Cancelling a fiber. Finalizers run, the exit is an Interrupt cause (not a
9
// failure), and uninterruptible regions defer cancellation.
10

11
// @beat
12
//   id: fiber-interrupt
13
//   shape: one-todo
14
//   title: Fiber.interrupt cancels a running fiber
15
//   teaches: A forked fiber can be interrupted by its parent; the interrupt is observed via Fiber.await as a Failure exit with an Interrupt cause.
16
//   hint: yield* Effect.forkChild(longWork), then yield* Fiber.interrupt(fiber)
17
it("Fiber.interrupt cancels a long-running fiber", async () => {
18
  const program = Effect.gen(function* () {
19
    const fiber = yield* Effect.forkChild(Effect.sleep("1 hour"))
20
    /* @stub */ yield* Fiber.interrupt(fiber) /* @end */
21
    return yield* Fiber.await(fiber)
22
  })
23

24
  const exit = await Effect.runPromise(program)
25
  expect(Exit.isFailure(exit)).toBe(true)
26
  if (Exit.isFailure(exit)) {
27
    expect(Cause.hasInterruptsOnly(exit.cause)).toBe(true)
28
  }
29
})
30
// @end-beat
31

32
// @beat
33
//   id: finalizers-run
34
//   shape: one-todo
35
//   title: Effect.ensuring finalizers fire on interruption
36
//   teaches: A finalizer attached with Effect.ensuring runs on success, on failure, and on interruption — the foundation of safe resource handling.
37
//   hint: work.pipe(Effect.ensuring(Effect.sync(() => audit.push("released"))))
38
it("ensuring finalizer runs when the fiber is interrupted", async () => {
39
  const audit: Array<string> = []
40

41
  const work = Effect.sleep("1 hour").pipe(
42
    /* @stub */ Effect.ensuring(Effect.sync(() => audit.push("released"))) /* @end */,
43
  )
44

45
  const program = Effect.gen(function* () {
46
    const fiber = yield* Effect.forkChild(work)
47
    yield* Effect.sleep("5 millis")
48
    yield* Fiber.interrupt(fiber)
49
    yield* Fiber.await(fiber)
50
  })
51

52
  await Effect.runPromise(program)
53
  expect(audit).toEqual(["released"])
54
})
55
// @end-beat
56

57
// @beat
58
//   id: interrupted-exit
59
//   shape: one-todo
60
//   title: Distinguish interruption from a typed failure
61
//   teaches: catch catches failures but not interrupts; use Cause.hasInterruptsOnly to react specifically to cancellation.
62
//   hint: Cause.hasInterruptsOnly(exit.cause)
63
it("Cause.hasInterruptsOnly distinguishes interruption from failure", async () => {
64
  const program = Effect.gen(function* () {
65
    const fiber = yield* Effect.forkChild(Effect.sleep("1 hour"))
66
    yield* Fiber.interrupt(fiber)
67
    return yield* Fiber.await(fiber)
68
  })
69

70
  const exit = await Effect.runPromise(program)
71
  expect(Exit.isFailure(exit)).toBe(true)
72
  if (Exit.isFailure(exit)) {
73
    const interrupted = /* @stub */ Cause.hasInterruptsOnly(exit.cause) /* @end */
74
    expect(interrupted).toBe(true)
75
  }
76
})
77
// @end-beat
78

79
// @beat
80
//   id: on-interrupt
81
//   shape: one-todo
82
//   title: Effect.onInterrupt — cleanup that only runs on cancellation
83
//   teaches: onInterrupt fires only when the workflow is interrupted, not on success or failure. Use it for cancellation-specific side effects.
84
//   hint: work.pipe(Effect.onInterrupt(() => Effect.sync(() => audit.push("cancelled"))))
85
it("onInterrupt fires only on the cancelled path", async () => {
86
  const audit: Array<string> = []
87

88
  const cancelling = Effect.sleep("1 hour").pipe(
89
    /* @stub */ Effect.onInterrupt(() =>
90
      Effect.sync(() => {
91
        audit.push("cancelled")
92
      }),
93
    ) /* @end */,
94
  )
95

96
  const okWork = Effect.succeed(1).pipe(
97
    Effect.onInterrupt(() =>
98
      Effect.sync(() => {
99
        audit.push("should-not-fire")
100
      }),
101
    ),
102
  )
103

104
  // Success path — onInterrupt does not fire.
105
  await Effect.runPromise(okWork)
106
  expect(audit).toEqual([])
107

108
  // Cancelled path — onInterrupt fires.
109
  await Effect.runPromise(
110
    Effect.gen(function* () {
111
      const fiber = yield* Effect.forkChild(cancelling)
112
      yield* Effect.sleep("5 millis")
113
      yield* Fiber.interrupt(fiber)
114
      yield* Fiber.await(fiber)
115
    }),
116
  )
117
  expect(audit).toEqual(["cancelled"])
118
})
119
// @end-beat
120

121
// @beat
122
//   id: uninterruptible
123
//   shape: one-todo
124
//   title: Effect.uninterruptible defers cancellation until the region exits
125
//   teaches: An uninterruptible region completes before any pending interrupt is delivered — use for atomic operations like lock release or buffer flush.
126
//   hint: critical.pipe(Effect.uninterruptible)
127
it("uninterruptible region completes before interruption is delivered", async () => {
128
  const audit: Array<string> = []
129

130
  const critical = Effect.gen(function* () {
131
    audit.push("started")
132
    yield* Effect.sleep("20 millis")
133
    audit.push("finished")
134
  }).pipe(/* @stub */ Effect.uninterruptible /* @end */)
135

136
  await Effect.runPromise(
137
    Effect.gen(function* () {
138
      const fiber = yield* Effect.forkChild(critical)
139
      yield* Effect.sleep("5 millis")
140
      yield* Fiber.interrupt(fiber)
141
      yield* Fiber.await(fiber)
142
    }),
143
  )
144

145
  // Even though we interrupted mid-region, both side effects landed.
146
  expect(audit).toEqual(["started", "finished"])
147
})
148
// @end-beat

07·03Interruption

37 - Interruption

What you’ll work through

Mental Model

`Fiber.interrupt` — cancelling a running fiber

`Effect.ensuring` — finalizers fire on interruption

Observing interruption — `Cause.hasInterruptsOnly`

`Effect.onInterrupt` — cleanup that only runs on cancellation

`Effect.uninterruptible` — a region that cannot be cancelled

A Full Example

Common Pitfalls

Rules of thumb

See Also

The full test suite

07·03Interruption

37 - Interruption

What you’ll work through

Mental Model

Fiber.interrupt — cancelling a running fiber

Effect.ensuring — finalizers fire on interruption

Observing interruption — Cause.hasInterruptsOnly

Effect.onInterrupt — cleanup that only runs on cancellation

Effect.uninterruptible — a region that cannot be cancelled

A Full Example

Common Pitfalls

Rules of thumb

See Also

The full test suite

`Fiber.interrupt` — cancelling a running fiber

`Effect.ensuring` — finalizers fire on interruption

Observing interruption — `Cause.hasInterruptsOnly`

`Effect.onInterrupt` — cleanup that only runs on cancellation

`Effect.uninterruptible` — a region that cannot be cancelled