Introduce `Fiber#storage` for inheritable fiber-scoped variables. (#6612)

1 files changed, 40 insertions, 0 deletions

diff --git a/NEWS.md b/NEWS.md
index da15f8167d..b9ecdbef98 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -102,6 +102,45 @@ Note that each entry is kept to a minimum, see links for details.
 
 Note: We're only listing outstanding class updates.
 
+* Fiber
+
+    * Introduce `Fiber.[]` and `Fiber.[]=` for inheritable fiber storage.
+      Introduce `Fiber#storage` and `Fiber#storage=` (experimental) for getting
+      and resetting the current storage. Introduce `Fiber.new(storage:)` for
+      setting the storage when creating a fiber. [[Feature #19078]]
+
+      Existing Thread and Fiber local variables can be tricky to use. Thread
+      local variables are shared between all fibers, making it hard to isolate,
+      while Fiber local variables can be hard to share. It is often desirable
+      to define unit of execution ("execution context") such that some state
+      is shared between all fibers and threads created in that context. This is
+      what Fiber storage provides.
+
+      ```ruby
+      def log(message)
+        puts "#{Fiber[:request_id]}: #{message}"
+      end
+      
+      def handle_requests
+        while request = read_request
+          Fiber.schedule do
+            Fiber[:request_id] = SecureRandom.uuid
+
+            request.messages.each do |message|
+              Fiber.schedule do
+                log("Handling #{message}") # Log includes inherited request_id.
+              end
+            end
+          end
+        end
+      end
+      ```
+
+      You should generally consider Fiber storage for any state which you want
+      to be shared implicitly between all fibers and threads created in a given
+      context, e.g. a connection pool, a request id, a logger level,
+      environment variables, configuration, etc.
+
 * Fiber::Scheduler
 
     * Introduce `Fiber::Scheduler#io_select` for non-blocking IO.select.
@@ -555,3 +594,4 @@ The following deprecated APIs are removed.
 [Bug #19100]:     https://bugs.ruby-lang.org/issues/19100
 [Feature #19135]: https://bugs.ruby-lang.org/issues/19135
 [Feature #19138]: https://bugs.ruby-lang.org/issues/19138
+[Feature #19078]: https://bugs.ruby-lang.org/issues/19078