SchedulerA scheduler manages the execution of Effect fibers by controlling when queued tasks run.
When to use
Use to define or provide custom runtime scheduling behavior for Effect fibers.
Details
A scheduler determines the execution mode, schedules tasks with different priorities, and decides when fibers should yield control after consuming their operation budget.
export interface Scheduler {
readonly Scheduler.executionMode: "sync" | "async"executionMode: "sync" | "async"
Scheduler.shouldYield(fiber: Fiber.Fiber<unknown, unknown>): booleanshouldYield(fiber: Fiber.Fiber<unknown, unknown>(parameter) fiber: {
id: number;
currentOpCount: number;
getRef: <A>(ref: Context.Reference<A>) => A;
context: Context.Context<never>;
setContext: (context: Context.Context<never>) => void;
currentScheduler: Scheduler;
currentDispatcher: SchedulerDispatcher;
currentSpan: AnySpan | undefined;
currentLogLevel: LogLevel;
minimumLogLevel: LogLevel;
currentStackFrame: StackFrame | undefined;
maxOpsBeforeYield: number;
currentPreventYield: boolean;
addObserver: (cb: (exit: Exit<A, E>) => void) => () => void;
interruptUnsafe: (fiberId?: number | undefined, annotations?: Context.Context<never> | undefined) => void;
pollUnsafe: () => Exit<A, E> | undefined;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
import FiberFiber.interface Fiber<out A, out E = never>A runtime fiber is a lightweight thread that executes Effects. Fibers are
the unit of concurrency in Effect. They provide a way to run multiple
Effects concurrently while maintaining structured concurrency and
cancellation safety.
When to use
Use to observe, join, interrupt, or coordinate work that has already been
forked.
Details
A fiber exposes both safe Effect-based operations, such as
await
,
join
, and
interrupt
, and low-level runtime fields used by
the scheduler and runtime internals.
Gotchas
Prefer the exported functions in this module over calling interruptUnsafe
or pollUnsafe directly. The unsafe methods are immediate runtime hooks and
do not provide the same Effect-based sequencing guarantees.
Example (Awaiting a forked fiber)
import { Effect, Fiber } from "effect"
const program = Effect.gen(function*() {
// Fork an effect to run in a new fiber
const fiber = yield* Effect.forkChild(Effect.succeed(42))
// Wait for the fiber to complete and get its result
const result = yield* Fiber.await(fiber)
console.log(result) // Exit.succeed(42)
return result
})
The Fiber namespace contains utility types and functions for working with fibers.
It provides type-level utilities for fiber operations and variance encoding.
When to use
Use to reference type-level helpers associated with Fiber.
Details
The namespace currently exposes type-level support used by the Fiber
interface. Runtime operations are exported as module-level functions.
Example (Working with fiber types)
import { Effect, Fiber } from "effect"
const program = Effect.gen(function*() {
// Create a fiber
const fiber = yield* Effect.forkChild(Effect.succeed(42))
// Use namespace types for variance
const typedFiber: Fiber.Fiber<number, never> = fiber
// Access fiber properties
console.log(`Fiber ID: ${fiber.id}`)
// Join the fiber
const result = yield* Fiber.join(fiber)
return result // 42
})
Fiber<unknown, unknown>): boolean
Scheduler.makeDispatcher(): SchedulerDispatchermakeDispatcher(): SchedulerDispatcher
}
/**
* A dispatcher created by a `Scheduler` for enqueuing tasks and forcing queued
* tasks to run.
*
* **When to use**
*
* Use when implementing or testing scheduler-created dispatchers that enqueue
* prioritized runtime tasks and flush queued work deterministically.
*
* **Details**
*
* `scheduleTask` queues a task with a priority. `flush` drains pending work
* synchronously, which is useful when callers need deterministic completion of
* already scheduled tasks. Lower priority numbers run first, and equal
* priorities run in FIFO order.
*
* @category models
* @since 4.0.0
*/
export interface SchedulerDispatcher {
SchedulerDispatcher.scheduleTask(task: () => void, priority: number): voidscheduleTask(task: () => voidtask: () => void, priority: numberpriority: number): void
SchedulerDispatcher.flush(): voidflush(): void
}
/**
* Context reference for the scheduler used by the Effect runtime.
*
* **When to use**
*
* Use when you need to replace scheduling behavior globally in tests or runtime
* setup, such as forcing deterministic task dispatch.
*
* **Details**
*
* The default value creates a `MixedScheduler`. Provide this service to
* customize execution mode, task dispatching, or yield behavior.
*
* @category references
* @since 2.0.0
*/
export const const Scheduler: Context.Reference<Scheduler>const Scheduler: {
key: string;
Service: {
executionMode: "sync" | "async";
shouldYield: (fiber: Fiber.Fiber<unknown, unknown>) => boolean;
makeDispatcher: () => SchedulerDispatcher;
};
defaultValue: () => Shape;
of: (this: void, self: Scheduler) => Scheduler;
context: (self: Scheduler) => Context.Context<never>;
use: (f: (service: Scheduler) => Effect<A, E, R>) => Effect<A, E, R>;
useSync: (f: (service: Scheduler) => A) => Effect<A, never, never>;
Identifier: Identifier;
stack: string | undefined;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
A scheduler manages the execution of Effect fibers by controlling when queued
tasks run.
When to use
Use to define or provide custom runtime scheduling behavior for Effect fibers.
Details
A scheduler determines the execution mode, schedules tasks with different
priorities, and decides when fibers should yield control after consuming
their operation budget.
Context reference for the scheduler used by the Effect runtime.
When to use
Use when you need to replace scheduling behavior globally in tests or runtime
setup, such as forcing deterministic task dispatch.
Details
The default value creates a MixedScheduler. Provide this service to
customize execution mode, task dispatching, or yield behavior.
Scheduler: import ContextContext.interface Reference<in out Shape>Service key with a lazily computed default value.
Details
When a Reference is requested from a Context that does not contain an
override, Context getters that resolve references return the cached default
value instead of failing.
Example (Defining a reference with a default value)
import { Context } from "effect"
// Define a reference with a default value
const LoggerRef: Context.Reference<{ log: (msg: string) => void }> =
Context.Reference("Logger", {
defaultValue: () => ({ log: (msg: string) => console.log(msg) })
})
// The reference can be used without explicit provision
const context = Context.empty()
const logger = Context.get(context, LoggerRef) // Uses default value
Creates a context key with a default value.
When to use
Use when you need to define a context key with a lazily computed default
value.
Details
Context.Reference allows you to create a key that can hold a value. You
can provide a default value for the service, which will automatically be used
when the context is accessed, or override it with a custom implementation
when needed. The default value is computed lazily and cached on the
reference.
Example (Creating references with default values)
import { Context } from "effect"
// Create a reference with a default value
const LoggerRef = Context.Reference("Logger", {
defaultValue: () => ({ log: (msg: string) => console.log(msg) })
})
// The reference provides the default value when accessed from an empty context
const context = Context.empty()
const logger = Context.get(context, LoggerRef)
// You can also override the default value
const customContext = Context.make(LoggerRef, {
log: (msg: string) => `Custom: ${msg}`
})
const customLogger = Context.get(customContext, LoggerRef)
Reference<Scheduler> = import ContextContext.const Reference: <Service>(
key: string,
options: {
readonly defaultValue: () => Service
}
) => Reference<Service>
Creates a context key with a default value.
When to use
Use when you need to define a context key with a lazily computed default
value.
Details
Context.Reference allows you to create a key that can hold a value. You
can provide a default value for the service, which will automatically be used
when the context is accessed, or override it with a custom implementation
when needed. The default value is computed lazily and cached on the
reference.
Example (Creating references with default values)
import { Context } from "effect"
// Create a reference with a default value
const LoggerRef = Context.Reference("Logger", {
defaultValue: () => ({ log: (msg: string) => console.log(msg) })
})
// The reference provides the default value when accessed from an empty context
const context = Context.empty()
const logger = Context.get(context, LoggerRef)
// You can also override the default value
const customContext = Context.make(LoggerRef, {
log: (msg: string) => `Custom: ${msg}`
})
const customLogger = Context.get(customContext, LoggerRef)
Reference<Scheduler>("effect/Scheduler", {
defaultValue: () => SchedulerdefaultValue: () => new constructor MixedScheduler(executionMode?: "sync" | "async", setImmediateFn?: (f: () => void) => () => void): MixedSchedulerProvides a scheduler implementation that batches queued tasks and dispatches them by
priority.
When to use
Use when you need the default runtime scheduler directly, including a
scheduler that batches queued work by priority and preserves FIFO order within
each priority.
Details
MixedScheduler supports synchronous and asynchronous execution modes, uses
operation counts to decide when fibers should yield, and is the default
scheduler implementation.
MixedScheduler()
})