rbs 3.6.1 → 3.9.5

data/core/process.rbs

@@ -13,7 +13,6 @@
 #     without waiting for completion.
 # *   Process.exec: Replaces the current process by executing the command.
 #
-#
 # In addition:
 #
 # *   Method Kernel#system executes a given command-line (string) in a subshell;
@@ -23,7 +22,6 @@
 # *   Module Open3 supports creating child processes with access to their
 #     $stdin, $stdout, and $stderr streams.
 #
-#
 # ### Execution Environment
 #
 # Optional leading argument `env` is a hash of name/value pairs, where each name
@@ -52,15 +50,14 @@
 #     built-in, or if it contains one or more meta characters.
 # *   `exe_path` otherwise.
 #
-#
-# **Argument `command_line`**
+# #### Argument `command_line`
 #
 # String argument `command_line` is a command line to be passed to a shell; it
 # must begin with a shell reserved word, begin with a special built-in, or
 # contain meta characters:
 #
 #     system('if true; then echo "Foo"; fi')          # => true  # Shell reserved word.
-#     system('echo')                                  # => true  # Built-in.
+#     system('exit')                                  # => true  # Built-in.
 #     system('date > /tmp/date.tmp')                  # => true  # Contains meta character.
 #     system('date > /nop/date.tmp')                  # => false
 #     system('date > /nop/date.tmp', exception: true) # Raises RuntimeError.
@@ -76,23 +73,85 @@
 # See [Execution Shell](rdoc-ref:Process@Execution+Shell) for details about the
 # shell.
 #
-# **Argument `exe_path`**
+# #### Argument `exe_path`
 #
 # Argument `exe_path` is one of the following:
 #
-# *   The string path to an executable to be called.
-# *   A 2-element array containing the path to an executable to be called, and
-#     the string to be used as the name of the executing process.
+# *   The string path to an executable file to be called:
+#
+#     Example:
+#
+#         system('/usr/bin/date') # => true # Path to date on Unix-style system.
+#         system('foo')           # => nil  # Command execlution failed.
+#
+#     Output:
+#
+#         Thu Aug 31 10:06:48 AM CDT 2023
+#
+#     A path or command name containing spaces without arguments cannot be
+#     distinguished from `command_line` above, so you must quote or escape the
+#     entire command name using a shell in platform dependent manner, or use the
+#     array form below.
+#
+#     If `exe_path` does not contain any path separator, an executable file is
+#     searched from directories specified with the `PATH` environment variable.
+#     What the word "executable" means here is depending on platforms.
+#
+#     Even if the file considered "executable", its content may not be in proper
+#     executable format.  In that case, Ruby tries to run it by using `/bin/sh`
+#     on a Unix-like system, like system(3) does.
+#
+#         File.write('shell_command', 'echo $SHELL', perm: 0o755)
+#         system('./shell_command')        # prints "/bin/sh" or something.
+#
+# *   A 2-element array containing the path to an executable and the string to
+#     be used as the name of the executing process:
+#
+#     Example:
+#
+#         pid = spawn(['sleep', 'Hello!'], '1') # 2-element array.
+#         p `ps -p #{pid} -o command=`
+#
+#     Output:
+#
+#         "Hello! 1\n"
+#
+# ### Arguments `args`
+#
+# If `command_line` does not contain shell meta characters except for spaces and
+# tabs, or `exe_path` is given, Ruby invokes the executable directly.  This form
+# does not use the shell:
 #
+#     spawn("doesnt_exist")       # Raises Errno::ENOENT
+#     spawn("doesnt_exist", "\n") # Raises Errno::ENOENT
+#
+#     spawn("doesnt_exist\n")     # => false
+#     # sh: 1: doesnot_exist: not found
+#
+# The error message is from a shell and would vary depending on your system.
+#
+# If one or more `args` is given after `exe_path`, each is an argument or option
+# to be passed to the executable:
 #
 # Example:
 #
-#     system('/usr/bin/date') # => true # Path to date on Unix-style system.
-#     system('foo')           # => nil  # Command failed.
+#     system('echo', '<', 'C*', '|', '$SHELL', '>')   # => true
 #
 # Output:
 #
