import * as Deferred from "./Deferred.ts"; import * as Effect from "./Effect.ts"; import * as Fiber from "./Fiber.ts"; import type * as Inspectable from "./Inspectable.ts"; import * as Option from "./Option.ts"; import type { Pipeable } from "./Pipeable.ts"; import type { Scheduler } from "./Scheduler.ts"; import type * as Scope from "./Scope.ts"; declare const TypeId = "~effect/FiberHandle"; /** * 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. * * **Example** (Managing a single fiber) * * ```ts import.meta.vitest * import { Effect, Fiber, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * // Create a FiberHandle that can hold fibers producing strings * const handle = yield* FiberHandle.make() * * // The handle can store and manage a single fiber * const fiber = yield* FiberHandle.run(handle, Effect.succeed("hello")) * return yield* Fiber.join(fiber) * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => "hello" * ``` * * @stability stable * @category models * @since 2.0.0 */ export interface FiberHandle extends Pipeable, Inspectable.Inspectable { readonly [TypeId]: typeof TypeId; readonly deferred: Deferred.Deferred; state: { readonly _tag: "Open"; fiber: Fiber.Fiber | undefined; /** Every fiber the handle still owns: the current one plus replaced fibers that are still interrupting. */ readonly fibers: Set>; } | { readonly _tag: "Closed"; }; } /** * Returns `true` if a value is a `FiberHandle` by checking for the * `FiberHandle` runtime marker. * * **Example** (Checking fiber handles) * * ```ts import.meta.vitest * import { Effect, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * * return [FiberHandle.isFiberHandle(handle), FiberHandle.isFiberHandle("not a handle")] * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => [true, false] * ``` * * @stability stable * @category guards * @since 2.0.0 */ export declare const isFiberHandle: (u: unknown) => u is FiberHandle; /** * 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. * * **Example** (Creating a scoped fiber handle) * * ```ts import.meta.vitest * import { Effect, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * * // run some effects * yield* FiberHandle.run(handle, Effect.never) * // this will interrupt the previous fiber * yield* FiberHandle.run(handle, Effect.never) * * yield* Effect.yieldNow * return handle.state._tag === "Open" && handle.state.fiber !== undefined * }).pipe( * Effect.scoped // The fiber will be interrupted when the scope is closed * ) * * const actual = await Effect.runPromise(program) * actual // => true * ``` * * @stability stable * @category constructors * @since 2.0.0 */ export declare const make: () => Effect.Effect, never, Scope.Scope>; /** * 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. * * **Example** (Running effects with a fiber handle) * * ```ts import.meta.vitest * import { Cause, Effect, Exit, Fiber, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const run = yield* FiberHandle.makeRuntime() * * // Run effects and get fibers back * const fiberA = run(Effect.never) * const fiberB = run(Effect.succeed("second")) * * // The second fiber will interrupt the first * const resultA = yield* Fiber.await(fiberA) * const resultB = yield* Fiber.await(fiberB) * return [resultA, resultB] * }).pipe(Effect.scoped) * * const actual = await Effect.runPromise(program) * actual // => [Exit.failCause(Cause.interrupt(-1)), Exit.succeed("second")] * ``` * * @stability stable * @category constructors * @since 2.0.0 */ export declare const makeRuntime: () => Effect.Effect<(effect: Effect.Effect, options?: { readonly signal?: AbortSignal | undefined; readonly scheduler?: Scheduler | undefined; readonly onlyIfMissing?: boolean | undefined; readonly propagateInterruption?: boolean | undefined; } | undefined) => Fiber.Fiber, never, Scope.Scope | R>; /** * 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. * * **Example** (Running effects as promises) * * ```ts import.meta.vitest * import { Effect, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const run = yield* FiberHandle.makeRuntimePromise() * * // Run effects and get promises back * const promise = run(Effect.succeed("hello")) * return yield* Effect.promise(() => promise) * }).pipe(Effect.scoped) * * const actual = await Effect.runPromise(program) * actual // => "hello" * ``` * * @stability stable * @category constructors * @since 3.13.0 */ export declare const makeRuntimePromise: () => Effect.Effect<(effect: Effect.Effect, options?: { readonly signal?: AbortSignal | undefined; readonly scheduler?: Scheduler | undefined; readonly onlyIfMissing?: boolean | undefined; readonly propagateInterruption?: boolean | undefined; } | undefined) => Promise, never, Scope.Scope | R>; /** * 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. * * **Example** (Setting a fiber unsafely) * * ```ts import.meta.vitest * import { Effect, Fiber, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * const fiber = Effect.runFork(Effect.succeed("hello")) * * // Set the fiber directly (unsafe) * FiberHandle.setUnsafe(handle, fiber) * * // The fiber is now managed by the handle * return yield* Fiber.join(fiber) * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => "hello" * ``` * * @stability stable * @category combinators * @since 4.0.0 */ export declare const setUnsafe: { /** * 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. * * **Example** (Setting a fiber unsafely) * * ```ts import.meta.vitest * import { Effect, Fiber, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * const fiber = Effect.runFork(Effect.succeed("hello")) * * // Set the fiber directly (unsafe) * FiberHandle.setUnsafe(handle, fiber) * * // The fiber is now managed by the handle * return yield* Fiber.join(fiber) * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => "hello" * ``` * * @stability stable * @category combinators * @since 4.0.0 */ (fiber: Fiber.Fiber, options?: { readonly onlyIfMissing?: boolean | undefined; readonly propagateInterruption?: boolean | undefined; }): (self: FiberHandle) => 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. * * **Example** (Setting a fiber unsafely) * * ```ts import.meta.vitest * import { Effect, Fiber, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * const fiber = Effect.runFork(Effect.succeed("hello")) * * // Set the fiber directly (unsafe) * FiberHandle.setUnsafe(handle, fiber) * * // The fiber is now managed by the handle * return yield* Fiber.join(fiber) * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => "hello" * ``` * * @stability stable * @category combinators * @since 4.0.0 */ (self: FiberHandle, fiber: Fiber.Fiber, options?: { readonly onlyIfMissing?: boolean | undefined; readonly propagateInterruption?: boolean | undefined; }): void; }; /** * 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. * * **Example** (Setting a fiber safely) * * ```ts import.meta.vitest * import { Effect, Fiber, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * const fiber = Effect.runFork(Effect.succeed("hello")) * * // Set the fiber safely * yield* FiberHandle.set(handle, fiber) * * // The fiber is now managed by the handle * return yield* Fiber.join(fiber) * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => "hello" * ``` * * @stability stable * @category combinators * @since 2.0.0 */ export declare const set: { /** * 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. * * **Example** (Setting a fiber safely) * * ```ts import.meta.vitest * import { Effect, Fiber, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * const fiber = Effect.runFork(Effect.succeed("hello")) * * // Set the fiber safely * yield* FiberHandle.set(handle, fiber) * * // The fiber is now managed by the handle * return yield* Fiber.join(fiber) * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => "hello" * ``` * * @stability stable * @category combinators * @since 2.0.0 */ (fiber: Fiber.Fiber, options?: { readonly onlyIfMissing?: boolean; readonly propagateInterruption?: boolean | undefined; }): (self: FiberHandle) => Effect.Effect; /** * 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. * * **Example** (Setting a fiber safely) * * ```ts import.meta.vitest * import { Effect, Fiber, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * const fiber = Effect.runFork(Effect.succeed("hello")) * * // Set the fiber safely * yield* FiberHandle.set(handle, fiber) * * // The fiber is now managed by the handle * return yield* Fiber.join(fiber) * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => "hello" * ``` * * @stability stable * @category combinators * @since 2.0.0 */ (self: FiberHandle, fiber: Fiber.Fiber, options?: { readonly onlyIfMissing?: boolean; readonly propagateInterruption?: boolean | undefined; }): Effect.Effect; }; /** * 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. * * **Example** (Reading the current fiber unsafely) * * ```ts import.meta.vitest * import { Effect, FiberHandle, Option } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * * // No fiber initially * const emptyFiber = FiberHandle.getUnsafe(handle) * * // Add a fiber * yield* FiberHandle.run(handle, Effect.never) * const fiber = FiberHandle.getUnsafe(handle) * return [emptyFiber, Option.map(fiber, () => true)] * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => [Option.none(), Option.some(true)] * ``` * * @stability stable * @category combinators * @since 4.0.0 */ export declare function getUnsafe(self: FiberHandle): Option.Option>; /** * Retrieves the fiber from the FiberHandle effectfully. * * **Example** (Reading the current fiber) * * ```ts import.meta.vitest * import { Effect, FiberHandle, Option } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * * // Add a fiber * yield* FiberHandle.run(handle, Effect.never) * * // Get the current fiber if present * const fiber = yield* FiberHandle.get(handle) * return Option.map(fiber, () => true) * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => Option.some(true) * ``` * * @stability stable * @category combinators * @since 2.0.0 */ export declare function get(self: FiberHandle): Effect.Effect>>; /** * Interrupts the fiber currently stored in the `FiberHandle`, if any, and * leaves the handle empty. * * **Example** (Clearing a fiber handle) * * ```ts import.meta.vitest * import { Effect, FiberHandle, Option } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * * // Add a fiber * yield* FiberHandle.run(handle, Effect.never) * * // Clear the handle, interrupting the fiber * yield* FiberHandle.clear(handle) * * // The handle is now empty * return FiberHandle.getUnsafe(handle) * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => Option.none() * ``` * * @stability stable * @category combinators * @since 2.0.0 */ export declare const clear: (self: FiberHandle) => Effect.Effect; /** * 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. * Set `startImmediately: false` to defer startup. By default, the effect starts * immediately. * * **Example** (Running an effect in a fiber handle) * * ```ts import.meta.vitest * import { Effect, Fiber, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * * // Run an effect and get the fiber * const fiber = yield* FiberHandle.run(handle, Effect.succeed("hello")) * const result = yield* Fiber.join(fiber) * * // Running another effect will interrupt the previous one * const fiber2 = yield* FiberHandle.run(handle, Effect.succeed("world")) * const result2 = yield* Fiber.join(fiber2) * return [result, result2] * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => ["hello", "world"] * ``` * * @stability stable * @category combinators * @since 2.0.0 */ export declare const run: { /** * 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. * Set `startImmediately: false` to defer startup. By default, the effect starts * immediately. * * **Example** (Running an effect in a fiber handle) * * ```ts import.meta.vitest * import { Effect, Fiber, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * * // Run an effect and get the fiber * const fiber = yield* FiberHandle.run(handle, Effect.succeed("hello")) * const result = yield* Fiber.join(fiber) * * // Running another effect will interrupt the previous one * const fiber2 = yield* FiberHandle.run(handle, Effect.succeed("world")) * const result2 = yield* Fiber.join(fiber2) * return [result, result2] * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => ["hello", "world"] * ``` * * @stability stable * @category combinators * @since 2.0.0 */ (self: FiberHandle, options?: { readonly onlyIfMissing?: boolean; readonly propagateInterruption?: boolean | undefined; readonly startImmediately?: boolean | undefined; }): (effect: Effect.Effect) => Effect.Effect, never, R>; /** * 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. * Set `startImmediately: false` to defer startup. By default, the effect starts * immediately. * * **Example** (Running an effect in a fiber handle) * * ```ts import.meta.vitest * import { Effect, Fiber, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * * // Run an effect and get the fiber * const fiber = yield* FiberHandle.run(handle, Effect.succeed("hello")) * const result = yield* Fiber.join(fiber) * * // Running another effect will interrupt the previous one * const fiber2 = yield* FiberHandle.run(handle, Effect.succeed("world")) * const result2 = yield* Fiber.join(fiber2) * return [result, result2] * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => ["hello", "world"] * ``` * * @stability stable * @category combinators * @since 2.0.0 */ (self: FiberHandle, effect: Effect.Effect, options?: { readonly onlyIfMissing?: boolean; readonly propagateInterruption?: boolean | undefined; readonly startImmediately?: boolean | undefined; }): Effect.Effect, 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. * * **Example** (Capturing a runtime for fiber handles) * * ```ts import.meta.vitest * import { Context, Effect, Fiber, FiberHandle } from "effect" * * class Users extends Context.Service> * }>()("Users") {} * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * const run = yield* FiberHandle.runtime(handle)() * * // run an effect and set the fiber in the handle * const fiberA = run(Effect.andThen(Users, (_) => _.getAll)) * * // this will interrupt the previous fiber * const fiberB = run(Effect.andThen(Users, (_) => _.getAll)) * yield* Fiber.await(fiberA) * return (yield* Fiber.join(fiberB)).length * }).pipe( * Effect.scoped // The fiber will be interrupted when the scope is closed * ) * * const actual = await Effect.runPromise(Effect.provideService(program, Users, { * getAll: Effect.succeed([]) * })) * actual // => 0 * ``` * * @stability stable * @category combinators * @since 2.0.0 */ export declare const runtime: (self: FiberHandle) => () => Effect.Effect<(effect: Effect.Effect, options?: { readonly signal?: AbortSignal | undefined; readonly scheduler?: Scheduler | undefined; readonly onlyIfMissing?: boolean | undefined; readonly propagateInterruption?: boolean | undefined; } | undefined) => Fiber.Fiber, never, R>; /** * 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. * * **Example** (Capturing a runtime for promises) * * ```ts import.meta.vitest * import { Effect, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * const runPromise = yield* FiberHandle.runtimePromise(handle)() * * // Run an effect and get a promise * const promise = runPromise(Effect.succeed("hello")) * return yield* Effect.promise(() => promise) * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => "hello" * ``` * * @stability stable * @category combinators * @since 3.13.0 */ export declare const runtimePromise: (self: FiberHandle) => () => Effect.Effect<(effect: Effect.Effect, options?: { readonly signal?: AbortSignal | undefined; readonly scheduler?: Scheduler | undefined; readonly onlyIfMissing?: boolean | undefined; readonly propagateInterruption?: boolean | undefined; } | undefined) => Promise, never, R>; /** * 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. * * **Example** (Propagating fiber failures) * * ```ts import.meta.vitest * import { Effect, Exit, FiberHandle } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * yield* FiberHandle.set(handle, Effect.runFork(Effect.fail("error"))) * * // parent fiber will fail with "error" * yield* FiberHandle.join(handle) * }) * * const actual = await Effect.runPromise(Effect.exit(Effect.scoped(program))) * actual // => Exit.fail("error") * ``` * * @stability stable * @category combinators * @since 2.0.0 */ export declare const join: (self: FiberHandle) => Effect.Effect; /** * Waits for the fiber in the FiberHandle to complete. * * **Example** (Waiting for a fiber to complete) * * ```ts import.meta.vitest * import { Effect, FiberHandle, Option } from "effect" * * const program = Effect.gen(function*() { * const handle = yield* FiberHandle.make() * * yield* FiberHandle.run(handle, Effect.yieldNow) * * // Wait for the fiber to complete * yield* FiberHandle.awaitEmpty(handle) * * return yield* FiberHandle.get(handle) * }) * * const actual = await Effect.runPromise(Effect.scoped(program)) * actual // => Option.none() * ``` * * @stability stable * @category combinators * @since 3.13.0 */ export declare const awaitEmpty: (self: FiberHandle) => Effect.Effect; export {}; //# sourceMappingURL=FiberHandle.d.ts.map