timeout 0.4.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19bdc6e927cfc023688f6d4e08a55b1d483257bd450db6e203e1965158bb7ed4
-  data.tar.gz: 742db38b61ab633ca1baef82a73338b0e2d9e4a0d10bdf3908fc8ed87d04f4c2
+  metadata.gz: 31442005d41eeaddb46916ff83e27dc0198a3a0509c463d47d1fd4a9c7e0ec6d
+  data.tar.gz: bf8dff95c8356a47b513568f3c6890d2c1a9a74a6a364f5fa38d5e8f4b8e3c87
 SHA512:
-  metadata.gz: 6836956b4e59cebd6a14d0a9d3857c700a1bd65a566ff1d41be3657631b3e33a443910d4123dae1b81eaa81198896442f5c0f2a32e3b7182ad2144fdc39cbcfc
-  data.tar.gz: a7a4a1a176dcbf09297133476914684db3ae8c77c37d510af6d6200279f17fa0b1829c6b2ad19fa29b6be1c62f9b60aba6e362c47affcd71ec36ce934e8a391a
+  metadata.gz: 3630c0c2b33659c650a9f4af7d5983dd303d174431c7d7c137292e4c702ac95afaab7434b4061bd6b013edc10343fa141e0969ac4188f671cbc84a14583c9986
+  data.tar.gz: b835d20514bda974bd0f5cd6473213bd429a9887503802dc2882ab25ae00be502f5df84642f305eb348866e33c9357130b985012d936ed48eebfea800458853c

data/.document

@@ -0,0 +1,3 @@
+LICENSE.txt
+README.md
+lib/

data/{LICENSE.txt → BSDL}

@@ -4,10 +4,10 @@ Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
-notice, this list of conditions and the following disclaimer.
+   notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright
-notice, this list of conditions and the following disclaimer in the
-documentation and/or other materials provided with the distribution.
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
 
 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

data/COPYING

@@ -0,0 +1,56 @@
+Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.jp>.
+You can redistribute it and/or modify it under either the terms of the
+2-clause BSDL (see the file BSDL), or the conditions below:
+
+1. You may make and give away verbatim copies of the source form of the
+   software without restriction, provided that you duplicate all of the
+   original copyright notices and associated disclaimers.
+
+2. You may modify your copy of the software in any way, provided that
+   you do at least ONE of the following:
+
+   a. place your modifications in the Public Domain or otherwise
+      make them Freely Available, such as by posting said
+      modifications to Usenet or an equivalent medium, or by allowing
+      the author to include your modifications in the software.
+
+   b. use the modified software only within your corporation or
+      organization.
+
+   c. give non-standard binaries non-standard names, with
+      instructions on where to get the original software distribution.
+
+   d. make other distribution arrangements with the author.
+
+3. You may distribute the software in object code or binary form,
+   provided that you do at least ONE of the following:
+
+   a. distribute the binaries and library files of the software,
+      together with instructions (in the manual page or equivalent)
+      on where to get the original distribution.
+
+   b. accompany the distribution with the machine-readable source of
+      the software.
+
+   c. give non-standard binaries non-standard names, with
+      instructions on where to get the original software distribution.
+
+   d. make other distribution arrangements with the author.
+
+4. You may modify and include the part of the software into any other
+   software (possibly commercial).  But some files in the distribution
+   are not written by the author, so that they are not under these terms.
+
+   For the list of those files and their copying conditions, see the
+   file LEGAL.
+
+5. The scripts and library files supplied as input to or produced as
+   output from the software do not automatically fall under the
+   copyright of the software, but belong to whomever generated them,
+   and may be sold commercially, and may be aggregated with this
+   software.
+
+6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+   IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+   WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+   PURPOSE.

data/README.md

@@ -3,10 +3,6 @@
 Timeout provides a way to auto-terminate a potentially long-running
 operation if it hasn't finished in a fixed amount of time.
 
