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
awaitEmpty
Wait for the fiber in the FiberHandle to complete.
Signature
export declare const awaitEmpty: <A, E>(self: FiberHandle<A, E>) => Effect.Effect<void, E>
Added in v3.13.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
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,
Scope.Scope | R
>
Added in v2.0.0
makeRuntimePromise
Create an Effect run function that is backed by a FiberHandle.
Signature
export 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
>
Added in 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
export 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>
}
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
readonly propagateInterruption?: 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
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
export 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
>
Added in 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
export 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>
}
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
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
}
Added in v2.0.0