rbs 3.10.0.pre.2 → 3.10.0

data/stdlib/strscan/0/string_scanner.rbs

@@ -28,7 +28,7 @@
 # *   `match_values_cleared?(scanner)`:
 #      Returns whether the scanner's [match
 #     values](rdoc-ref:StringScanner@Match+Values) are cleared.
-# See examples at [helper methods](doc/strscan/helper_methods.md).
+# See examples at [helper methods](helper_methods.md).
 # ## The `StringScanner` Object
 # This code creates a `StringScanner` object
 # (we'll call it simply a *scanner*),

data/stdlib/tempfile/0/tempfile.rbs

@@ -248,8 +248,8 @@ class Tempfile < File
   #
   # Implementation note:
   #
-  # The keyword argument +anonymous=true+ is implemented using FILE_SHARE_DELETE
-  # on Windows. O_TMPFILE is used on Linux.
+  # The keyword argument `anonymous=true` is implemented using `FILE_SHARE_DELETE`
+  # on Windows. `O_TMPFILE` is used on Linux.
   #
   # Related: Tempfile.new.
   #

data/stdlib/time/0/time.rbs

@@ -10,7 +10,7 @@ class Time
 
   # <!--
   #   rdoc-file=lib/time.rb
-  #   - zone_offset(zone, year=self.now.year)
+  #   - zone_offset(zone, year=nil)
   # -->
   # Return the number of seconds the specified time zone differs from UTC.
   #

data/stdlib/timeout/0/timeout.rbs

@@ -26,7 +26,7 @@ module Timeout
   #   rdoc-file=lib/timeout.rb
   #   - timeout(sec, klass = nil, message = nil) { |sec| ... }
   # -->
-  # Perform an operation in a block, raising an error if it takes longer than
+  # Perform an operation in a block, raising an exception if it takes longer than
   # `sec` seconds to complete.
   #
   # `sec`
@@ -45,12 +45,20 @@ module Timeout
   #
   #
   # Returns the result of the block **if** the block completed before `sec`
-  # seconds, otherwise throws an exception, based on the value of `klass`.
+  # seconds, otherwise raises an exception, based on the value of `klass`.
   #
-  # The exception thrown to terminate the given block cannot be rescued inside the
-  # block unless `klass` is given explicitly. However, the block can use ensure to
-  # prevent the handling of the exception.  For that reason, this method cannot be
-  # relied on to enforce timeouts for untrusted blocks.
+  # The exception raised to terminate the given block is the given `klass`, or
+  # Timeout::ExitException if `klass` is not given. The reason for that behavior
+  # is that Timeout::Error inherits from RuntimeError and might be caught
+  # unexpectedly by `rescue`. Timeout::ExitException inherits from Exception so it
+  # will only be rescued by `rescue Exception`. Note that the
+  # Timeout::ExitException is translated to a Timeout::Error once it reaches the
+  # Timeout.timeout call, so outside that call it will be a Timeout::Error.
+  #
+  # In general, be aware that the code block may rescue the exception, and in such
+  # a case not respect the timeout. Also, the block can use `ensure` to prevent
+  # the handling of the exception. For those reasons, this method cannot be relied
+  # on to enforce timeouts for untrusted blocks.
   #
   # If a scheduler is defined, it will be used to handle the timeout by invoking
   # Scheduler#timeout_after.
@@ -59,11 +67,59 @@ module Timeout
   # Timeout` into your classes so they have a #timeout method, as well as a module
   # method, so you can call it directly as Timeout.timeout().
   #
+  # #### Ensuring the exception does not fire inside ensure blocks
+  #
+  # When using Timeout.timeout it can be desirable to ensure the timeout exception
+  # does not fire inside an `ensure` block. The simplest and best way to do so it
+  # to put the Timeout.timeout call inside the body of the begin/ensure/end:
+  #
+  #     begin
+  #       Timeout.timeout(sec) { some_long_operation }
+  #     ensure
+  #       cleanup # safe, cannot be interrupt by timeout
+  #     end
+  #
+  # If that is not feasible, e.g. if there are `ensure` blocks inside
+  # `some_long_operation`, they need to not be interrupted by timeout, and it's
+  # not possible to move these ensure blocks outside, one can use
+  # Thread.handle_interrupt to delay the timeout exception like so:
+  #
+  #     Thread.handle_interrupt(Timeout::Error => :never) {
+  #       Timeout.timeout(sec, Timeout::Error) do
+  #         setup # timeout cannot happen here, no matter how long it takes
+  #         Thread.handle_interrupt(Timeout::Error => :immediate) {
+  #           some_long_operation # timeout can happen here
+  #         }
+  #       ensure
+  #         cleanup # timeout cannot happen here, no matter how long it takes
+  #       end
+  #     }
+  #
+  # An important thing to note is the need to pass an exception klass to
+  # Timeout.timeout, otherwise it does not work. Specifically, using
+  # +Thread.handle_interrupt(Timeout::ExitException => ...)+ is unsupported and
+  # causes subtle errors like raising the wrong exception outside the block, do
+  # not use that.
+  #
+  # Note that Thread.handle_interrupt is somewhat dangerous because if setup or
+  # cleanup hangs then the current thread will hang too and the timeout will never
+  # fire. Also note the block might run for longer than `sec` seconds: e.g.
+  # some_long_operation executes for `sec` seconds + whatever time cleanup takes.
+  #
+  # If you want the timeout to only happen on blocking operations one can use
+  # :on_blocking instead of :immediate. However, that means if the block uses no
+  # blocking operations after `sec` seconds, the block will not be interrupted.
+  # ----
+  # <!--
+  #   rdoc-file=lib/timeout.rb
+  #   - timeout(*args, &block)
+  # -->
+  #
   def self?.timeout: [T] (Numeric? sec, ?singleton(Exception) klass, ?String message) { (Numeric sec) -> T } -> T
 end
 
 # <!-- rdoc-file=lib/timeout.rb -->
-# Internal error raised to when a timeout is triggered.
+# Internal exception raised to when a timeout is triggered.
 #
 class Timeout::ExitException < Exception
 end

data/stdlib/uri/0/generic.rbs

@@ -424,7 +424,7 @@ module URI
     #
     #     uri = URI.parse("http://john:S3nsit1ve@my.example.com")
     #     uri.user = "sam"
-    #     uri.to_s  #=> "http://sam:V3ry_S3nsit1ve@my.example.com"
+    #     uri.to_s  #=> "http://sam@my.example.com"
     #
     def user=: (String? user) -> String?
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbs
 version: !ruby/object:Gem::Version
-  version: 3.10.0.pre.2
+  version: 3.10.0
 platform: ruby
 authors:
 - Soutaro Matsumoto
@@ -106,6 +106,7 @@ files:
 - core/rbs/unnamed/random.rbs
 - core/refinement.rbs
 - core/regexp.rbs
+- core/ruby.rbs
 - core/ruby_vm.rbs
 - core/rubygems/basic_specification.rbs
 - core/rubygems/config_file.rbs
@@ -561,7 +562,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.1
+rubygems_version: 4.0.2
 specification_version: 4
 summary: Type signature for Ruby.
 test_files: []