rbs 2.8.4 → 3.8.1

data/core/thread.rbs

@@ -226,7 +226,7 @@ class Thread < Object
   # For thread-local variables, please see #thread_variable_get and
   # #thread_variable_set.
   #
-  def []: (String | Symbol key) -> untyped
+  def []: (interned key) -> untyped
 
   # <!--
   #   rdoc-file=thread.c
@@ -240,7 +240,7 @@ class Thread < Object
   # For thread-local variables, please see #thread_variable_set and
   # #thread_variable_get.
   #
-  def []=: (String | Symbol key, untyped value) -> untyped
+  def []=: (interned key, untyped value) -> untyped
 
   # <!--
   #   rdoc-file=thread.c
@@ -382,7 +382,7 @@ class Thread < Object
   # If you're going to subclass Thread, be sure to call super in your `initialize`
   # method, otherwise a ThreadError will be raised.
   #
-  def initialize: (*untyped) { (*untyped) -> void } -> void
+  def initialize: (*untyped) { (?) -> void } -> void
 
   # <!--
   #   rdoc-file=thread.c
@@ -485,7 +485,6 @@ class Thread < Object
   # *   On Windows it is the thread identifier returned by GetThreadId().
   # *   On other platforms, it raises NotImplementedError.
   #
-  #
   # NOTE: If the thread is not associated yet or already deassociated with a
   # native thread, it returns *nil*. If the Ruby implementation uses M:N thread
   # model, the ID may change depending on the timing.
@@ -614,12 +613,16 @@ class Thread < Object
   #
   # `"sleep"`
   # :   Returned if this thread is sleeping or waiting on I/O
+  #
   # `"run"`
   # :   When this thread is executing
+  #
   # `"aborting"`
   # :   If this thread is aborting
+  #
   # `false`
   # :   When this thread is terminated normally
+  #
   # `nil`
   # :   If terminated with an exception.
   #
@@ -676,7 +679,7 @@ class Thread < Object
   # Note that these are not fiber local variables.  Please see Thread#[] and
   # Thread#thread_variable_get for more details.
   #
-  def thread_variable?: (String | Symbol key) -> bool
+  def thread_variable?: (interned key) -> bool
 
   # <!--
   #   rdoc-file=thread.c
@@ -817,6 +820,15 @@ class Thread < Object
   #
   def self.abort_on_exception=: (untyped abort_on_exception) -> untyped
 
+  # <!--
+  #   rdoc-file=vm_backtrace.c
+  #   - Thread.each_caller_location(...) { |loc| ... } -> nil
+  # -->
+  # Yields each frame of the current execution stack as a backtrace location
+  # object.
+  #
+  def self.each_caller_location: () { (Backtrace::Location) -> void } -> nil
+
   # Wraps the block in a single, VM-global
   # [Mutex\#synchronize](https://ruby-doc.org/core-2.6.3/Mutex.html#method-i-synchronize)
   # , returning the value of the block. A thread executing inside the
@@ -864,8 +876,10 @@ class Thread < Object
   #
   # `:immediate`
   # :   Invoke interrupts immediately.
+  #
   # `:on_blocking`
   # :   Invoke interrupts while *BlockingOperation*.
+  #
   # `:never`
   # :   Never invoke all interrupts.
   #
@@ -914,30 +928,6 @@ class Thread < Object
   # resource allocation code. Then, the ensure block is where we can safely
   # deallocate your resources.
   #
-  # #### Guarding from Timeout::Error
-  #
-  # In the next example, we will guard from the Timeout::Error exception. This
-  # will help prevent from leaking resources when Timeout::Error exceptions occur
-  # during normal ensure clause. For this example we use the help of the standard
-  # library Timeout, from lib/timeout.rb
-  #
-  #     require 'timeout'
-  #     Thread.handle_interrupt(Timeout::Error => :never) {
-  #       timeout(10){
-  #         # Timeout::Error doesn't occur here
-  #         Thread.handle_interrupt(Timeout::Error => :on_blocking) {
-  #           # possible to be killed by Timeout::Error
-  #           # while blocking operation
-  #         }
-  #         # Timeout::Error doesn't occur here
-  #       }
-  #     }
-  #
-  # In the first part of the `timeout` block, we can rely on Timeout::Error being
-  # ignored. Then in the `Timeout::Error => :on_blocking` block, any operation
-  # that will block the calling thread is susceptible to a Timeout::Error
-  # exception being raised.
-  #
   # #### Stack control settings
   #
   # It's possible to stack multiple levels of ::handle_interrupt blocks in order