-#     Mon Aug 28 11:43:10 AM CDT 2023
+#     < C* | $SHELL >
+#
+# However, there are exceptions on Windows.  See [Execution Shell on
+# Windows](rdoc-ref:Process@Execution+Shell+on+Windows).
+#
+# If you want to invoke a path containing spaces with no arguments without
+# shell, you will need to use a 2-element array `exe_path`.
+#
+# Example:
+#
+#     path = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+#     spawn(path) # Raises Errno::ENOENT; No such file or directory - /Applications/Google
+#     spawn([path] * 2)
 #
 # ### Execution Options
 #
@@ -133,14 +192,12 @@
 #
 # *   *n*: Specifies file descriptor *n*.
 #
-#
 # There are these shorthand symbols for fds:
 #
 # *   `:in`: Specifies file descriptor 0 (STDIN).
 # *   `:out`: Specifies file descriptor 1 (STDOUT).
 # *   `:err`: Specifies file descriptor 2 (STDERR).
 #
-#
 # The value given with a source is one of:
 #
 # *   *n*: Redirects to fd *n* in the parent process.
@@ -156,7 +213,6 @@
 # *   `[:child, fd]`: Redirects to the redirected `fd`.
 # *   `:close`: Closes the file descriptor in child process.
 #
-#
 # See [Access Modes](rdoc-ref:File@Access+Modes) and [File
 # Permissions](rdoc-ref:File@File+Permissions).
 #
@@ -194,7 +250,6 @@
 # *   `true`: Create a new process group for the new process.
 # *   *pgid*: Create the new process in the process group whose id is *pgid*.
 #
-#
 # On Windows only, use execution option `:new_pgroup` with value `true` to
 # create a new process group for the new process.
 #
@@ -212,7 +267,6 @@
 # *   An integer, specifying both the current and maximum limits.
 # *   A 2-element array of integers, specifying the current and maximum limits.
 #
-#
 # #### File Descriptor Inheritance
 #
 # By default, the new process inherits file descriptors from the parent process.
@@ -222,23 +276,48 @@
 #
 # ### Execution Shell
 #
-# On a Unix-like system, the shell invoked is `/bin/sh`; otherwise the shell
-# invoked is determined by environment variable `ENV['RUBYSHELL']`, if defined,
-# or `ENV['COMSPEC']` otherwise.
-#
-# Except for the `COMSPEC` case, the entire string `command_line` is passed as
-# an argument to [shell option
+# On a Unix-like system, the shell invoked is `/bin/sh`; the entire string
+# `command_line` is passed as an argument to [shell option
 # -c](https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/utilities/sh.
 # html).
 #
 # The shell performs normal shell expansion on the command line:
 #
-#     spawn('echo C*') # => 799139
-#     Process.wait     # => 799139
+# Example:
+#
+#     system('echo $SHELL: C*') # => true
+#
+# Output:
+#
+#     /bin/bash: CONTRIBUTING.md COPYING COPYING.ja
+#
+# #### Execution Shell on Windows
+#
+# On Windows, the shell invoked is determined by environment variable
+# `RUBYSHELL`, if defined, or `COMSPEC` otherwise; the entire string
+# `command_line` is passed as an argument to `-c` option for `RUBYSHELL`, as
+# well as `/bin/sh`, and [/c
+# option](https://learn.microsoft.com/en-us/windows-server/administration/window
+# s-commands/cmd) for `COMSPEC`.  The shell is invoked automatically in the
+# following cases:
+#
+# *   The command is a built-in of `cmd.exe`, such as `echo`.
+# *   The executable file is a batch file; its name ends with `.bat` or `.cmd`.
+#
+# Note that the command will still be invoked as `command_line` form even when
+# called in `exe_path` form, because `cmd.exe` does not accept a script name
+# like `/bin/sh` does but only works with `/c` option.
+#
+# The standard shell `cmd.exe` performs environment variable expansion but does
+# not have globbing functionality:
+#
+# Example:
+#
+#     system("echo %COMSPEC%: C*")' # => true
 #
 # Output:
 #
