Scheduler

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.

Gotchas

On Cloudflare Workers, request-owned scheduler timers can be discarded, leaving shared fibers suspended. Use new MixedScheduler("sync") for the whole application; see HttpRouter.toWebHandler for a recipe. Sync mode does not yield to the event loop: CPU-heavy work delays other requests, and I/O-polling loops can exhaust the CPU limit. It does not fix request-owned timers (such as Effect.sleep) or request-bound async contexts.

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

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.

interface SchedulerDispatcher {
  flush(): void;
  scheduleTask(task: () => void, priority: number): void;
}

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

• PreventSchedulerYield for bypassing scheduler yield checks entirely rather than tuning the operation budget

declare const MaxOpsBeforeYield: Reference<number>

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

• MaxOpsBeforeYield for tuning yield frequency without disabling yield checks
• Scheduler for providing custom scheduler yield behavior

declare const PreventSchedulerYield: Reference<boolean>

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.

declare const Scheduler: Reference<Scheduler>

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.

interface Scheduler {
  readonly executionMode: "sync" | "async";
  makeDispatcher(): SchedulerDispatcher;
  shouldYield(fiber: Fiber<unknown, unknown>): boolean;
}