@@ -962,6 +952,29 @@ class Thread < Object
   #
   def self.handle_interrupt: (untyped hash) -> untyped
 
+  # <!--
+  #   rdoc-file=thread.c
+  #   - thr.raise
+  #   - thr.raise(string)
+  #   - thr.raise(exception [, string [, array]])
+  # -->
+  # Raises an exception from the given thread. The caller does not have to be
+  # `thr`. See Kernel#raise for more information.
+  #
+  #     Thread.abort_on_exception = true
+  #     a = Thread.new { sleep(200) }
+  #     a.raise("Gotcha")
+  #
+  # This will produce:
+  #
+  #     prog.rb:3: Gotcha (RuntimeError)
+  #      from prog.rb:2:in `initialize'
+  #      from prog.rb:2:in `new'
+  #      from prog.rb:2
+  #
+  def raise: (?String message) -> nil
+           | (_Exception, ?_ToS message, ?Array[Thread::Backtrace::Location] | Array[String] | nil backtrace) -> nil
+
   # <!--
   #   rdoc-file=thread.c
   #   - Thread.kill(thread)   -> thread
@@ -1098,7 +1111,6 @@ class Thread < Object
   #     However, this might handle the exception much later, or not at all if the
   #     Thread is never joined due to the parent thread being blocked, etc.
   #
-  #
   # See also ::report_on_exception=.
   #
   # There is also an instance level method to set this for a specific thread, see
@@ -1146,7 +1158,7 @@ class Thread < Object
   # calling `start` in that subclass will not invoke the subclass's `initialize`
   # method.
   #
-  def self.start: (*untyped args) { (*untyped) -> void } -> instance
+  def self.start: (*untyped args) { (?) -> void } -> instance
 
   # <!--
   #   rdoc-file=thread.c
@@ -1173,10 +1185,10 @@ end
 class Thread::Backtrace < Object
   # <!--
   #   rdoc-file=vm_backtrace.c
-  #   - Threade::Backtrace::limit -> integer
+  #   - Thread::Backtrace::limit -> integer
   # -->
   # Returns maximum backtrace length set by `--backtrace-limit` command-line
-  # option. The defalt is `-1` which means unlimited backtraces. If the value is
+  # option. The default is `-1` which means unlimited backtraces. If the value is
   # zero or positive, the error backtraces, produced by Exception#full_message,
   # are abbreviated and the extra lines are replaced by `... 3 levels... `
   #
@@ -1286,9 +1298,28 @@ class Thread::Backtrace::Location
   #   rdoc-file=vm_backtrace.c
   #   - base_label()
   # -->
-  # Returns the base label of this frame.
+  # Returns the base label of this frame, which is usually equal to the label,
+  # without decoration.
+  #
+  # Consider the following example:
   #
-  # Usually same as #label, without decoration.
+  #     def foo
+  #       puts caller_locations(0).first.base_label
+  #
+  #       1.times do
+  #         puts caller_locations(0).first.base_label
+  #
+  #         1.times do
+  #           puts caller_locations(0).first.base_label
+  #         end
+  #       end
+  #     end
+  #
+  # The result of calling `foo` is this:
+  #
+  #     foo
+  #     foo
+  #     foo
   #
   def base_label: () -> String?
 
@@ -1311,15 +1342,14 @@ class Thread::Backtrace::Location
   #         1.times do
   #           puts caller_locations(0).first.label
   #         end
-  #
   #       end
   #     end
   #
   # The result of calling `foo` is this:
   #
-  #     label: foo
-  #     label: block in foo
-  #     label: block (2 levels) in foo
+  #     foo
+  #     block in foo
+  #     block (2 levels) in foo
   #
   def label: () -> String?
 
@@ -1405,7 +1435,7 @@ class Thread::ConditionVariable < Object
   #
   # Returns the slept result on `mutex`.
   #
-  def wait: (Thread::Mutex mutex, ?Integer timeout) -> self
+  def wait: (Thread::Mutex mutex, ?Time::_Timeout? timeout) -> Integer?
 end
 
 # <!-- rdoc-file=thread_sync.c -->
@@ -1488,8 +1518,8 @@ end
 # exchanged safely between multiple threads. The Thread::Queue class implements
 # all the required locking semantics.
 #