-#     CONTRIBUTING.md COPYING COPYING.ja
+#     C:\WINDOWS\system32\cmd.exe: C*
 #
 # ## What's Here
 #
@@ -254,7 +333,6 @@
 # *   ::ppid: Returns the process ID of the parent process.
 # *   ::uid: Returns the (real) user ID.
 #
-#
 # ### Current-Process Setters
 #
 # *   ::egid=: Sets the effective group ID.
@@ -267,7 +345,6 @@
 #     leader, with no controlling tty.
 # *   ::uid=: Sets the user ID.
 #
-#
 # ### Current-Process Execution
 #
 # *   ::abort: Immediately terminates the process.
@@ -281,7 +358,6 @@
 #     application is completed, and that the VM may begin optimizing the
 #     application.
 #
-#
 # ### Child Processes
 #
 # *   ::detach: Guards against a child process becoming a zombie.
@@ -295,7 +371,6 @@
 # *   ::waitall: Waits for all child processes to exit; returns their process
 #     IDs and statuses.
 #
-#
 # ### Process Groups
 #
 # *   ::getpgid: Returns the process group ID for a process.
@@ -317,7 +392,6 @@
 # *   ::setpriority: Sets the scheduling priority for a process, process group,
 #     or user.
 #
-#
 # ### Timing
 #
 # *   ::clock_getres: Returns the resolution of a system clock.
@@ -448,7 +522,6 @@ module Process
   # *   `:CLOCK_UPTIME_RAW_APPROX`: macOS 10.12.
   # *   `:CLOCK_VIRTUAL`: FreeBSD 3.0, OpenBSD 2.1.
   #
-  #
   # Note that SUS stands for Single Unix Specification. SUS contains POSIX and
   # clock_gettime is defined in the POSIX part. SUS defines `:CLOCK_REALTIME` as
   # mandatory but `:CLOCK_MONOTONIC`, `:CLOCK_PROCESS_CPUTIME_ID`, and
@@ -464,7 +537,6 @@ module Process
   #     *   `:TIME_BASED_CLOCK_REALTIME`: Use time() defined by ISO C. The
   #         resolution is 1 second.
   #
-  #
   # *   Emulations for `:CLOCK_MONOTONIC`:
   #
   #     *   `:MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONIC`: Use mach_absolute_time(),
@@ -485,7 +557,6 @@ module Process
   #         type, the resolution is 10 millisecond and cannot represent over 497
   #         days.
   #
-  #
   # *   Emulations for `:CLOCK_PROCESS_CPUTIME_ID`:
   #
   #     *   `:GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_ID`: Use getrusage() defined
@@ -508,8 +579,6 @@ module Process
   #         `CLOCKS_PER_SEC` is 1000000 and clock_t is a 32-bit integer type, it
   #         cannot represent over 72 minutes.
   #
-  #
-  #
   # **Argument `unit`**
   #
   # Optional argument `unit` (default `:float_second`) specifies the unit for the
@@ -523,7 +592,6 @@ module Process
   # *   `:nanosecond`: Number of nanoseconds as an integer.
   # *   `::second`: Number of seconds as an integer.
   #
-  #
   # Examples:
   #
   #     Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :float_microsecond)
@@ -569,7 +637,6 @@ module Process
   # *   Changes the current working directory to the root directory.
   # *   Redirects $stdin, $stdout, and $stderr to the null device.
   #
-  #
   # If optional argument `nochdir` is `true`, does not change the current working
   # directory.
   #
@@ -615,7 +682,7 @@ module Process
   #
   #     thread.join.pid                       # => 313262
   #
-  def self.detach: (Integer pid) -> Thread
+  def self.detach: (Integer pid) -> Process::Waiter
 
   # <!--
   #   rdoc-file=process.c
@@ -698,7 +765,6 @@ module Process
   # *   Process::PRIO_PGRP: return priority for process group.
   # *   Process::PRIO_USER: return priority for user.
   #
-  #
   # Argument `id` is the ID for the process, process group, or user; zero
   # specified the current ID for `kind`.
   #
