Skip to main content Link Search Menu Expand Document (external link)
effect

FiberHandle.ts overview

Since v2.0.0

Exports Grouped by Category

utils

FiberHandle (interface)

Signature

export interface FiberHandle<out A = unknown, out E = unknown> extends Pipeable, Inspectable.Inspectable {
  readonly [TypeId]: TypeId
  readonly deferred: Deferred.Deferred<void, unknown>
  /** @internal */
  state:
    | {
        readonly _tag: "Open"
        fiber: Fiber.RuntimeFiber<A, E> | undefined
      }
    | {
        readonly _tag: "Closed"
      }
}

Source

Since v2.0.0

TypeId

Signature

declare const TypeId: unique symbol

Source

Since v2.0.0

TypeId (type alias)

Signature

type TypeId = typeof TypeId

Source

Since v2.0.0

awaitEmpty

Wait for the fiber in the FiberHandle to complete.

Signature

declare const awaitEmpty: <A, E>(self: FiberHandle<A, E>) => Effect.Effect<void, E>

Source

Since v3.13.0

clear

Signature

declare const clear: <A, E>(self: FiberHandle<A, E>) => Effect.Effect<void>

Source

Since v2.0.0

get

Retrieve the fiber from the FiberHandle.

Signature

declare const get: <A, E>(self: FiberHandle<A, E>) => Effect.Effect<Fiber.RuntimeFiber<A, E>, NoSuchElementException>

Source

Since v2.0.0

isFiberHandle

Signature

declare const isFiberHandle: (u: unknown) => u is FiberHandle

Source

Since v2.0.0

join

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

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

Signature

declare const join: <A, E>(self: FiberHandle<A, E>) => Effect.Effect<void, E>

Source

Since v2.0.0

make

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.

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
)

Signature

declare const make: <A = unknown, E = unknown>() => Effect.Effect<FiberHandle<A, E>, never, Scope.Scope>

Source

Since v2.0.0

makeRuntime

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

Signature

declare const makeRuntime: <R, E = unknown, A = unknown>() => Effect.Effect<
  <XE extends E, XA extends A>(
    effect: Effect.Effect<XA, XE, R>,
    options?: (Runtime.RunForkOptions & { readonly onlyIfMissing?: boolean | undefined }) | undefined
  ) => Fiber.RuntimeFiber<XA, XE>,
  never,
  Scope.Scope | R
>

Source

Since v2.0.0

makeRuntimePromise

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

Signature

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

Source

Since v3.13.0

run

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

Source

Since v2.0.0

runtime

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

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
)

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 | undefined
          readonly propagateInterruption?: boolean | undefined
        })
      | undefined
  ) => Fiber.RuntimeFiber<XA, XE>,
  never,
  R
>

Source

Since v2.0.0

runtimePromise

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 const runtimePromise: <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 propagateInterruption?: boolean | undefined }) | undefined
  ) => Promise<XA>,
  never,
  R
>

Source

Since v3.13.0

set

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

Source

Since v2.0.0

unsafeGet

Retrieve the fiber from the FiberHandle.

Signature

declare const unsafeGet: <A, E>(self: FiberHandle<A, E>) => Option.Option<Fiber.RuntimeFiber<A, E>>

Source

Since v2.0.0

unsafeSet

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 extends E, XA extends A>(
    fiber: Fiber.RuntimeFiber<XA, XE>,
    options?: {
      readonly interruptAs?: FiberId.FiberId | undefined
      readonly onlyIfMissing?: boolean | undefined
      readonly propagateInterruption?: boolean | undefined
    }
  ): (self: FiberHandle<A, E>) => void
  <A, E, XE extends E, XA extends A>(
    self: FiberHandle<A, E>,
    fiber: Fiber.RuntimeFiber<XA, XE>,
    options?: {
      readonly interruptAs?: FiberId.FiberId | undefined
      readonly onlyIfMissing?: boolean | undefined
      readonly propagateInterruption?: boolean | undefined
    }
  ): void
}

Source

Since v2.0.0