FiberHandle
Manages at most one fiber inside a scope.
A FiberHandle<A, E> can hold one Fiber<A, E>. Installing a new fiber interrupts the previous one unless the operation is configured with onlyIfMissing, and closing the owning scope interrupts the current fiber. This module includes constructors for handles and scoped runtimes, helpers for setting, reading, clearing, and running fibers, and operations for joining the current fiber or waiting until the handle is empty.
Combinators
awaitEmpty
Signature
declare function awaitEmpty<A, E>(self: FiberHandle<A, E>): Effect<void, E>;Interrupts the fiber currently stored in the FiberHandle, if any, and leaves the handle empty.
Signature
declare function clear<A, E>(self: FiberHandle<A, E>): Effect<void>;Retrieves the fiber from the FiberHandle effectfully.
Signature
declare function get<A, E>(self: FiberHandle<A, E>): Effect<Option<Fiber<A, E>>>;Retrieves the fiber from the FiberHandle synchronously.
When to use
Use when synchronous inspection of the current fiber is needed and an Option result is enough outside the Effect workflow.
Signature
declare function getUnsafe<A, E>(self: FiberHandle<A, E>): Option<Fiber<A, E>>;Waits for the FiberHandle to fail or close.
Details
The returned Effect fails with the first managed fiber failure that is not ignored by the handle's interruption rules. Normal successful completion of a managed fiber only removes it from the handle; use awaitEmpty to wait for the current fiber to finish.
Signature
declare function join<A, E>(self: FiberHandle<A, E>): Effect<void, E>;Forks an Effect and stores the resulting fiber in the FiberHandle.
Details
The handle manages only one fiber: running a new effect interrupts the previous fiber unless onlyIfMissing is set. When the managed fiber completes, it is removed from the handle.
Signature
declare const run: {
<A, E>(
self: FiberHandle<A, E>,
options?: {
readonly onlyIfMissing?: boolean;
readonly propagateInterruption?: boolean;
readonly startImmediately?: boolean;
},
): <R, XE, XA>(effect: Effect<XA, XE, R>) => Effect<Fiber<XA, XE>, never, R>;
<A, E, R, XE, XA>(
self: FiberHandle<A, E>,
effect: Effect<XA, XE, R>,
options?: {
readonly onlyIfMissing?: boolean;
readonly propagateInterruption?: boolean;
readonly startImmediately?: boolean;
},
): Effect<Fiber<XA, XE>, never, R>;
};Captures the current runtime and returns a function for forking effects into an existing FiberHandle.
Details
Each call returns the forked fiber, stores it in the handle, and interrupts the previous fiber unless onlyIfMissing is set.
Signature
declare const runtime: <A, E>(
self: FiberHandle<A, E>,
) => <R = never>() => Effect.Effect<
<XE extends E, XA extends A>(
effect: Effect.Effect<XA, XE, R>,
options?: {
readonly onlyIfMissing?: boolean;
readonly propagateInterruption?: boolean;
readonly scheduler?: Scheduler;
readonly signal?: AbortSignal;
},
) => Fiber.Fiber<XA, XE>,
never,
R
>;runtimePromise
Captures the current runtime and returns a function for running effects in an existing FiberHandle as Promises.
Details
Each call stores the forked fiber in the handle and interrupts the previous fiber unless onlyIfMissing is set. The Promise resolves with the effect's success value or rejects with the squashed failure cause.
Signature
declare function runtimePromise<A, E>(
self: FiberHandle<A, E>,
): <R = never>() => Effect<
<XE, XA>(
effect: Effect<XA, XE, R>,
options?: {
readonly onlyIfMissing?: boolean;
readonly propagateInterruption?: boolean;
readonly scheduler?: Scheduler;
readonly signal?: AbortSignal;
},
) => Promise<XA>,
never,
R
>;Sets the fiber in the FiberHandle.
Details
When the fiber completes, it will be removed from the FiberHandle. If a fiber already exists in the FiberHandle, it will be interrupted unless options.onlyIfMissing is set.
Signature
declare const set: {
<A, E, XE, XA>(
fiber: Fiber<XA, XE>,
options?: {
readonly onlyIfMissing?: boolean;
readonly propagateInterruption?: boolean;
},
): (self: FiberHandle<A, E>) => Effect<void>;
<A, E, XE, XA>(
self: FiberHandle<A, E>,
fiber: Fiber<XA, XE>,
options?: {
readonly onlyIfMissing?: boolean;
readonly propagateInterruption?: boolean;
},
): Effect<void>;
};Sets the fiber in a FiberHandle. When the fiber completes, it will be removed from the FiberHandle. If a fiber is already running, it will be interrupted unless options.onlyIfMissing is set.
When to use
Use when an existing forked fiber must be installed synchronously into a handle and immediate interruption of replaced or closed fibers is acceptable.
Signature
declare const setUnsafe: {
<A, E, XE, XA>(
fiber: Fiber<XA, XE>,
options?: {
readonly onlyIfMissing?: boolean;
readonly propagateInterruption?: boolean;
},
): (self: FiberHandle<A, E>) => void;
<A, E, XE, XA>(
self: FiberHandle<A, E>,
fiber: Fiber<XA, XE>,
options?: {
readonly onlyIfMissing?: boolean;
readonly propagateInterruption?: boolean;
},
): void;
};Constructors
Creates a scoped FiberHandle that can store a single fiber.
Details
When the associated Scope is closed, the contained fiber will be interrupted. You can add a fiber to the handle using FiberHandle.run, and the fiber will be automatically removed from the FiberHandle when it completes.
Signature
declare function make<A = unknown, E = unknown>(): Effect<FiberHandle<A, E>, never, Scope>;makeRuntime
Creates a scoped run function that forks effects into a new FiberHandle.
Details
Each call returns the forked fiber, stores it in the handle, and interrupts the previous fiber unless onlyIfMissing is set. The managed fiber is interrupted when the handle's scope closes.
Signature
declare function makeRuntime<R, E = unknown, A = unknown>(): Effect<
<XE, XA>(
effect: Effect<XA, XE, R>,
options?: {
readonly onlyIfMissing?: boolean;
readonly propagateInterruption?: boolean;
readonly scheduler?: Scheduler;
readonly signal?: AbortSignal;
},
) => Fiber<XA, XE>,
never,
Scope | R
>;makeRuntimePromise
Creates a scoped run function that forks effects into a new FiberHandle and returns a Promise for each effect result.
When to use
Use when integrating a scoped FiberHandle runner with Promise-based APIs and Promise rejection from squashed failures is the desired boundary.
Details
Each call stores the fiber in the handle and interrupts the previous fiber unless onlyIfMissing is set. The returned Promise resolves with the effect's success value or rejects with the squashed failure cause.
Signature
declare function makeRuntimePromise<R = never, A = unknown, E = unknown>(): Effect<
<XE, XA>(
effect: Effect<XA, XE, R>,
options?: {
readonly onlyIfMissing?: boolean;
readonly propagateInterruption?: boolean;
readonly scheduler?: Scheduler;
readonly signal?: AbortSignal;
},
) => Promise<XA>,
never,
Scope | R
>;Guards
isFiberHandle
Returns true if a value is a FiberHandle by checking for the FiberHandle runtime marker.
Signature
declare function isFiberHandle(u: unknown): u is FiberHandle<unknown, unknown>;Models
FiberHandle interface
Scoped handle that manages at most one fiber, interrupts the current fiber when the handle's scope closes, and removes managed fibers from the handle when they complete.
Signature
interface FiberHandle<out A = unknown, out E = unknown> extends Pipeable, Inspectable {
readonly "~effect/FiberHandle": "~effect/FiberHandle";
readonly deferred: Deferred<void, unknown>;
state:
| {
readonly _tag: "Open";
fiber: Fiber<A, E> | undefined;
}
| {
readonly _tag: "Closed";
};
}
Waits for the fiber in the FiberHandle to complete.