module Fiber::ExecutionContext

Overview

An execution context creates and manages a dedicated pool of 1 or more schedulers where fibers will be running in. 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 synchronization primitives such as Channel or Mutex.

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

When spawning a fiber with ::spawn, it spawns into the execution context of the current fiber, so 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::Concurrent: Fully concurrent with limited parallelism. Fibers run concurrently, never in parallel (only one fiber at a time). They can use simpler and faster synchronization primitives internally (no atomics, limited 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::Parallel: Fully concurrent, fully parallel. Fibers running in this context can be resumed by multiple system threads in this context. They run concurrently and in parallel to each other (multiple fibers at a time), in addition to running in parallel to any fibers in other contexts. Schedulers steal work from each other. The parallelism can grow and shrink dynamically.
• ExecutionContext::Isolated: Single fiber in a single system 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 as Fiber::ExecutionContext.default:

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

NOTE The default context is a Concurrent context for backwards compatibility reasons. It might change to a Parallel context in the future.

EXPERIMENTAL

Direct including types

• Fiber::ExecutionContext::Concurrent
• Fiber::ExecutionContext::Isolated
• Fiber::ExecutionContext::Parallel

Defined in:

fiber/execution_context.cr
fiber/execution_context/concurrent.cr
fiber/execution_context/global_queue.cr
fiber/execution_context/isolated.cr
fiber/execution_context/monitor.cr
fiber/execution_context/parallel.cr
fiber/execution_context/parallel/scheduler.cr
fiber/execution_context/runnables.cr
fiber/execution_context/scheduler.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

• .current? : ExecutionContext | Nil
• .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