@@ -787,7 +853,6 @@ module Process
   # *   Whether the array includes duplicate group IDs.
   # *   Whether the array size exceeds the value of Process.maxgroups.
   #
-  #
   # Use this call to get a sorted and unique array:
   #
   #     Process.groups.uniq.sort
@@ -816,7 +881,6 @@ module Process
   #     belongs.
   # *   The group ID `gid`.
   #
-  #
   # Example:
   #
   #     Process.groups                # => [0, 1, 2, 3, 4, 6, 10, 11, 20, 26, 27]
@@ -840,7 +904,6 @@ module Process
   # *   Zero, send the signal to all processes in the current process group.
   # *   Negative, sends the signal to a system-dependent collection of processes.
   #
-  #
   # Argument `signal` specifies the signal to be sent; the argument may be:
   #
   # *   An integer signal number: e.g., `-29`, `0`, `29`.
@@ -852,7 +915,6 @@ module Process
   #     *   `'-SIGPOLL'`.
   #     *   `'-POLL'`.
   #
-  #
   # *   A signal symbol, with or without leading `'SIG'`, and with or without a
   #     further prefixed minus sign (`'-'`): e.g.:
   #
@@ -861,8 +923,6 @@ module Process
   #     *   `:'-SIGPOLL'`.
   #     *   `:'-POLL'`.
   #
-  #
-  #
   # If `signal` is:
   #
   # *   A non-negative integer, or a signal name or symbol without prefixed `'-'`,
@@ -870,7 +930,6 @@ module Process
   # *   A negative integer, or a signal name or symbol with prefixed `'-'`, each
   #     process group with group ID `id` is signalled.
   #
-  #
   # Use method Signal.list to see which signals are supported by Ruby on the
   # underlying platform; the method returns a hash of the string names and
   # non-negative integer values of the supported signals. The size and content of
@@ -899,7 +958,6 @@ module Process
   # *   Raises Errno::ESRCH or RangeError if one of `ids` is invalid.
   # *   Raises Errno::EPERM if needed permissions are not in force.
   #
-  #
   # In the last two cases, signals may have been sent to some processes.
   #
   def self.kill: (Integer | interned signal, *Integer pids) -> Integer
@@ -1031,7 +1089,6 @@ module Process
   # *   `:SIGPENDING`: Number of queued signals allowed (signals) (GNU/Linux).
   # *   `:STACK`: Stack size (bytes) (SUSv3).
   #
-  #
   # Arguments `cur_limit` and `max_limit` may be:
   #
   # *   Integers (`max_limit` should not be smaller than `cur_limit`).
@@ -1042,7 +1099,6 @@ module Process
   # *   Symbol `:INFINITY`, string `'INFINITY'`, or constant
   #     `Process::RLIM_INFINITY`: no limit on resource.
   #
-  #
   # This example raises the soft limit of core size to the hard limit to try to
   # make core dump possible:
   #
@@ -1221,15 +1277,13 @@ module Process
   #         Process.wait(-child1_pid) returned pid 230109, which is child 1 pid.
   #         Raised Errno::ECHILD, because there's no longer a child with process group id 230109.
   #
-  #
   # Argument `flags` should be given as one of the following constants, or as the
   # logical OR of both:
   #
   # *   Process::WNOHANG: Does not block if no child process is available.
-  # *   Process:WUNTRACED: May return a stopped child process, even if not yet
+  # *   Process::WUNTRACED: May return a stopped child process, even if not yet
   #     reported.
   #
-  #
   # Not all flags are available on all platforms.
   #
   # Raises Errno::ECHILD if there is no suitable child process.
@@ -1251,7 +1305,7 @@ module Process
   #     Process.wait2(pid)
   #     # => [309581, #<Process::Status: pid 309581 exit 13>]
   #
-  # Process.waitpid2 is an alias for Process.waitpid.
+  # Process.waitpid2 is an alias for Process.wait2.
   #
   def self.wait2: (?Integer pid, ?Integer flags) -> [ Integer, Process::Status ]
 
