Merge pull request #1674 from ruby/ruby-33

Update methods for Ruby 3.3

Author: soutaro

.github/workflows/ruby.yml

@@ -31,9 +31,8 @@ jobs:
             job: stdlib_test
           - container_tag: 3.1-dev-focal
             job: stdlib_test
-        include:
-          - container_tag: master-nightly-focal
-            allow_failures: "true"
+          - container_tag: 3.2-dev-focal
+            job: stdlib_test
     container:
       image: rubylang/ruby:${{ matrix.container_tag }}
     steps:

core/dir.rbs

@@ -364,6 +364,61 @@ class Dir
   #
   def self.exist?: (path | io file_name) -> bool
 
+  # <!--
+  #   rdoc-file=dir.c
+  #   - Dir.fchdir(fd) -> 0
+  #   - Dir.fchdir(fd) { ... } -> object
+  # -->
+  # Changes the current working directory to the directory specified by the
+  # integer file descriptor `fd`.
+  #
+  # When passing a file descriptor over a UNIX socket or to a child process, using
+  # `fchdir` instead of `chdir` avoids the [time-of-check to time-of-use
+  # vulnerability](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use)
+  #
+  # With no block, changes to the directory given by `fd`:
+  #
+  #     Dir.chdir('/var/spool/mail')
+  #     Dir.pwd # => "/var/spool/mail"
+  #     dir  = Dir.new('/usr')
+  #     fd = dir.fileno
+  #     Dir.fchdir(fd) do
+  #       Dir.pwd # => "/usr"
+  #     end
+  #     Dir.pwd # => "/var/spool/mail"
+  #
+  # With a block, temporarily changes the working directory:
+  #
+  # *   Calls the block with the argument.
+  # *   Changes to the given directory.
+  # *   Executes the block
+  # *   Restores the previous working directory.
+  # *   Returns the block's return value.
+  #
+  #
+  # Example:
+  #
+  #     Dir.chdir('/var/spool/mail')
+  #     Dir.pwd # => "/var/spool/mail"
+  #     Dir.chdir('/tmp') do
+  #       Dir.pwd # => "/tmp"
+  #     end
+  #     Dir.pwd # => "/var/spool/mail"
+  #
+  # This method uses the
+  # [fchdir()](https://www.man7.org/linux/man-pages/man3/fchdir.3p.html) function
+  # defined by POSIX 2008; the method is not implemented on non-POSIX platforms
+  # (raises NotImplementedError).
+  #
+  # Raises an exception if the file descriptor is not valid.
+  #
+  # In a multi-threaded program an error is raised if a thread attempts to open a
+  # `chdir` block while another thread has one open, or a call to `chdir` without
+  # a block occurs inside a block passed to `chdir` (even in the same thread).
+  #
+  def self.fchdir: (int) -> Integer
+                 | [T] (int) { () -> T } -> T
+
   # <!--
   #   rdoc-file=dir.c
   #   - Dir.foreach(dirpath, encoding: 'UTF-8') {|entry_name| ... }  -> nil
@@ -397,6 +452,28 @@ class Dir
   #
   alias self.foreach self.each_child
 
+  # <!--
+  #   rdoc-file=dir.c
+  #   - Dir.for_fd(fd) -> dir
+  # -->
+  # Returns a new Dir object representing the directory specified by the given
+  # integer directory file descriptor `fd`:
+  #
+  #     d0 = Dir.new('..')
+  #     d1 = Dir.for_fd(d0.fileno)
+  #
+  # Note that the returned `d1` does not have an associated path:
+  #
+  #     d0.path # => '..'
+  #     d1.path # => nil
+  #
+  # This method uses the
+  # [fdopendir()](https://www.man7.org/linux/man-pages/man3/fdopendir.3p.html)
+  # function defined by POSIX 2008; the method is not implemented on non-POSIX
+  # platforms (raises NotImplementedError).
+  #
+  def self.for_fd: (int) -> Dir
+
   # <!--
   #   rdoc-file=dir.c
   #   - Dir.pwd -> string
@@ -678,6 +755,20 @@ class Dir
 
   public
 
+  # <!--
+  #   rdoc-file=dir.c
+  #   - chdir -> nil
+  # -->
+  # Changes the current working directory to the path of `self`:
+  #
+  #     Dir.pwd # => "/"
+  #     dir = Dir.new('example')
+  #     dir.chdir
+  #     dir.pwd # => "/example"
+  #
+  def chdir: () -> Integer
+           | [T] { () -> T } -> T
+
   # <!--
   #   rdoc-file=dir.c
   #   - children -> array

