Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 19 additions & 5 deletions migration/forking.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,11 +62,25 @@ optional options object with the following fields:
}
```

- **`startImmediately`** — When `true`, the forked fiber begins executing
immediately rather than being deferred. Defaults to `undefined` (deferred).
- **`uninterruptible`** — Controls whether the forked fiber can be interrupted.
`true` makes it uninterruptible, `"inherit"` inherits the parent's
interruptibility, and `undefined` uses the default behavior.
- **`startImmediately`** — Defaults to `false` (also when omitted): the fork
returns before the new fiber runs the effect. With `true`, it runs synchronously
until it first suspends, yields, or completes, before the forking fiber
continues. Deferred startup does not promise a particular scheduler turn.
- **`uninterruptible`** — Defaults to `false` (also when omitted): the new fiber is
interruptible even when forked from an uninterruptible region. With `true`, it
starts uninterruptible, as if the effect were wrapped in
`Effect.uninterruptible`. `Fiber.interrupt` waits for it to finish, and the fiber
keeps its own result. Explicit `Effect.interruptible` regions can still be
interrupted. `"inherit"` copies the forking fiber's interruptibility at the fork.

These options do not change ownership. A `forkChild` fiber is interrupted when its
parent exits; a `forkDetach` fiber is independent of the parent's lifetime.
`forkIn` and `forkScoped` bind the fiber to a scope instead of the forking fiber.
Forking and scope registration are interruption-safe, so interrupting the forker
cannot leave the new fiber outside the scope. Closing the scope from another
fiber interrupts the scoped fiber and waits for its finalizers. Uninterruptible
work can delay closure; a fiber closing its own scope is not interrupted or
awaited by that close.

**Usage as data-last (curried)**

Expand Down
210 changes: 198 additions & 12 deletions packages/effect/src/Effect.ts
Original file line number Diff line number Diff line change
Expand Up @@ -414,6 +414,18 @@ export declare namespace All {
* `Result` in the same output shape. Use `discard: true` to ignore successful
* values and return `void`.
*
* With concurrent execution, a failure requests interruption of other effects
* that have already started. The returned effect waits for those fibers to finish,
* including their finalizers. Uninterruptible regions can delay completion.
* This fail-fast behavior does not apply to `mode: "result"`. Concurrent
* effects inherit the surrounding region's interruptibility.
*
* **Gotchas**
*
* Waiting for fiber cleanup does not ensure external work stops: a Promise
* can keep running unless the operation honors cancellation. Fibers started
* with `forkDetach` are not awaited.
*
* **Example** (Collecting tuple results in order)
*
* ```ts import.meta.vitest
Expand Down Expand Up @@ -743,8 +755,8 @@ export const findFirstFilter: {
* The `forEach` function applies a provided operation to each element in the
* iterable, producing a new effect that returns an array of results.
*
* If any effect fails, the iteration stops immediately (short-circuiting), and
* the error is propagated.
* If any effect fails, the iteration short-circuits and propagates the error
* after cleanup.
*
* Concurrency:
*
Expand All @@ -756,6 +768,17 @@ export const findFirstFilter: {
* If the `discard` option is set to `true`, the intermediate results are not
* collected, and the final result of the operation is `void`.
*
* With concurrent execution, a failure requests interruption of other effects
* that have already started. The returned effect waits for those fibers to finish,
* including their finalizers. Uninterruptible regions can delay completion.
* Concurrent effects inherit the surrounding region's interruptibility.
*
* **Gotchas**
*
* Waiting for fiber cleanup does not ensure external work stops: a Promise
* can keep running unless the operation honors cancellation. Fibers started
* with `forkDetach` are not awaited.
*
* **Example** (Mapping over an iterable with effects)
*
* ```ts import.meta.vitest
Expand Down Expand Up @@ -1094,6 +1117,11 @@ export const succeedSome: <A>(value: A) => Effect<Option<A>> = internal.succeedS
* different effects. Any side effects or scoped captures inside the thunk are
* re-executed on each invocation.
*
* **Gotchas**
*
* If the thunk throws, the thrown value is treated as a defect, not as a typed
* failure. Use `Effect.try` when a throw should become a typed failure.
*
* **Example** (Lazily evaluating side effects)
*
* ```ts import.meta.vitest
Expand Down Expand Up @@ -4755,13 +4783,19 @@ export const firstSuccessOf: <Eff extends Effect<any, any, any>>(
*
* The `timeout` function allows you to specify a time limit for an
* effect's execution. If the effect does not complete within the given time, a
* `TimeoutError` is raised. This can be useful for controlling how long your
* program waits for a task to finish, ensuring that it doesn't hang
* indefinitely if the task takes too long.
* `TimeoutError` is raised after the source fiber finishes its cleanup.
*
* **Gotchas**
*
* If the timeout wins, the source effect is interrupted.
* If the timeout wins, the source is interrupted and the returned effect waits
* for the source fiber to finish, including its finalizers. The duration
* determines when interruption is requested, not a deadline for completion.
* An uninterruptible source can delay completion; its eventual result is
* discarded and the timeout failure is still returned.
*
* Waiting for fiber cleanup does not ensure external work stops: a Promise
* can keep running unless the operation honors cancellation. Fibers started
* with `forkDetach` are not awaited.
*
* **Example** (Failing when work takes too long)
*
Expand Down Expand Up @@ -4805,6 +4839,18 @@ export const timeout: {
* interrupted and the returned effect succeeds with `Option.none`. If the
* source effect fails before the timeout, that failure is preserved.
*
* **Gotchas**
*
* If the timeout wins, the source is interrupted and the returned effect waits
* for the source fiber to finish, including its finalizers. The duration
* determines when interruption is requested, not a deadline for completion.
* An uninterruptible source can delay completion; its eventual result is
* discarded and the timeout still produces `Option.none`.
*
* Waiting for fiber cleanup does not ensure external work stops: a Promise
* can keep running unless the operation honors cancellation. Fibers started
* with `forkDetach` are not awaited.
*
* **Example** (Returning None on timeout)
*
* ```ts import.meta.vitest
Expand Down Expand Up @@ -4833,7 +4879,19 @@ export const timeoutOption: {

/**
* Applies a timeout to an effect, lazily evaluating `orElse` after interrupting
* the source if the timeout is reached.
* the source and waiting for its cleanup if the timeout is reached.
*
* **Gotchas**
*
* If the timeout wins, the source is interrupted and the returned effect waits
* for the source fiber to finish, including its finalizers. The duration
* determines when interruption is requested, not a deadline for completion.
* An uninterruptible source can delay completion; its eventual result is
* discarded and the timeout still selects `orElse`.
*
* Waiting for fiber cleanup does not ensure external work stops: a Promise
* can keep running unless the operation honors cancellation. Fibers started
* with `forkDetach` are not awaited.
*
* **Example** (Falling back on timeout)
*
Expand Down Expand Up @@ -4976,6 +5034,18 @@ export const timed: <A, E, R>(self: Effect<A, E, R>) => Effect<[duration: Durati
* remaining effects are interrupted. If every effect fails, the returned effect
* fails with a cause containing the collected failure reasons.
*
* The returned effect completes only after the interrupted participants have
* finished, including their finalizers.
*
* **Gotchas**
*
* A losing effect in an uninterruptible region delays completion until that
* region finishes. Its result is discarded.
*
* Waiting for fiber cleanup does not ensure external work stops: a Promise
* can keep running unless the operation honors cancellation. Fibers started
* with `forkDetach` are not awaited.
*
* **Example** (Racing many effects)
*
* ```ts import.meta.vitest
Expand Down Expand Up @@ -5014,6 +5084,18 @@ export const raceAll: <Eff extends Effect<any, any, any>>(
* `raceAll` when early failures should be ignored until a success occurs or
* all effects fail.
*
* The returned effect completes only after the interrupted participants have
* finished, including their finalizers.
*
* **Gotchas**
*
* A losing effect in an uninterruptible region delays completion until that
* region finishes. Its result is discarded.
*
* Waiting for fiber cleanup does not ensure external work stops: a Promise
* can keep running unless the operation honors cancellation. Fibers started
* with `forkDetach` are not awaited.
*
* **Example** (Taking the first settled result)
*
* ```ts import.meta.vitest
Expand Down Expand Up @@ -5049,6 +5131,18 @@ export const raceAllFirst: <Eff extends Effect<any, any, any>>(
* If one effect succeeds, the other is interrupted and `onWinner` can observe the
* winning fiber. If both fail, the race fails.
*
* The returned effect completes only after the interrupted participants have
* finished, including their finalizers.
*
* **Gotchas**
*
* A losing effect in an uninterruptible region delays completion until that
* region finishes. Its result is discarded.
*
* Waiting for fiber cleanup does not ensure external work stops: a Promise
* can keep running unless the operation honors cancellation. Fibers started
* with `forkDetach` are not awaited.
*
* **Example** (Racing two effects)
*
* ```ts import.meta.vitest
Expand Down Expand Up @@ -5104,6 +5198,18 @@ export const race: {
*
* The losing effect is interrupted, and `onWinner` can observe the winning fiber.
*
* The returned effect completes only after the interrupted participants have
* finished, including their finalizers.
*
* **Gotchas**
*
* A losing effect in an uninterruptible region delays completion until that
* region finishes. Its result is discarded.
*
* Waiting for fiber cleanup does not ensure external work stops: a Promise
* can keep running unless the operation honors cancellation. Fibers started
* with `forkDetach` are not awaited.
*
* **Example** (Observing the winning fiber)
*
* ```ts import.meta.vitest
Expand Down Expand Up @@ -6942,8 +7048,12 @@ export const acquireDisposable: <A extends AsyncDisposable | Disposable, E, R>(
* and will be executed as long as the acquisition `Effect` value
* successfully acquires the resource.
*
* During the time period between the acquisition and release of the resource,
* the `use` `Effect` value will be executed.
* `use` runs with the interruptibility of the surrounding region. In an
* interruptible region, it can be interrupted, and `release` receives an `Exit`
* whose cause contains the interruption. In an uninterruptible region, `use`
* runs to completion unless it explicitly restores interruptibility.
*
* The returned effect waits for release to finish, including when interrupted.
*
* If the `release` `Effect` value fails, then the entire `Effect` value will
* fail, even if the `use` `Effect` value succeeds. If this fail-fast behavior
Expand Down Expand Up @@ -8890,9 +9000,7 @@ export const requestUnsafe: <A extends Request.Any>(
// -----------------------------------------------------------------------------

/**
* Returns an effect that forks this effect into its own separate fiber,
* returning the fiber immediately, without waiting for it to begin executing
* the effect.
* Forks this effect into a child fiber and returns its handle.
*
* **Details**
*
Expand All @@ -8912,6 +9020,18 @@ export const requestUnsafe: <A extends Request.Any>(
* fibers leak. This behavior is called "auto supervision", and if this
* behavior is not desired, you may use the `forkDetach` or `forkIn` methods.
*
* Fork options:
*
* - `startImmediately` defaults to `false`: the fork returns before the new
* fiber runs, without promising a scheduler turn. With `true`, the fiber
* runs synchronously until it suspends, yields, or completes before the fork
* returns.
* - `uninterruptible` defaults to `false`, even in an uninterruptible caller.
* With `true`, the fiber starts uninterruptible: `Fiber.interrupt` waits for
* completion without replacing its result. Explicit `Effect.interruptible`
* regions can still be interrupted. `"inherit"` copies the caller's
* interruptibility at the fork.
*
* **Example** (Forking a child fiber)
*
* ```ts import.meta.vitest
Expand Down Expand Up @@ -8953,6 +9073,33 @@ export const forkChild: <
* Forks the effect in the specified scope. The fiber will be interrupted
* when the scope is closed.
*
* **Details**
*
* The scope owns the fiber, not the forker: it can outlive the forker's
* completion or interruption. Closing the scope from another fiber interrupts
* it and waits for completion, including finalizers.
*
* Forking and registration are interruption-safe: interrupting the forker
* cannot leave the new fiber outside the scope. If the scope is already
* closed, the effect is not started and the returned fiber is interrupted.
*
* Fork options:
*
* - `startImmediately` defaults to `false`: the fork returns before the new
* fiber runs, without promising a scheduler turn. With `true`, the fiber
* runs synchronously until it suspends, yields, or completes before the fork
* returns.
* - `uninterruptible` defaults to `false`, even in an uninterruptible caller.
* With `true`, the fiber starts uninterruptible: `Fiber.interrupt` waits for
* completion without replacing its result. Explicit `Effect.interruptible`
* regions can still be interrupted. `"inherit"` copies the caller's
* interruptibility at the fork.
*
* **Gotchas**
*
* A fiber that closes its own scope is not interrupted or awaited by that
* close. An uninterruptible fiber can delay scope closure.
*
* **Example** (Forking into a supplied scope)
*
* ```ts import.meta.vitest
Expand Down Expand Up @@ -8997,6 +9144,33 @@ export const forkIn: {
/**
* Forks the fiber in a `Scope`, interrupting it when the scope is closed.
*
* **Details**
*
* The scope owns the fiber, not the forker: it can outlive the forker's
* completion or interruption. Closing the scope from another fiber interrupts
* it and waits for completion, including finalizers.
*
* Forking and registration are interruption-safe: interrupting the forker
* cannot leave the new fiber outside the scope. If the scope is already
* closed, the effect is not started and the returned fiber is interrupted.
*
* Fork options:
*
* - `startImmediately` defaults to `false`: the fork returns before the new
* fiber runs, without promising a scheduler turn. With `true`, the fiber
* runs synchronously until it suspends, yields, or completes before the fork
* returns.
* - `uninterruptible` defaults to `false`, even in an uninterruptible caller.
* With `true`, the fiber starts uninterruptible: `Fiber.interrupt` waits for
* completion without replacing its result. Explicit `Effect.interruptible`
* regions can still be interrupted. `"inherit"` copies the caller's
* interruptibility at the fork.
*
* **Gotchas**
*
* A fiber that closes its own scope is not interrupted or awaited by that
* close. An uninterruptible fiber can delay scope closure.
*
* **Example** (Forking into the current scope)
*
* ```ts import.meta.vitest
Expand Down Expand Up @@ -9047,6 +9221,18 @@ export const forkScoped: <
* until it completes or is explicitly interrupted through the returned handle,
* even after the forking fiber terminates.
*
* Fork options:
*
* - `startImmediately` defaults to `false`: the fork returns before the new
* fiber runs, without promising a scheduler turn. With `true`, the fiber
* runs synchronously until it suspends, yields, or completes before the fork
* returns.
* - `uninterruptible` defaults to `false`, even in an uninterruptible caller.
* With `true`, the fiber starts uninterruptible: `Fiber.interrupt` waits for
* completion without replacing its result. Explicit `Effect.interruptible`
* regions can still be interrupted. `"inherit"` copies the caller's
* interruptibility at the fork.
*
* **Example** (Forking a detached fiber)
*
* ```ts import.meta.vitest
Expand Down
Loading
Loading