@@ -1388,15 +1442,13 @@ module Process
   #         Process.wait(-child1_pid) returned pid 230109, which is child 1 pid.
   #         Raised Errno::ECHILD, because there's no longer a child with process group id 230109.
   #
-  #
   # Argument `flags` should be given as one of the following constants, or as the
   # logical OR of both:
   #
   # *   Process::WNOHANG: Does not block if no child process is available.
-  # *   Process:WUNTRACED: May return a stopped child process, even if not yet
+  # *   Process::WUNTRACED: May return a stopped child process, even if not yet
   #     reported.
   #
-  #
   # Not all flags are available on all platforms.
   #
   # Raises Errno::ECHILD if there is no suitable child process.
@@ -1418,7 +1470,7 @@ module Process
   #     Process.wait2(pid)
   #     # => [309581, #<Process::Status: pid 309581 exit 13>]
   #
-  # Process.waitpid2 is an alias for Process.waitpid.
+  # Process.waitpid2 is an alias for Process.wait2.
   #
   def self.waitpid2: (?Integer pid, ?Integer flags) -> [ Integer, Process::Status ]
 

data/core/ractor.rbs

@@ -50,7 +50,6 @@
 # *   Ractor.yield and Ractor#take for when the *receiver* knows the sender
 #     (pull);
 #
-#
 # In addition to that, any arguments passed to Ractor.new are passed to the
 # block and available there as if received by Ractor.receive, and the last block
 # value is sent outside of the ractor as if sent by Ractor.yield.
@@ -250,6 +249,30 @@
 # See [Ractor design doc](rdoc-ref:ractor.md) for more details.
 #
 class Ractor
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - _require(feature)
+  # -->
+  # internal method
+  #
+  def self._require: (String feature) -> bool
+
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - [](sym)
+  # -->
+  # get a value from ractor-local storage of current Ractor
+  #
+  def self.[]: (Symbol) -> untyped
+
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - []=(sym, val)
+  # -->
+  # set a value in ractor-local storage of current Ractor
+  #
+  def self.[]=: (Symbol, untyped) -> untyped
+
   # <!--
   #   rdoc-file=ractor.rb
   #   - count()
@@ -281,7 +304,15 @@ class Ractor
   # -->
   # returns main ractor
   #
-  def self.main: () -> untyped
+  def self.main: () -> Ractor
+
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - main?()
+  # -->
+  # return true if the current ractor is main ractor
+  #
+  def self.main?: () -> boolish
 
   # <!--
   #   rdoc-file=ractor.rb
@@ -557,6 +588,23 @@ class Ractor
   #
   def self.shareable?: (untyped obj) -> bool
 
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - Ractor.store_if_absent(key){ init_block }
+  # -->
+  # If the correponding value is not set, yield a value with init_block and store
+  # the value in thread-safe manner. This method returns corresponding stored
+  # value.
+  #
+  #     (1..10).map{
+  #       Thread.new(it){|i|
+  #         Ractor.store_if_absent(:s){ f(); i }
+  #         #=> return stored value of key :s
+  #       }
+  #     }.map(&:value).uniq.size #=> 1 and f() is called only once
+  #
+  def self.store_if_absent: [A] (Symbol) { (nil) -> A } -> A
+
   # <!--
   #   rdoc-file=ractor.rb
   #   - Ractor.yield(msg, move: false) -> nil
@@ -608,7 +656,8 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - [](sym)
   # -->
-  # get a value from ractor-local storage
+  # get a value from ractor-local storage of current Ractor Obsolete and use
+  # Ractor.[] instead.
   #
   def []: (interned sym) -> untyped
 
@@ -616,7 +665,8 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - []=(sym, val)
   # -->
-  # set a value in ractor-local storage
+  # set a value in ractor-local storage of current Ractor Obsolete and use
+  # Ractor.[]= instead.
   #
   def []=: [T] (interned sym, T val) -> T
 
@@ -1003,6 +1053,9 @@ class Ractor
   #     end
   #
   class RemoteError < Ractor::Error
+    # <!-- rdoc-file=ractor.rb -->
+    # The Ractor an uncaught exception is raised in.
+    #
     def ractor: () -> Ractor
   end