-# The class implements FIFO type of queue. In a FIFO queue, the first tasks
-# added are the first retrieved.
+# The class implements FIFO (first in, first out) type of queue. In a FIFO
+# queue, the first tasks added are the first retrieved.
 #
 # Example:
 #
@@ -1497,23 +1527,23 @@ end
 #
 #     producer = Thread.new do
 #       5.times do |i|
-#          sleep rand(i) # simulate expense
-#          queue << i
-#          puts "#{i} produced"
+#         sleep rand(i) # simulate expense
+#         queue << i
+#         puts "#{i} produced"
 #       end
 #     end
 #
 #     consumer = Thread.new do
 #       5.times do |i|
-#          value = queue.pop
-#          sleep rand(i/2) # simulate expense
-#          puts "consumed #{value}"
+#         value = queue.pop
+#         sleep rand(i/2) # simulate expense
+#         puts "consumed #{value}"
 #       end
 #     end
 #
 #     consumer.join
 #
-class Thread::Queue < Object
+class Thread::Queue[Elem = untyped] < Object
   # <!-- rdoc-file=thread_sync.c -->
   # Pushes the given `object` to the queue.
   #
@@ -1546,7 +1576,6 @@ class Thread::Queue < Object
   # *   when `empty?` is true, deq(false) will not suspend the thread and will
   #     return nil. deq(true) will raise a `ThreadError`.
   #
-  #
   # ClosedQueueError is inherited from StopIteration, so that you can break loop
   # block.
   #
@@ -1570,12 +1599,10 @@ class Thread::Queue < Object
   #
   def closed?: () -> bool
 
-  # <!-- rdoc-file=thread_sync.c -->
-  # Retrieves data from the queue.
-  #
-  # If the queue is empty, the calling thread is suspended until data is pushed
-  # onto the queue. If `non_block` is true, the thread isn't suspended, and
-  # `ThreadError` is raised.
+  # <!--
+  #   rdoc-file=thread_sync.rb
+  #   - deq(non_block = false, timeout: nil)
+  # -->
   #
   alias deq pop
 
@@ -1592,6 +1619,15 @@ class Thread::Queue < Object
   #
   alias enq push
 
+  # <!--
+  #   rdoc-file=thread_sync.c
+  #   - freeze
+  # -->
+  # The queue can't be frozen, so this method raises an exception:
+  #     Thread::Queue.new.freeze # Raises TypeError (cannot freeze #<Thread::Queue:0x...>)
+  #
+  def freeze: () -> bot
+
   # <!--
   #   rdoc-file=thread_sync.c
   #   - length
@@ -1610,10 +1646,8 @@ class Thread::Queue < Object
   def num_waiting: () -> Integer
 
   # <!--
-  #   rdoc-file=thread_sync.c
-  #   - pop(non_block=false)
-  #   - deq(non_block=false)
-  #   - shift(non_block=false)
+  #   rdoc-file=thread_sync.rb
+  #   - pop(non_block=false, timeout: nil)
   # -->
   # Retrieves data from the queue.
   #
@@ -1621,7 +1655,10 @@ class Thread::Queue < Object
   # onto the queue. If `non_block` is true, the thread isn't suspended, and
   # `ThreadError` is raised.
   #
-  def pop: (?boolish non_block) -> untyped
+  # If `timeout` seconds have passed and no data is available `nil` is returned.
+  # If `timeout` is `0` it returns immediately.
+  #
+  def pop: (?boolish non_block, ?timeout: _ToF?) -> Elem?
 
   # <!--
   #   rdoc-file=thread_sync.c
@@ -1631,14 +1668,12 @@ class Thread::Queue < Object
   # -->
   # Pushes the given `object` to the queue.
   #
-  def push: (untyped obj) -> void
+  def push: (Elem obj) -> void
 
-  # <!-- rdoc-file=thread_sync.c -->
-  # Retrieves data from the queue.
-  #
-  # If the queue is empty, the calling thread is suspended until data is pushed
-  # onto the queue. If `non_block` is true, the thread isn't suspended, and
-  # `ThreadError` is raised.
+  # <!--
+  #   rdoc-file=thread_sync.rb
+  #   - shift(non_block = false, timeout: nil)
+  # -->
   #
   alias shift pop
 
@@ -1654,25 +1689,30 @@ end
 #
 # See Thread::Queue for an example of how a Thread::SizedQueue works.
 #