-Previous versions didn't use a module for namespacing, however
-#timeout is provided for backwards compatibility.  You
-should prefer Timeout.timeout instead.
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -27,7 +23,7 @@ Or install it yourself as:
 
 ```ruby
 require 'timeout'
-status = Timeout::timeout(5) {
+status = Timeout.timeout(5) {
   # Something that should be interrupted if it takes more than 5 seconds...
 }
 ```

data/lib/timeout.rb

@@ -4,7 +4,7 @@
 # == Synopsis
 #
 #   require 'timeout'
-#   status = Timeout::timeout(5) {
+#   status = Timeout.timeout(5) {
 #     # Something that should be interrupted if it takes more than 5 seconds...
 #   }
 #
@@ -13,28 +13,25 @@
 # Timeout provides a way to auto-terminate a potentially long-running
 # operation if it hasn't finished in a fixed amount of time.
 #
-# Previous versions didn't use a module for namespacing, however
-# #timeout is provided for backwards compatibility.  You
-# should prefer Timeout.timeout instead.
-#
 # == Copyright
 #
 # Copyright:: (C) 2000  Network Applied Communication Laboratory, Inc.
 # Copyright:: (C) 2000  Information-technology Promotion Agency, Japan
 
 module Timeout
-  VERSION = "0.4.0"
+  # The version
+  VERSION = "0.6.1"
 
-  # Internal error raised to when a timeout is triggered.
+  # Internal exception raised to when a timeout is triggered.
   class ExitException < Exception
-    def exception(*)
+    def exception(*) # :nodoc:
       self
     end
   end
 
   # Raised by Timeout.timeout when the block times out.
   class Error < RuntimeError
-    def self.handle_timeout(message)
+    def self.handle_timeout(message) # :nodoc:
       exc = ExitException.new(message)
 
       begin
@@ -47,12 +44,101 @@ module Timeout
   end
 
   # :stopdoc:
-  CONDVAR = ConditionVariable.new
-  QUEUE = Queue.new
-  QUEUE_MUTEX = Mutex.new
-  TIMEOUT_THREAD_MUTEX = Mutex.new
-  @timeout_thread = nil
-  private_constant :CONDVAR, :QUEUE, :QUEUE_MUTEX, :TIMEOUT_THREAD_MUTEX
+
+  # We keep a private reference so that time mocking libraries won't break Timeout.
+  GET_TIME = Process.method(:clock_gettime)
+  if defined?(Ractor.make_shareable)
+    # Ractor.make_shareable(Method) only works on Ruby 4+
+    Ractor.make_shareable(GET_TIME) rescue nil
+  end
+  private_constant :GET_TIME
+
+  class State
+    def initialize
+      @condvar = ConditionVariable.new
+      @queue = Queue.new
+      @queue_mutex = Mutex.new
+
+      @timeout_thread = nil
+      @timeout_thread_mutex = Mutex.new
+    end
+
+    if defined?(Ractor.store_if_absent) && defined?(Ractor.shareable?) && Ractor.shareable?(GET_TIME)
+      # Ractor support if
+      # 1. Ractor.store_if_absent is available
+      # 2. Method object can be shareable (4.0~)
+      def self.instance
+        Ractor.store_if_absent :timeout_gem_state do
+          State.new
+        end
+      end
+    else
+      GLOBAL_STATE = State.new
+
+      def self.instance
+        GLOBAL_STATE
+      end
+    end
+
+    def create_timeout_thread
+      # Threads unexpectedly inherit the interrupt mask: https://github.com/ruby/timeout/issues/41
+      # So reset the interrupt mask to the default one for the timeout thread
+      Thread.handle_interrupt(Object => :immediate) do
+        watcher = Thread.new do
+          requests = []
+          while true
+            until @queue.empty? and !requests.empty? # wait to have at least one request
+              req = @queue.pop
+              requests << req unless req.done?
+            end
+            closest_deadline = requests.min_by(&:deadline).deadline
+
+            now = 0.0
+            @queue_mutex.synchronize do
+              while (now = GET_TIME.call(Process::CLOCK_MONOTONIC)) < closest_deadline and @queue.empty?
+                @condvar.wait(@queue_mutex, closest_deadline - now)
+              end
+            end
+
+            requests.each do |req|
+              req.interrupt if req.expired?(now)
+            end
+            requests.reject!(&:done?)
+          end
+        end
+
+        if !watcher.group.enclosed? && (!defined?(Ractor.main?) || Ractor.main?)
+          ThreadGroup::Default.add(watcher)
+        end
+
+        watcher.name = "Timeout stdlib thread"
+        watcher.thread_variable_set(:"\0__detached_thread__", true)
+        watcher
+      end
+    end
+
+    def ensure_timeout_thread_created
+      unless @timeout_thread&.alive?
+        # If the Mutex is already owned we are in a signal handler.
+        # In that case, just return and let the main thread create the Timeout thread.
+        return if @timeout_thread_mutex.owned?
+
+        Sync.synchronize @timeout_thread_mutex do
+          unless @timeout_thread&.alive?
+            @timeout_thread = create_timeout_thread
+          end
+        end
+      end
+    end
+
+    def add_request(request)
+      Sync.synchronize @queue_mutex do
+        @queue << request
+        @condvar.signal
+      end
+    end
+  end
+  private_constant :State
 
   class Request
     attr_reader :deadline
