module Fiber::ExecutionContext

Overview

An execution context creates and manages a dedicated pool of 1 or more threads where fibers can be executed into. Each context manages the rules to run, suspend and swap fibers internally.

EXPERIMENTAL Execution contexts are an experimental feature, implementing RFC 2. It's opt-in and requires the compiler flags -Dpreview_mt -Dexecution_context.

Applications can create any number of execution contexts in parallel. These contexts are isolated but they can communicate with the usual thread-safe synchronization primitives (e.g. Channel, Mutex).

An execution context groups fibers together. Instead of associating a fiber to a specific thread, we associate a fiber to an execution context, abstracting which thread(s) they actually run on.

When spawning a fiber with ::spawn, it spawns into the execution context of the current fiber. Thus child fibers execute in the same context as their parent (unless told otherwise).

Once spawned, a fiber cannot move to another execution context. It always resumes in the same execution context.

Context types

The standard library provides a number of execution context implementations for common use cases.

• ExecutionContext::SingleThreaded: Fully concurrent with limited parallelism. Fibers run concurrently in a single thread and never in parallel. They can use simpler and faster synchronization primitives internally (no atomics, no thread safety). Communication with fibers in other contexts requires thread-safe primitives. A blocking fiber blocks the entire thread and all other fibers in the context.
• ExecutionContext::MultiThreaded: Fully concurrent, fully parallel. Fibers running in this context can be resumed by any thread in this context. They run concurrently and in parallel to each other, in addition to running in parallel to any fibers in other contexts. Schedulers steal work from each other. The number of threads can grow and shrink dynamically.
• ExecutionContext::Isolated: Single fiber in a single thread without concurrency. This is useful for tasks that can block thread execution for a long time (e.g. a GUI main loop, a game loop, or CPU heavy computation). The event-loop works normally (when the fiber sleeps, it pauses the thread). Communication with fibers in other contexts requires thread-safe primitives.

The default execution context

The Crystal runtime starts with a single threaded execution context, available in Fiber::ExecutionContext.default.

Fiber::ExecutionContext.default.class # => Fiber::ExecutionContext::SingleThreaded

NOTE The single threaded default context is required for backwards compatibility. It may change to a multi-threaded default context in the future.

EXPERIMENTAL

Direct including types

• Fiber::ExecutionContext::Isolated
• Fiber::ExecutionContext::MultiThreaded
• Fiber::ExecutionContext::SingleThreaded

Defined in:

fiber/execution_context.cr
fiber/execution_context/global_queue.cr
fiber/execution_context/isolated.cr
fiber/execution_context/monitor.cr
fiber/execution_context/multi_threaded.cr
fiber/execution_context/multi_threaded/scheduler.cr
fiber/execution_context/runnables.cr
fiber/execution_context/scheduler.cr
fiber/execution_context/single_threaded.cr

Constructors

• .current : ExecutionContext

  Returns the ExecutionContext the current fiber is running in.

• .default : ExecutionContext

  Returns the default ExecutionContext for the process, automatically started when the program started.

Class Method Summary

• .default_workers_count : Int32

  Returns the number of threads to start in the default multi threaded execution context.

• .each(&) : Nil

  Iterates all execution contexts.

Instance Method Summary

• #spawn(*, name : String | Nil = nil, &block : -> ) : Fiber

  Creates a new fiber then calls #enqueue to add it to the execution context.

Constructor Detail

Class Method Detail

Instance Method Detail