-class Thread::SizedQueue < Thread::Queue
-  # <!-- rdoc-file=thread_sync.c -->
-  # Pushes `object` to the queue.
-  #
-  # If there is no space left in the queue, waits until space becomes available,
-  # unless `non_block` is true.  If `non_block` is true, the thread isn't
-  # suspended, and `ThreadError` is raised.
+class Thread::SizedQueue[Elem = untyped] < Thread::Queue[Elem]
+  # <!--
+  #   rdoc-file=thread_sync.rb
+  #   - <<(object, non_block = false, timeout: nil)
+  # -->
   #
   alias << push
 
-  # <!-- rdoc-file=thread_sync.c -->
-  # Pushes `object` to the queue.
-  #
-  # If there is no space left in the queue, waits until space becomes available,
-  # unless `non_block` is true.  If `non_block` is true, the thread isn't
-  # suspended, and `ThreadError` is raised.
+  # <!--
+  #   rdoc-file=thread_sync.rb
+  #   - enq(object, non_block = false, timeout: nil)
+  # -->
   #
   alias enq push
 
+  # <!--
+  #   rdoc-file=thread_sync.c
+  #   - freeze
+  # -->
+  # The queue can't be frozen, so this method raises an exception:
+  #     Thread::Queue.new.freeze # Raises TypeError (cannot freeze #<Thread::Queue:0x...>)
+  #
+  def freeze: () -> bot
+
   # <!--
   #   rdoc-file=thread_sync.c
   #   - new(max)
@@ -1698,9 +1738,9 @@ class Thread::SizedQueue < Thread::Queue
   def max=: (Integer max) -> void
 
   # <!--
-  #   rdoc-file=thread_sync.c
-  #   - push(object, non_block=false)
-  #   - enq(object, non_block=false)
+  #   rdoc-file=thread_sync.rb
+  #   - push(object, non_block=false, timeout: nil)
+  #   - enq(object, non_block=false, timeout: nil)
   #   - <<(object)
   # -->
   # Pushes `object` to the queue.
@@ -1709,13 +1749,17 @@ class Thread::SizedQueue < Thread::Queue
   # unless `non_block` is true.  If `non_block` is true, the thread isn't
   # suspended, and `ThreadError` is raised.
   #
-  def push: (untyped obj, ?boolish non_block) -> void
+  # If `timeout` seconds have passed and no space is available `nil` is returned.
+  # If `timeout` is `0` it returns immediately. Otherwise it returns `self`.
+  #
+  def push: (Elem obj, ?boolish non_block) -> void
+          | (Elem obj, timeout: _ToF?) -> self?
 end
 
-ConditionVariable: singleton(Thread::ConditionVariable)
+class ConditionVariable = Thread::ConditionVariable
 
-Mutex: singleton(Thread::Mutex)
+class Mutex = Thread::Mutex
 
-Queue: singleton(Thread::Queue)
+class Queue = Thread::Queue
 
-SizedQueue: singleton(Thread::SizedQueue)
+class SizedQueue = Thread::SizedQueue

data/core/thread_group.rbs

@@ -8,7 +8,13 @@
 # Newly created threads belong to the same group as the thread from which they
 # were created.
 #
-class ThreadGroup < Object
+class ThreadGroup
+  # <!-- rdoc-file=thread.c -->
+  # The default ThreadGroup created when Ruby starts; all Threads belong to it by
+  # default.
+  #
+  Default: ThreadGroup
+
   # <!--
   #   rdoc-file=thread.c
   #   - thgrp.add(thread)   -> thgrp
@@ -34,7 +40,7 @@ class ThreadGroup < Object
   #     Initial group now #<Thread:0x401b3c18>#<Thread:0x401bdf4c>
   #     tg group now #<Thread:0x401b3c90>
   #
-  def add: (Thread thread) -> ThreadGroup
+  def add: (Thread thread) -> self
 
   # <!--
   #   rdoc-file=thread.c
@@ -69,11 +75,5 @@ class ThreadGroup < Object
   #
   #     ThreadGroup::Default.list   #=> [#<Thread:0x401bdf4c run>]
   #
-  def list: () -> ::Array[Thread]
+  def list: () -> Array[Thread]
 end
-
-# <!-- rdoc-file=thread.c -->
-# The default ThreadGroup created when Ruby starts; all Threads belong to it by
-# default.
-#
-ThreadGroup::Default: ThreadGroup