@@ -67,6 +153,7 @@ module Timeout
       @done = false # protected by @mutex
     end
 
+    # Only called by the timeout thread, so does not need Sync.synchronize
     def done?
       @mutex.synchronize do
         @done
@@ -77,6 +164,7 @@ module Timeout
       now >= @deadline
     end
 
+    # Only called by the timeout thread, so does not need Sync.synchronize
     def interrupt
       @mutex.synchronize do
         unless @done
@@ -87,105 +175,128 @@ module Timeout
     end
 
     def finished
-      @mutex.synchronize do
+      Sync.synchronize @mutex do
         @done = true
       end
     end
   end
   private_constant :Request
 
-  def self.create_timeout_thread
-    watcher = Thread.new do
-      requests = []
-      while true
-        until QUEUE.empty? and !requests.empty? # wait to have at least one request
-          req = QUEUE.pop
-          requests << req unless req.done?
-        end
-        closest_deadline = requests.min_by(&:deadline).deadline
-
-        now = 0.0
-        QUEUE_MUTEX.synchronize do
-          while (now = GET_TIME.call(Process::CLOCK_MONOTONIC)) < closest_deadline and QUEUE.empty?
-            CONDVAR.wait(QUEUE_MUTEX, closest_deadline - now)
-          end
-        end
-
-        requests.each do |req|
-          req.interrupt if req.expired?(now)
-        end
-        requests.reject!(&:done?)
-      end
-    end
-    ThreadGroup::Default.add(watcher) unless watcher.group.enclosed?
-    watcher.name = "Timeout stdlib thread"
-    watcher.thread_variable_set(:"\0__detached_thread__", true)
-    watcher
-  end
-  private_class_method :create_timeout_thread
-
-  def self.ensure_timeout_thread_created
-    unless @timeout_thread and @timeout_thread.alive?
-      TIMEOUT_THREAD_MUTEX.synchronize do
-        unless @timeout_thread and @timeout_thread.alive?
-          @timeout_thread = create_timeout_thread
-        end
+  module Sync
+    # Calls mutex.synchronize(&block) but if that fails on CRuby due to being in a trap handler,
+    # run mutex.synchronize(&block) in a separate Thread instead.
+    def self.synchronize(mutex, &block)
+      begin
+        mutex.synchronize(&block)
+      rescue ThreadError => e
+        raise e unless e.message == "can't be called from trap context"
+        # Workaround CRuby issue https://bugs.ruby-lang.org/issues/19473
+        # which raises on Mutex#synchronize in trap handler.
+        # It's expensive to create a Thread just for this,
+        # but better than failing.
+        Thread.new {
+          mutex.synchronize(&block)
+        }.join
       end
     end
   end
-
-  # We keep a private reference so that time mocking libraries won't break
-  # Timeout.
-  GET_TIME = Process.method(:clock_gettime)
-  private_constant :GET_TIME
+  private_constant :Sync
 
   # :startdoc:
 
