rbs 2.8.4 → 3.8.1

data/core/false_class.rbs

@@ -4,42 +4,54 @@
 # operators allowing `false` to participate correctly in logical expressions.
 #
 class FalseClass
-  public
-
   def !: () -> true
 
   # <!--
   #   rdoc-file=object.c
-  #   - false & obj   -> false
-  #   - nil & obj     -> false
+  #   - false & object -> false
+  #   - nil & object   -> false
   # -->
-  # And---Returns `false`. *obj* is always evaluated as it is the argument to a
-  # method call---there is no short-circuit evaluation in this case.
+  # Returns `false`:
+  #
+  #     false & true       # => false
+  #     false & Object.new # => false
+  #
+  # Argument `object` is evaluated:
+  #
+  #     false & raise # Raises RuntimeError.
   #
   def &: (untyped obj) -> false
 
   # <!--
   #   rdoc-file=object.c
-  #   - obj === other   -> true or false
+  #   - true === other -> true or false
+  #   - false === other -> true or false
+  #   - nil === other -> true or false
   # -->
-  # Case Equality -- For class Object, effectively the same as calling `#==`, but
-  # typically overridden by descendants to provide meaningful semantics in `case`
-  # statements.
+  # Returns `true` or `false`.
+  #
+  # Like Object#==, if `object` is an instance of Object (and not an instance of
+  # one of its many subclasses).
+  #
+  # This method is commonly overridden by those subclasses, to provide meaningful
+  # semantics in `case` statements.
   #
   def ===: (false) -> true
-         | (untyped obj) -> false
+         | (untyped obj) -> bool
 
   # <!--
   #   rdoc-file=object.c
-  #   - false ^ obj    -> true or false
-  #   - nil   ^ obj    -> true or false
+  #   - false ^ object -> true or false
+  #   - nil ^ object   -> true or false
   # -->
-  # Exclusive Or---If *obj* is `nil` or `false`, returns `false`; otherwise,
-  # returns `true`.
+  # Returns `false` if `object` is `nil` or `false`, `true` otherwise:
+  #
+  #     nil ^ nil        # => false
+  #     nil ^ false      # => false
+  #     nil ^ Object.new # => true
   #
-  def ^: (nil) -> false
-       | (false) -> false
-       | (untyped obj) -> true
+  def ^: (false | nil) -> false
+       | (untyped obj) -> bool
 
   # <!-- rdoc-file=object.c -->
   # The string representation of `false` is "false".
@@ -56,14 +68,15 @@ class FalseClass
 
   # <!--
   #   rdoc-file=object.c
-  #   - false | obj   ->   true or false
-  #   - nil   | obj   ->   true or false
+  #   - false | object -> true or false
+  #   - nil   | object -> true or false
   # -->
-  # Or---Returns `false` if *obj* is `nil` or `false`; `true` otherwise.
+  # Returns `false` if `object` is `nil` or `false`, `true` otherwise:
   #
-  def |: (nil) -> false
-       | (false) -> false
-       | (untyped obj) -> true
-
-  def clone: (?freeze: true?) -> self
+  #     nil | nil        # => false
+  #     nil | false      # => false
+  #     nil | Object.new # => true
+  #
+  def |: (nil | false) -> false
+       | (untyped obj) -> bool
 end

data/core/fiber.rbs

@@ -69,13 +69,38 @@
 # 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) -> 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, A) -> A
+
   # <!--
   #   rdoc-file=cont.c
   #   - Fiber.blocking? -> false or 1
@@ -146,8 +171,8 @@ class Fiber < Object
   #
   # 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!)`.
@@ -158,11 +183,11 @@ class Fiber < Object
   #   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'
-  #
-  # #  behavior is the same as blocking.
-  #     (see "Non-blocking fibers" section in class docs for details about the scheduler concept).
+  # 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).
   #
   def self.scheduler: () -> untyped?
 
@@ -177,8 +202,8 @@ class Fiber < Object
   # 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.
   #
@@ -197,7 +222,7 @@ class Fiber < Object
 
   # <!--
   #   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:
@@ -218,7 +243,32 @@ class Fiber < Object
   # 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[interned, untyped] | nil) { (?) -> void } -> void
 
   # <!--
   #   rdoc-file=cont.c
@@ -319,6 +369,27 @@ class Fiber < Object
   #
   alias inspect to_s
 
+  # <!--
+  #   rdoc-file=cont.c
+  #   - fiber.kill -> nil
+  # -->
+  # Terminates the fiber by raising an uncatchable exception. It only terminates
+  # the given fiber and no other fiber, returning `nil` to another fiber if that
+  # fiber was calling #resume or #transfer.
+  #
+  # `Fiber#kill` only interrupts another fiber when it is in Fiber.yield. If
+  # called on the current fiber then it raises that exception at the `Fiber#kill`
+  # call site.
+  #
+  # If the fiber has not been started, transition directly to the terminated
+  # state.
+  #
+  # If the fiber is already terminated, does nothing.
+  #
+  # Raises FiberError if called on a fiber belonging to another thread.
+  #
+  def kill: () -> nil
+
   # <!--
   #   rdoc-file=cont.c
   #   - fiber.raise                                 -> obj
@@ -339,8 +410,12 @@ class Fiber < Object
   # parameter is an array of callback information. Exceptions are caught by the
   # `rescue` clause of `begin...end` blocks.
   #
+  # Raises `FiberError` if called on a Fiber belonging to another `Thread`.
+  #
+  # See Kernel#raise for more information.
+  #
   def raise: (?string msg) -> untyped
-           | (_Exception, ?string msg, ?Array[string] backtrace) -> untyped
+           | (_Exception, ?string msg, ?Array[string] | Array[Thread::Backtrace::Location] | nil backtrace) -> untyped
 
   # <!--
   #   rdoc-file=cont.c
@@ -357,6 +432,39 @@ class Fiber < Object
   #
   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[interned, 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[interned, untyped]) -> Hash[interned, untyped]
+
   # <!--
   #   rdoc-file=cont.c
   #   - to_s()
@@ -387,7 +495,6 @@ class Fiber < Object
   #     transferred back, and if it had yielded, it only can be resumed back.
   #     After that, it again can transfer or yield.
   #
-  #
   # If those rules are broken FiberError is raised.
   #
   # For an individual Fiber design, yield/resume is easier to use (the Fiber just