Skip to content

Effect 4.0 is here. One ecosystem. Zero dependencies.

API

FiberHandle

17 exports Since v2.0.0 Source

Other

awaitEmpty

Since v3.13.0

Wait for the fiber in the FiberHandle to complete.

Signature

declare function awaitEmpty<A, E>(self: FiberHandle<A, E>): Effect<void, E>

clear

Since v2.0.0

Signature

declare function clear<A, E>(self: FiberHandle<A, E>): Effect<void>

FiberHandle

interface

Since v2.0.0

Signature

interface FiberHandle<out A = unknown, out E = unknown> extends Pipeable, Inspectable {
  readonly [TypeId]: typeof TypeId;
  readonly deferred: Deferred<void, unknown>;
}

get

Since v2.0.0

Retrieve the fiber from the FiberHandle.

Signature

declare function get<A, E>(self: FiberHandle<A, E>): Effect<RuntimeFiber<A, E>, NoSuchElementException>

isFiberHandle

Since v2.0.0

Signature

declare function isFiberHandle(u: unknown): u is FiberHandle<unknown, unknown>

join

Since v2.0.0

If any of the Fiber's in the handle terminate with a failure, the returned Effect will terminate with the first failure that occurred.

Signature

declare function join<A, E>(self: FiberHandle<A, E>): Effect<void, E>

Example

import { Effect, FiberHandle } from "effect";

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));
});

make

Since v2.0.0

A FiberHandle can be used to store a single fiber. 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>

Example

import { Effect, FiberHandle } from "effect"

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.sleep(1000)
}).pipe(
  Effect.scoped // The fiber will be interrupted when the scope is closed
)

makeRuntime

Since v2.0.0

Create an Effect run function that is backed by a FiberHandle.

Signature

declare function makeRuntime<R, E = unknown, A = unknown>(): Effect<<XE, XA>(effect: Effect<XA, XE, R>, options?: RunForkOptions & {
  readonly onlyIfMissing?: boolean;
}) => RuntimeFiber<XA, XE>, never, Scope | R>

makeRuntimePromise

Since v3.13.0

Create an Effect run function that is backed by a FiberHandle.

Signature

declare function makeRuntimePromise<R = never, A = unknown, E = unknown>(): Effect<<XE, XA>(effect: Effect<XA, XE, R>, options?: RunForkOptions) => Promise<XA>, never, Scope | R>

run

Since v2.0.0

Run an Effect and add the forked fiber to the FiberHandle. When the fiber completes, it will be removed from the FiberHandle.

Signature

declare const run: {
  <A, E>(self: FiberHandle<A, E>, options?: {
    readonly onlyIfMissing?: boolean;
    readonly propagateInterruption?: boolean;
  }): <R, XE, XA>(effect: Effect<XA, XE, R>) => Effect<RuntimeFiber<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;
  }): Effect<RuntimeFiber<XA, XE>, never, R>;
}

runtime

Since v2.0.0

Capture a Runtime and use it to fork Effect's, adding the forked fibers to the FiberHandle.

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?: Runtime.RunForkOptions & {
  readonly onlyIfMissing?: boolean;
  readonly propagateInterruption?: boolean;
}) => Fiber.RuntimeFiber<XA, XE>, never, R>

Example

import { Context, Effect, FiberHandle } from "effect"

interface Users {
  readonly _: unique symbol
}
const Users = Context.GenericTag<Users, {
   getAll: Effect.Effect<Array<unknown>>
}>("Users")

Effect.gen(function*() {
  const handle = yield* FiberHandle.make()
  const run = yield* FiberHandle.runtime(handle)<Users>()

  // run an effect and set the fiber in the handle
  run(Effect.andThen(Users, _ => _.getAll))

  // this will interrupt the previous fiber
  run(Effect.andThen(Users, _ => _.getAll))
}).pipe(
  Effect.scoped // The fiber will be interrupted when the scope is closed
)

runtimePromise

Since v3.13.0

Capture a Runtime and use it to fork Effect's, adding the forked fibers to the FiberHandle.

The returned run function will return Promise's that will resolve when the fiber completes.

Signature

declare function runtimePromise<A, E>(self: FiberHandle<A, E>): <R = never>() => Effect<<XE, XA>(effect: Effect<XA, XE, R>, options?: RunForkOptions & {
  readonly propagateInterruption?: boolean;
}) => Promise<XA>, never, R>

set

Since v2.0.0

Set the fiber in the FiberHandle. 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: RuntimeFiber<XA, XE>, options?: {
    readonly onlyIfMissing?: boolean;
    readonly propagateInterruption?: boolean;
  }): (self: FiberHandle<A, E>) => Effect<void>;
  <A, E, XE, XA>(self: FiberHandle<A, E>, fiber: RuntimeFiber<XA, XE>, options?: {
    readonly onlyIfMissing?: boolean;
    readonly propagateInterruption?: boolean;
  }): Effect<void>;
}

TypeId

Since v2.0.0

Signature

declare const TypeId: unique symbol

TypeId

type

Since v2.0.0

Signature

type TypeId = typeof TypeId

unsafeGet

Since v2.0.0

Retrieve the fiber from the FiberHandle.

Signature

declare function unsafeGet<A, E>(self: FiberHandle<A, E>): Option<RuntimeFiber<A, E>>

unsafeSet

Since v2.0.0

Set 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.

Signature

declare const unsafeSet: {
  <A, E, XE, XA>(fiber: RuntimeFiber<XA, XE>, options?: {
    readonly interruptAs?: FiberId.FiberId;
    readonly onlyIfMissing?: boolean;
    readonly propagateInterruption?: boolean;
  }): (self: FiberHandle<A, E>) => void;
  <A, E, XE, XA>(self: FiberHandle<A, E>, fiber: RuntimeFiber<XA, XE>, options?: {
    readonly interruptAs?: FiberId.FiberId;
    readonly onlyIfMissing?: boolean;
    readonly propagateInterruption?: boolean;
  }): void;
}