-  # 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+:: Number of seconds to wait for the block to terminate. Any number
-  #         may be used, including Floats to specify fractional seconds. A
+  # +sec+:: Number of seconds to wait for the block to terminate. Any non-negative number
+  #         or nil may be used, including Floats to specify fractional seconds. A
   #         value of 0 or +nil+ will execute the block without any timeout.
+  #         Any negative number will raise an ArgumentError.
   # +klass+:: Exception Class to raise if the block fails to terminate
-  #           in +sec+ seconds.  Omitting will use the default, Timeout::Error
+  #           in +sec+ seconds.  Omitting will use the default, Timeout::Error.
   # +message+:: Error message to raise with Exception Class.
-  #             Omitting will use the default, "execution expired"
+  #             Omitting will use the default, <tt>"execution expired"</tt>.
   #
   # Returns the result of the block *if* the block completed before
-  # +sec+ seconds, otherwise throws an exception, based on the value of +klass+.
+  # +sec+ 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 <tt>rescue Exception</tt>.
+  # 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.
+  # Fiber::Scheduler#timeout_after.
   #
   # Note that this is both a method of module Timeout, so you can <tt>include
   # Timeout</tt> into your classes so they have a #timeout method, as well as
   # a module method, so you can call it directly as Timeout.timeout().
-  def timeout(sec, klass = nil, message = nil, &block)   #:yield: +sec+
+  #
+  # ==== 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 is 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 interrupted 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 <tt>Thread.handle_interrupt(Timeout::ExitException => ...)</tt>
+  # 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.
+  def self.timeout(sec, klass = nil, message = nil, &block)   #:yield: +sec+
     return yield(sec) if sec == nil or sec.zero?
+    raise ArgumentError, "Timeout sec must be a non-negative number" if 0 > sec
 
     message ||= "execution expired"
 
     if Fiber.respond_to?(:current_scheduler) && (scheduler = Fiber.current_scheduler)&.respond_to?(:timeout_after)
-      return scheduler.timeout_after(sec, klass || Error, message, &block)
-    end
-
-    Timeout.ensure_timeout_thread_created
-    perform = Proc.new do |exc|
-      request = Request.new(Thread.current, sec, exc, message)
-      QUEUE_MUTEX.synchronize do
-        QUEUE << request
-        CONDVAR.signal
+      perform = Proc.new do |exc|
+        scheduler.timeout_after(sec, exc, message, &block)
       end
-      begin
-        return yield(sec)
-      ensure
-        request.finished
+    else
+      state = State.instance
+      state.ensure_timeout_thread_created
+
+      perform = Proc.new do |exc|
+        request = Request.new(Thread.current, sec, exc, message)
+        state.add_request(request)
+        begin
+          return yield(sec)
+        ensure
+          request.finished
+        end
       end
     end
 
@@ -195,5 +306,9 @@ module Timeout
       Error.handle_timeout(message, &perform)
     end
   end
-  module_function :timeout
+
+  # See Timeout.timeout
+  private def timeout(*args, &block)
+    Timeout.timeout(*args, &block)
+  end
 end

data/timeout.gemspec

@@ -20,6 +20,9 @@ Gem::Specification.new do |spec|
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = spec.homepage + "/releases"
+
+  spec.required_ruby_version = '>= 2.6.0'
 
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: timeout
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Yukihiro Matsumoto
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-23 00:00:00.000000000 Z
+date: 2026-03-09 00:00:00.000000000 Z
 dependencies: []
 description: Auto-terminate potentially long-running operations in Ruby.
 email:
@@ -17,8 +16,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".document"
+- BSDL
+- COPYING
 - Gemfile
-- LICENSE.txt
 - README.md
 - lib/timeout.rb
 - timeout.gemspec
@@ -29,7 +30,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/ruby/timeout
   source_code_uri: https://github.com/ruby/timeout
-post_install_message:
+  changelog_uri: https://github.com/ruby/timeout/releases
 rdoc_options: []
 require_paths:
 - lib
@@ -37,15 +38,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.0.dev
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Auto-terminate potentially long-running operations in Ruby.
 test_files: []