Merge pull request #2731 from ruby/type-definitions

Update RBS files for Ruby 4

Author: soutaro

core/fiber.rbs

@@ -425,8 +425,8 @@ class Fiber < Object
   #
   # See Kernel#raise for more information.
   #
-  def raise: (?string msg) -> untyped
-           | (_Exception, ?string msg, ?Array[string] | Array[Thread::Backtrace::Location] | nil backtrace) -> untyped
+  def raise: (?string msg, ?cause: Exception?) -> untyped
+           | (_Exception, ?string msg, ?Array[string] | Array[Thread::Backtrace::Location] | nil backtrace, ?cause: Exception?) -> untyped
 
   # <!--
   #   rdoc-file=cont.c

core/math.rbs

@@ -410,6 +410,27 @@ module Math
   #
   def self.exp: (double x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.expm1(x) -> float
+  # -->
+  # Returns "exp(x) - 1", `e` raised to the `x` power, minus 1.
+  #
+  # *   Domain: `[-INFINITY, INFINITY]`.
+  # *   Range: `[-1.0, INFINITY]`.
+  #
+  # Examples:
+  #
+  #     expm1(-INFINITY) # => 0.0
+  #     expm1(-1.0)      # => -0.6321205588285577 # 1.0/E - 1
+  #     expm1(0.0)       # => 0.0
+  #     expm1(0.5)       # => 0.6487212707001282  # sqrt(E) - 1
+  #     expm1(1.0)       # => 1.718281828459045   # E - 1
+  #     expm1(2.0)       # => 6.38905609893065    # E**2 - 1
+  #     expm1(INFINITY)  # => Infinity
+  #
+  def self.expm1: (double x) -> Float
+
   # <!--
   #   rdoc-file=math.c
   #   - Math.frexp(x) -> [fraction, exponent]
@@ -602,6 +623,25 @@ module Math
   #
   def self.log10: (double x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.log1p(x) -> float
+  # -->
+  # Returns "log(x + 1)", the base E
+  # [logarithm](https://en.wikipedia.org/wiki/Logarithm) of (`x` + 1).
+  #
+  # *   Domain: `[-1, INFINITY]`.
+  # *   Range: `[-INFINITY, INFINITY]`.
+  #
+  # Examples:
+  #
+  #     log1p(-1.0)     # => -Infinity
+  #     log1p(0.0)      # => 0.0
+  #     log1p(E - 1)    # => 1.0
+  #     log1p(INFINITY) # => Infinity
+  #
+  def self.log1p: (double x) -> Float
+
   # <!--
   #   rdoc-file=math.c
   #   - Math.log2(x) -> float

core/object_space.rbs

@@ -29,6 +29,7 @@ module ObjectSpace
   #   - _id2ref(p1)
   # -->
   #
+  %a{deprecated}
   def self._id2ref: (Integer id) -> untyped
 
   # <!--

core/ractor.rbs

@@ -363,7 +363,7 @@ class Ractor
   # -->
   # TBD
   #
-  def self.select: (?) -> untyped
+  def self.select: (?) -> Array[untyped]
 
   # <!--
   #   rdoc-file=ractor.rb
@@ -380,6 +380,36 @@ class Ractor
   #
   def self.shareable?: (untyped obj) -> bool
 
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - Ractor.sharable_proc(self: nil){} -> sharable proc
+  # -->
+  # It returns shareable Proc object. The Proc object is shareable and the self in
+  # a block will be replaced with the value passed via `self:` keyword.
+  #
+  # In a shareable Proc, you can not access to the outer variables.
+  #
+  #     a = 42
+  #     Ractor.shareable_proc{ p a }
+  #     #=> can not isolate a Proc because it accesses outer variables (a). (ArgumentError)
+  #
+  # The `self` should be a sharable object
+  #
+  #     Ractor.shareable_proc(self: self){}
+  #     #=> self should be shareable: main (Ractor::IsolationError)
+  #
+  def self.shareable_proc: [T] () { (?) [self: nil] -> T } -> ^(?) [self: nil] -> T
+                         | [T, S] (self: S) { (?) [self: S] -> T } -> ^(?) [self: S] -> T
+
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - Ractor.sharable_proc{} -> sharable proc
+  # -->
+  # Same as Ractor.sharable_proc, but returns lambda proc.
+  #
+  def self.shareable_lambda: [T] () { (?) [self: nil] -> T } -> ^(?) [self: nil] -> T
+                           | [T, S] (self: S) { (?) [self: S] -> T } -> ^(?) [self: S] -> T
+
   # <!--
   #   rdoc-file=ractor.rb
   #   - Ractor.store_if_absent(key){ init_block }
@@ -424,13 +454,35 @@ class Ractor
   %a{deprecated: Use Ractor.[]= instead}
   def []=: [T] (interned sym, T val) -> T
 
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - ractor.default_port -> port object
+  # -->
+  # return default port of the Ractor.
+  #
+  def default_port: () -> Port[untyped]
+
   # <!--
   #   rdoc-file=ractor.rb
   #   - inspect()
   # -->
   #
   def inspect: () -> String
 
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - ractor.join -> self
+  # -->
+  # Wait for the termination of the Ractor. If the Ractor was aborted (terminated
+  # with an exception), Ractor#value is called to raise an exception.
+  #
+  #     Ractor.new{}.join #=> ractor
+  #
+  #     Ractor.new{ raise "foo" }.join
+  #     #=> raise an exception "foo (RuntimeError)"
+  #
+  def join: () -> self
+
   # <!--
   #   rdoc-file=ractor.rb
   #   - name()
@@ -439,6 +491,25 @@ class Ractor
   #
   def name: () -> String?
 
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - ractor.monitor(port) -> self
+  # -->
+  # Register port as a monitoring port. If the ractor terminated, the port
+  # received a Symbol object. :exited will be sent if the ractor terminated
+  # without an exception. :aborted will be sent if the ractor terminated with a
+  # exception.
+  #
+  #     r = Ractor.new{ some_task() }
+  #     r.monitor(port = Ractor::Port.new)
+  #     port.receive #=> :exited and r is terminated
+  #
+  #     r = Ractor.new{ raise "foo" }
+  #     r.monitor(port = Ractor::Port.new)
+  #     port.receive #=> :terminated and r is terminated with an exception "foo"
+  #
+  def monitor: [T < Symbol] (Port[T]) -> untyped
+
   # <!--
   #   rdoc-file=ractor.rb
   #   - ractor.send(msg) -> self
@@ -454,6 +525,29 @@ class Ractor
   #
   alias to_s inspect
 
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - ractor.unmonitor(port) -> self
+  # -->
+  # Unregister port from the monitoring ports.
+  #
+  def unmonitor: (Port[untyped]) -> self
+
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - ractor.value -> obj
+  # -->
+  # Waits for `ractor` to complete, using #join, and return its value or raise the
+  # exception which terminated the Ractor. The value will not be copied even if it
+  # is unshareable object. Therefore at most 1 Ractor can get a value.
+  #
+  #     r = Ractor.new{ [1, 2] }
+  #     r.value #=> [1, 2] (unshareable object)
+  #
+  #     Ractor.new(r){|r| r.value} #=> Ractor::Error
+  #
+  def value: () -> untyped
+
   private
 
   # <!--
@@ -621,6 +715,166 @@ class Ractor
     def method_missing: (*untyped) -> untyped
   end
 
+  # <!-- rdoc-file=ractor.rb -->
+  # Port objects transmit messages between Ractors.
+  #
+  class Port[T = untyped]
+    # <!--
+    #   rdoc-file=ractor.rb
+    #   - <<(obj, move: false)
+    # -->
+    #
+    alias << send
+
+    # <!--
+    #   rdoc-file=ractor.rb
+    #   - port.close
+    # -->
+    # Close the port. On the closed port, sending is not prohibited. Receiving is
+    # also not allowed if there is no sent messages arrived before closing.
+    #
+    #     port = Ractor::Port.new
+    #     Ractor.new port do |port|
+    #       port.send 1 # OK
+    #       port.send 2 # OK
+    #       port.close
+    #       port.send 3 # raise Ractor::ClosedError
+    #     end
+    #
+    #     port.receive #=> 1
+    #     port.receive #=> 2
+    #     port.receive #=> raise Ractor::ClosedError
+    #
+    # Now, only a Ractor which creates the port is allowed to close ports.
+    #
+    #     port = Ractor::Port.new
+    #     Ractor.new port do |port|
+    #       port.close #=> closing port by other ractors is not allowed (Ractor::Error)
+    #     end.join
+    #
+    def close: () -> void
+
+    # <!--
+    #   rdoc-file=ractor.rb
+    #   - port.closed? -> true/false
+    # -->
+    # Return the port is closed or not.
+    #
+    def closed?: () -> bool
+
+    # <!--
+    #   rdoc-file=ractor.rb
+    #   - port.inspect -> string
+    # -->
+    #
+    def inspect: () -> String
+
+    # <!--
+    #   rdoc-file=ractor.rb
+    #   - port.receive -> msg
+    # -->
+    # Receive a message to the port (which was sent there by Port#send).
+    #
+    #     port = Ractor::Port.new
+    #     r = Ractor.new port do |port|
+    #       port.send('message1')
+    #     end
+    #
+    #     v1 = port.receive
+    #     puts "Received: #{v1}"
+    #     r.join
+    #     # Here will be printed: "Received: message1"
+    #
+    # The method blocks if the message queue is empty.
+    #
+    #     port = Ractor::Port.new
+    #     r = Ractor.new port do |port|
+    #       wait
+    #       puts "Still not received"
+    #       port.send('message1')
+    #       wait
+    #       puts "Still received only one"
+    #       port.send('message2')
+    #     end
+    #     puts "Before first receive"
+    #     v1 = port.receive
+    #     puts "Received: #{v1}"
+    #     v2 = port.receive
+    #     puts "Received: #{v2}"
+    #     r.join
+    #
+    # Output:
+    #
+    #     Before first receive
+    #     Still not received
+    #     Received: message1
+    #     Still received only one
+    #     Received: message2
+    #
+    # If close_incoming was called on the ractor, the method raises
+    # Ractor::ClosedError if there are no more messages in the message queue:
+    #
+    #     port = Ractor::Port.new
+    #     port.close
+    #     port.receive #=> raise Ractor::ClosedError
+    #
+    def receive: () -> T
+
+    # <!--
+    #   rdoc-file=ractor.rb
+    #   - port.send(msg, move: false) -> self
+    # -->
+    # Send a message to a port to be accepted by port.receive.
+    #
+    #     port = Ractor::Port.new
+    #     r = Ractor.new do
+    #       r.send 'message'
+    #     end
+    #     value = port.receive
+    #     puts "Received #{value}"
+    #     # Prints: "Received: message"
+    #
+    # The method is non-blocking (will return immediately even if the ractor is not
+    # ready to receive anything):
+    #
+    #     port = Ractor::Port.new
+    #     r = Ractor.new(port) do |port|
+    #       port.send 'test'}
+    #       puts "Sent successfully"
+    #       # Prints: "Sent successfully" immediately
+    #     end
+    #
+    # An attempt to send to a port which already closed its execution will raise
+    # Ractor::ClosedError.
+    #
+    #     r = Ractor.new {Ractor::Port.new}
+    #     r.join
+    #     p r
+    #     # "#<Ractor:#6 (irb):23 terminated>"
+    #     port = r.value
+    #     port.send('test') # raise Ractor::ClosedError
+    #
+    # If the `obj` is unshareable, by default it will be copied into the receiving
+    # ractor by deep cloning.
+    #
+    # If the object is shareable, it only send a reference to the object without
+    # cloning.
+    #
+    def send: (T obj, ?move: boolish) -> self
+
+    private
+
+    # <!--
+    #   rdoc-file=ractor_sync.c
+    #   - Ractor::Port.new  -> new_port
+    # -->
+    # Returns a new Ractor::Port object.
+    #
+    def initialize: () -> void
+
+    def initialize_copy: (untyped) -> untyped
+  end
+
   # <!-- rdoc-file=ractor.c -->
   # Raised on attempt to Ractor#take if there was an uncaught exception in the
   # Ractor. Its `cause` will contain the original exception, and `ractor` is the

core/thread.rbs

@@ -974,8 +974,8 @@ class Thread < Object
   #      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
+  def raise: (?String message, ?cause: Exception?) -> nil
+           | (_Exception, ?_ToS message, ?Array[Thread::Backtrace::Location] | Array[String] | nil backtrace, ?cause: Exception?) -> nil
 
   # <!--
   #   rdoc-file=thread.c

stdlib/socket/0/socket.rbs

@@ -511,7 +511,9 @@ class Socket < BasicSocket
   #     }
   #
   def self.tcp: (String host, Integer port, ?String local_host, ?Integer local_port, ?resolv_timeout: Time::_Timeout, ?connect_timeout: Time::_Timeout) -> instance
-              | (String host, Integer port, ?String local_host, ?Integer local_port, ?resolv_timeout: Time::_Timeout, ?connect_timeout: Time::_Timeout) { (instance) -> void } -> void
+              | (String host, Integer port, ?String local_host, ?Integer local_port, ?open_timeout: Time::_Timeout) -> instance
+              | [T] (String host, Integer port, ?String local_host, ?Integer local_port, ?resolv_timeout: Time::_Timeout, ?connect_timeout: Time::_Timeout) { (instance) -> T } -> T
+              | [T] (String host, Integer port, ?String local_host, ?Integer local_port, ?open_timeout: Time::_Timeout) { (instance) -> T } -> T
 
   # <!--
   #   rdoc-file=ext/socket/lib/socket.rb