Enhance documentation for ExecutionContext (#15665)

Co-authored-by: Sijawusz Pur Rahnama <[email protected]>
Co-authored-by: Julien Portalier <[email protected]>

Author: 3 people

src/concurrent.cr

@@ -39,6 +39,9 @@ end
 {% begin %}
 # Spawns a new fiber.
 #
+# When using execution contexts, the fiber spawns into the current execution
+# context (`Fiber::ExecutionContext.current`).
+#
 # NOTE: The newly created fiber doesn't run as soon as spawned.
 #
 # Example:
@@ -85,6 +88,9 @@ end
 # Spawns a fiber by first creating a `Proc`, passing the *call*'s
 # expressions to it, and letting the `Proc` finally invoke the *call*.
 #
+# When using execution contexts, the fiber spawns into the current execution
+# context (`Fiber::ExecutionContext.current`).
+#
 # Compare this:
 #
 # ```

src/fiber/execution_context.cr

@@ -8,12 +8,73 @@ require "./execution_context/*"
 {% raise "ERROR: execution contexts require the `preview_mt` compilation flag" unless flag?(:preview_mt) || flag?(:docs) %}
 {% raise "ERROR: execution contexts require the `execution_context` compilation flag" unless flag?(:execution_context) || flag?(:docs) %}
 
+# 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](https://github.com/crystal-lang/rfcs/pull/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]
 module Fiber::ExecutionContext
   @@default : ExecutionContext?
 
   # Returns the default `ExecutionContext` for the process, automatically
   # started when the program started.
+  #
+  # NOTE: The default context is a `SingleThreaded` context for backwards
+  # compatibility reasons. It may change to a multi-threaded default context in
+  # the future.
   @[AlwaysInline]
   def self.default : ExecutionContext
     @@default.not_nil!("expected default execution context to have been setup")

src/fiber/execution_context/isolated.cr

@@ -2,7 +2,7 @@ require "./scheduler"
 require "../list"
 
 module Fiber::ExecutionContext
-  # ST scheduler. Owns a single thread running a single fiber.
+  # Isolated execution context. Runs a single thread with a single fiber.
   #
   # Concurrency is disabled within the thread: the fiber owns the thread and the
   # thread can only run this fiber. Keep in mind that the fiber will still run

src/fiber/execution_context/multi_threaded.cr

@@ -2,16 +2,28 @@ require "./global_queue"
 require "./multi_threaded/scheduler"
 
 module Fiber::ExecutionContext
-  # MT scheduler.
+  # A multi-threaded execution context which owns one or more threads. It's
+  # fully concurrent and fully parallel.
   #
   # Owns multiple threads and starts a scheduler in each one. The number of
   # threads is dynamic. Setting the minimum and maximum to the same value will
   # start a fixed number of threads.
   #
-  # Fully concurrent, fully parallel: fibers running in this context can be
-  # resumed by any thread in the context; fibers can run concurrently and in
-  # parallel to each other, in addition to running in parallel to every other
-  # fibers running in other contexts.
+  # Fibers running in this context can be resumed by any thread in the context.
+  # Fibers can run concurrently and in parallel to each other, in addition to
+  # running in parallel to any other fiber running in other contexts.
+  #
+  # ```
+  # mt_context = Fiber::ExecutionContext::MultiThreaded.new("worker-threads", 4)
+  #
+  # 10.times do
+  #   mt_context.spawn do
+  #     do_something
+  #   end
+  # end
+  #
+  # sleep
+  # ```
   class MultiThreaded
     include ExecutionContext
 

src/fiber/execution_context/single_threaded.cr

@@ -3,12 +3,19 @@ require "./runnables"
 require "./scheduler"
 
 module Fiber::ExecutionContext
-  # ST scheduler. Owns a single thread.
+  # A single-threaded execution context which owns a single thread. It's fully
+  # concurrent with limited parallelism.
   #
-  # Fully concurrent with limited parallelism: concurrency is restricted to this
-  # single thread. Fibers running in this context will never run in parallel to
-  # each other but they may still run in parallel to fibers running in other
-  # contexts (i.e. another thread).
+  # Concurrency is restricted to a single thread. Fibers in the same context
+  # will never run in parallel to each other but they may still run in parallel
+  # to fibers running in other contexts (i.e. in another thread).
+  #
+  # Fibers can use simpler and faster synchronization primitives between
+  # themselves (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.
   class SingleThreaded
     include ExecutionContext
     include ExecutionContext::Scheduler