core/fiber.rbs

@@ -369,6 +369,20 @@ class Fiber < Object
   #
   alias inspect to_s
 
+  # <!--
+  #   rdoc-file=cont.c
+  #   - fiber.kill -> nil
+  # -->
+  # Terminates `fiber` by raising an uncatchable exception, returning the
+  # terminated Fiber.
+  #
+  # If the fiber has not been started, transition directly to the terminated
+  # state.
+  #
+  # If the fiber is already terminated, does nothing.
+  #
+  def kill: () -> nil
+
   # <!--
   #   rdoc-file=cont.c
   #   - fiber.raise                                 -> obj

core/io/buffer.rbs

@@ -165,6 +165,21 @@ class IO
     #
     def self.map: (File file, ?Integer? size, ?Integer offset, ?Integer flags) -> Buffer
 
+    # <!--
+    #   rdoc-file=io_buffer.c
+    #   - IO::Buffer.string(length) {|io_buffer| ... read/write io_buffer ...} -> string
+    # -->
+    # Creates a new string of the given length and yields a IO::Buffer instance to
+    # the block which uses the string as a source. The block is expected to write to
+    # the buffer and the string will be returned.
+    #
+    #     IO::Buffer.string(4) do |buffer|
+    #       buffer.set_string("Ruby")
+    #     end
+    #     # => "Ruby"
+    #
+    def self.string: (int) { (Buffer) -> void } -> String
+
     public
 
     # <!--

core/match_data.rbs

@@ -305,6 +305,8 @@ class MatchData
   #     m.named_captures(symbolize_names: true) #=> {:a => "1"}
   #
   def named_captures: () -> Hash[String, String?]
+                    | (symbolize_names: true) -> Hash[Symbol, String?]
+                    | (symbolize_names: boolish) -> Hash[String | Symbol, String?]
 
   # <!--
   #   rdoc-file=re.c

core/module.rbs

@@ -1463,7 +1463,7 @@ class Module < Object
   #
   # Returns a module, where refined methods are defined.
   #
-  def refine: (Module mod) { () -> void } -> Refinement
+  def refine: (Module mod) { () [self: Refinement] -> void } -> Refinement
 
   # <!--
   #   rdoc-file=eval.c
@@ -1527,6 +1527,50 @@ class Module < Object
   #
   def remove_method: (*interned arg0) -> self
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - mod.set_temporary_name(string) -> self
+  #   - mod.set_temporary_name(nil) -> self
+  # -->
+  # Sets the temporary name of the module `mod`. This name is used as a prefix for
+  # the names of constants declared in `mod`. If the module is assigned a
+  # permanent name, the temporary name is discarded.
+  #
+  # After a permanent name is assigned, a temporary name can no longer be set, and
+  # this method raises a RuntimeError.
+  #
+  # If the name given is not a string or is a zero length string, this method
+  # raises an ArgumentError.
+  #
+  # The temporary name must not be a valid constant name, to avoid confusion with
+  # actual constants. If you attempt to set a temporary name that is a a valid
+  # constant name, this method raises an ArgumentError.
+  #
+  # If the given name is `nil`, the module becomes anonymous.
+  #
+  # Example:
+  #
+  #     m = Module.new # => #<Module:0x0000000102c68f38>
+  #     m.name #=> nil
+  #
+  #     m.set_temporary_name("fake_name") # => fake_name
+  #     m.name #=> "fake_name"
+  #
+  #     m.set_temporary_name(nil) # => #<Module:0x0000000102c68f38>
+  #     m.name #=> nil
+  #
+  #     n = Module.new
+  #     n.set_temporary_name("fake_name")
+  #
+  #     n::M = m
+  #     n::M.name #=> "fake_name::M"
+  #     N = n
+  #
+  #     N.name #=> "nested_fake_name"
+  #     N::M.name #=> "N::M"
+  #
+  def set_temporary_name: (string?) -> self
+
   # <!--
   #   rdoc-file=object.c
   #   - mod.singleton_class?    -> true or false

core/object_space/weak_key_map.rbs

