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

FiberHandle overview

Added in v2.0.0

Table of contents

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

Added in v2.0.0

TypeId

Signature

export declare const TypeId: typeof TypeId

Added in v2.0.0

TypeId (type alias)

Signature

export type TypeId = typeof TypeId

Added in v2.0.0

clear

Signature

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

Added in v2.0.0

get

Retrieve the fiber from the FiberHandle.

Signature

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

Added in v2.0.0

isFiberHandle

Signature

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

Added in 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.

Signature

export declare const join: <A, E>(self: FiberHandle<A, E>) => Effect.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))
})

Added in 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.

Signature

export declare const make: <A = unknown, E = unknown>() => Effect.Effect<FiberHandle<A, E>, never, Scope.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
)

Added in v2.0.0

makeRuntime

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

Signature

export 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,
  any
>

Added in v2.0.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

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

Added in v2.0.0

runtime

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

Signature

export 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 }) | undefined
  ) => 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
)

Added in v2.0.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

export declare const set: {
  <A, E, XE extends E, XA extends A>(
    fiber: Fiber.RuntimeFiber<XA, XE>,
    options?: { readonly onlyIfMissing?: boolean }
  ): (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 }
  ): Effect.Effect<void>
}

Added in v2.0.0

unsafeGet

Retrieve the fiber from the FiberHandle.

Signature

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

Added in 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

export 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 }
  ): (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 }
  ): void
}

Added in v2.0.0