Scheduler
Controls how runnable Effect fiber tasks are dispatched.
A scheduler decides how tasks are queued, when queued tasks run, and when a fiber should pause so other work can continue. This module includes the scheduler service reference, the default MixedScheduler, dispatcher types for queued tasks, and references for tuning or disabling automatic scheduler yields.
Models
MixedScheduler
Signature
declare class MixedScheduler implements Scheduler {
constructor(executionMode: "sync" | "async", setImmediateFn?: (f: () => void) => () => void);
readonly executionMode: "sync" | "async";
readonly setImmediate: (f: () => void) => () => void;
makeDispatcher(): MixedSchedulerDispatcher;
shouldYield(fiber: Fiber<unknown, unknown>): boolean;
}SchedulerDispatcher interface
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.
Signature
interface SchedulerDispatcher {
flush(): void;
scheduleTask(task: () => void, priority: number): void;
}Services
MaxOpsBeforeYield
Context reference that controls the maximum number of operations a fiber can perform before yielding control back to the scheduler.
When to use
Use to tune scheduler fairness for CPU-bound fibers by changing the scheduler operation budget that triggers a yield.
Details
The default value is 2048 operations, which balances performance and fairness by helping prevent long-running fibers from monopolizing the execution thread.
See
PreventSchedulerYieldfor bypassing scheduler yield checks entirely rather than tuning the operation budget
Signature
declare const MaxOpsBeforeYield: Reference<number>;PreventSchedulerYield
Context reference that controls whether the runtime should bypass scheduler yield checks. When set to true, the fiber run loop won't call Scheduler.shouldYield.
When to use
Use to bypass scheduler yield checks for controlled runtime workloads where cooperative yielding should be disabled.
Gotchas
Setting this reference to true can let long-running fibers monopolize the JavaScript thread.
See
MaxOpsBeforeYieldfor tuning yield frequency without disabling yield checksSchedulerfor providing custom scheduler yield behavior
Signature
declare const PreventSchedulerYield: Reference<boolean>;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.
Signature
declare const Scheduler: Reference<Scheduler>;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.
Signature
interface Scheduler {
readonly executionMode: "sync" | "async";
makeDispatcher(): SchedulerDispatcher;
shouldYield(fiber: Fiber<unknown, unknown>): boolean;
}
Provides 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
MixedSchedulersupports synchronous and asynchronous execution modes, uses operation counts to decide when fibers should yield, and is the default scheduler implementation.