@@ -0,0 +1,102 @@
+%a{annotate:rdoc:skip}
+module ObjectSpace
+  # <!-- rdoc-file=weakmap.c -->
+  # An ObjectSpace::WeakKeyMap object holds references to any objects, but objects
+  # uses as keys can be garbage collected.
+  #
+  # Objects used as values can't be garbage collected until the key is.
+  #
+  class WeakKeyMap[Key, Value]
+    public
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map[key] -> value
+    # -->
+    # Returns the value associated with the given `key` if found.
+    #
+    # If `key` is not found, returns `nil`.
+    #
+    def []: (Key) -> Value?
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map[key] = value -> value
+    # -->
+    # Associates the given `value` with the given `key`; returns `value`.
+    #
+    # The reference to `key` is weak, so when there is no other reference to `key`
+    # it may be garbage collected.
+    #
+    # If the given `key` exists, replaces its value with the given `value`; the
+    # ordering is not affected
+    #
+    def []=: (Key, Value?) -> Value?
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map.clear -> self
+    # -->
+    # Removes all map entries; returns `self`.
+    #
+    def clear: () -> self
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map.delete(key) -> value or nil
+    #   - map.delete(key) {|key| ... } -> object
+    # -->
+    # Deletes the entry for the given `key` and returns its associated value.
+    #
+    # If no block is given and `key` is found, deletes the entry and returns the
+    # associated value:
+    #     m = ObjectSpace::WeakKeyMap.new
+    #     m["foo"] = 1
+    #     m.delete("foo") # => 1
+    #     m["foo"] # => nil
+    #
+    # If no block given and `key` is not found, returns `nil`.
+    #
+    # If a block is given and `key` is found, ignores the block, deletes the entry,
+    # and returns the associated value:
+    #     m = ObjectSpace::WeakKeyMap.new
+    #     m["foo"] = 2
+    #     h.delete("foo") { |key| raise 'Will never happen'} # => 2
+    #
+    # If a block is given and `key` is not found, calls the block and returns the
+    # block's return value:
+    #     m = ObjectSpace::WeakKeyMap.new
+    #     h.delete("nosuch") { |key| "Key #{key} not found" } # => "Key nosuch not found"
+    #
+    def delete: (Key) -> Value?
+              | [T] (Key) { (Key) -> T } -> (Value | T)
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map.getkey(key) -> existing_key or nil
+    # -->
+    # Returns the existing equal key if it exists, otherwise returns `nil`.
+    #
+    def getkey: (untyped) -> Key?
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map.inspect -> new_string
+    # -->
+    # Returns a new String containing informations about the map:
+    #
+    #     m = ObjectSpace::WeakKeyMap.new
+    #     m[key] = value
+    #     m.inspect # => "#<ObjectSpace::WeakKeyMap:0x00000001028dcba8 size=1>"
+    #
+    def inspect: () -> String
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - hash.key?(key) -> true or false
+    # -->
+    # Returns `true` if `key` is a key in `self`, otherwise `false`.
+    #
+    def key?: (Key) -> bool
+  end
+end

core/process.rbs

@@ -1421,6 +1421,33 @@ module Process
   # Process.waitpid2 is an alias for Process.waitpid.
   #
   def self.waitpid2: (?Integer pid, ?Integer flags) -> [ Integer, Process::Status ]
+
+  # <!--
+  #   rdoc-file=process.c
+  #   - Process.warmup    -> true
+  # -->
+  # Notify the Ruby virtual machine that the boot sequence is finished, and that
+  # now is a good time to optimize the application. This is useful for long
+  # running applications.
+  #
+  # This method is expected to be called at the end of the application boot. If
+  # the application is deployed using a pre-forking model, `Process.warmup` should
+  # be called in the original process before the first fork.
+  #
+  # The actual optimizations performed are entirely implementation specific and
+  # may change in the future without notice.
+  #
+  # On CRuby, `Process.warmup`:
+  #
+  # *   Performs a major GC.
+  # *   Compacts the heap.
+  # *   Promotes all surviving objects to the old generation.
+  # *   Precomputes the coderange of all strings.
+  # *   Frees all empty heap pages and increments the allocatable pages counter by
+  #     the number of pages freed.
+  # *   Invoke `malloc_trim` if available to free empty malloc pages.
+  #
+  def self.warmup: () -> bool
 end
 
 # <!-- rdoc-file=process.c -->

core/ractor.rbs

@@ -1014,4 +1014,8 @@ class Ractor
 
   class UnsafeError < Ractor::Error
   end
+
+  %a{annotate:rdoc:skip}
+  class Selector
+  end
 end