fiber.rbs in rbs-3.0.0.dev.3

- old
+ new

@@ -67,19 +67,44 @@
 # `blocking: false` (which is the default), and Fiber.scheduler should be set
 # with Fiber.set_scheduler. If Fiber.scheduler is not set in the current thread,
 # blocking and non-blocking fibers' behavior is identical.
 #
 # Ruby doesn't provide a scheduler class: it is expected to be implemented by
-# the user and correspond to Fiber::SchedulerInterface.
+# the user and correspond to Fiber::Scheduler.
 #
 # There is also Fiber.schedule method, which is expected to immediately perform
 # the given block in a non-blocking manner. Its actual implementation is up to
 # the scheduler.
 #
 class Fiber < Object
   # <!--
   #   rdoc-file=cont.c
+  #   - Fiber[key] -> value
+  # -->
+  # Returns the value of the fiber storage variable identified by `key`.
+  #
+  # The `key` must be a symbol, and the value is set by Fiber#[]= or Fiber#store.
+  #
+  # See also Fiber::[]=.
+  #
+  def self.[]: (Symbol | String) -> untyped
+
+  # <!--
+  #   rdoc-file=cont.c
+  #   - Fiber[key] = value
+  # -->
+  # Assign `value` to the fiber storage variable identified by `key`. The variable
+  # is created if it doesn't exist.
+  #
+  # `key` must be a Symbol, otherwise a TypeError is raised.
+  #
+  # See also Fiber::[].
+  #
+  def self.[]=: [A] (Symbol | String, A) -> A
+
+  # <!--
+  #   rdoc-file=cont.c
   #   - Fiber.blocking? -> false or 1
   # -->
   # Returns `false` if the current fiber is non-blocking. Fiber is non-blocking if
   # it was created via passing `blocking: false` to Fiber.new, or via
   # Fiber.schedule.
@@ -144,28 +169,28 @@
   # execution*, the scheduler takes care of properly resuming all the blocked
   # fibers.
   #
   # Note that the behavior described above is how the method is *expected* to
   # behave, actual behavior is up to the current scheduler's implementation of
-  # Fiber::SchedulerInterface#fiber method. Ruby doesn't enforce this method to
-  # behave in any particular way.
+  # Fiber::Scheduler#fiber method. Ruby doesn't enforce this method to behave in
+  # any particular way.
   #
   # If the scheduler is not set, the method raises `RuntimeError (No scheduler is
   # available!)`.
   #
   def self.schedule: () { () -> void } -> Fiber
 
   # <!--
   #   rdoc-file=cont.c
   #   - Fiber.scheduler -> obj or nil
   # -->
-  # Returns the Fiber scheduler, that was last set for the current thread with Fiber.set_scheduler.
-  #     Returns +nil+ if no scheduler is set (which is the default), and non-blocking fibers'
+  # Returns the Fiber scheduler, that was last set for the current thread with
+  # Fiber.set_scheduler. Returns `nil` if no scheduler is set (which is the
+  # default), and non-blocking fibers' behavior is the same as blocking. (see
+  # "Non-blocking fibers" section in class docs for details about the scheduler
+  # concept).
   #
-  # #  behavior is the same as blocking.
-  #     (see "Non-blocking fibers" section in class docs for details about the scheduler concept).
-  #
   def self.scheduler: () -> untyped?
 
   # <!--
   #   rdoc-file=cont.c
   #   - Fiber.set_scheduler(scheduler) -> scheduler
@@ -175,12 +200,12 @@
   # Fiber.schedule) call that scheduler's hook methods on potentially blocking
   # operations, and the current thread will call scheduler's `close` method on
   # finalization (allowing the scheduler to properly manage all non-finished
   # fibers).
   #
-  # `scheduler` can be an object of any class corresponding to
-  # Fiber::SchedulerInterface. Its implementation is up to the user.
+  # `scheduler` can be an object of any class corresponding to Fiber::Scheduler.
+  # Its implementation is up to the user.
   #
   # See also the "Non-blocking fibers" section in class docs.
   #
   def self.set_scheduler: (untyped) -> untyped
 
@@ -195,11 +220,11 @@
   #
   def self.yield: (*untyped) -> untyped
 
   # <!--
   #   rdoc-file=cont.c
-  #   - Fiber.new(blocking: false) { |*args| ... } -> fiber
+  #   - Fiber.new(blocking: false, storage: true) { |*args| ... } -> fiber
   # -->
   # Creates new Fiber. Initially, the fiber is not running and can be resumed with
   # #resume. Arguments to the first #resume call will be passed to the block:
   #
   #     f = Fiber.new do |initial|
@@ -216,11 +241,36 @@
   #
   # If `blocking: false` is passed to `Fiber.new`, *and* current thread has a
   # Fiber.scheduler defined, the Fiber becomes non-blocking (see "Non-blocking
   # Fibers" section in class docs).
   #
-  def initialize: (?blocking: boolish) { (*untyped) -> void } -> void
+  # If the `storage` is unspecified, the default is to inherit a copy of the
+  # storage from the current fiber. This is the same as specifying `storage:
+  # true`.
+  #
+  #     Fiber[:x] = 1
+  #     Fiber.new do
+  #       Fiber[:x] # => 1
+  #       Fiber[:x] = 2
+  #     end.resume
+  #     Fiber[:x] # => 1
+  #
+  # If the given `storage` is `nil`, this function will lazy initialize the
+  # internal storage, which starts as an empty hash.
+  #
+  #     Fiber[:x] = "Hello World"
+  #     Fiber.new(storage: nil) do
+  #       Fiber[:x] # nil
+  #     end
+  #
+  # Otherwise, the given `storage` is used as the new fiber's storage, and it must
+  # be an instance of Hash.
+  #
+  # Explicitly using `storage: true` is currently experimental and may change in
+  # the future.
+  #
+  def initialize: (?blocking: boolish, ?storage: true | Hash[Symbol | String, untyped] | nil) { (*untyped) -> void } -> void
 
   # <!--
   #   rdoc-file=cont.c
   #   - fiber.alive? -> true or false
   # -->
@@ -354,9 +404,42 @@
   # Alternatively, when resume is called it evaluates to the arguments passed to
   # the next Fiber.yield statement inside the fiber's block or to the block value
   # if it runs to completion without any Fiber.yield
   #
   def resume: (*untyped) -> untyped
+
+  # <!--
+  #   rdoc-file=cont.c
+  #   - fiber.storage -> hash (dup)
+  # -->
+  # Returns a copy of the storage hash for the fiber. The method can only be
+  # called on the Fiber.current.
+  #
+  def storage: () -> Hash[Symbol | String, untyped]
+
+  # <!--
+  #   rdoc-file=cont.c
+  #   - fiber.storage = hash
+  # -->
+  # Sets the storage hash for the fiber. This feature is experimental and may
+  # change in the future. The method can only be called on the Fiber.current.
+  #
+  # You should be careful about using this method as you may inadvertently clear
+  # important fiber-storage state. You should mostly prefer to assign specific
+  # keys in the storage using Fiber::[]=.
+  #
+  # You can also use `Fiber.new(storage: nil)` to create a fiber with an empty
+  # storage.
+  #
+  # Example:
+  #
+  #     while request = request_queue.pop
+  #       # Reset the per-request state:
+  #       Fiber.current.storage = nil
+  #       handle_request(request)
+  #     end
+  #
+  def storage=: (Hash[Symbol | String, untyped]) -> Hash[Symbol | String, untyped]
 
   # <!--
   #   rdoc-file=cont.c
   #   - to_s()
   # -->