123456789_123456789_123456789_123456789_123456789_

Module: Timeout

Relationships & Source Files
Namespace Children
Classes:
Request
Exceptions:
Error, ExitException
Defined in: lib/timeout.rb

Overview

Timeout long-running blocks

Synopsis

require 'timeout'
status = Timeout.timeout(5) {
  # Something that should be interrupted if it takes more than 5 seconds...
}

Description

Timeout provides a way to auto-terminate a potentially long-running operation if it hasn’t finished in a fixed amount of time.

Copyright

© 2000 Network Applied Communication Laboratory, Inc.

Copyright

© 2000 Information-technology Promotion Agency, Japan

Constant Summary

Class Method Summary

Class Method Details

.create_timeout_thread (private)

This method is for internal use only.
[ GitHub ] 

  


# File 'lib/timeout.rb', line 94



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


  








  

    .ensure_timeout_thread_created  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'lib/timeout.rb', line 124



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
    end
  end
end


  








  

    .timeout(sec, klass = nil, message = nil, &block)   (mod_func)
  



  

    

Perform an operation in a block, raising an error if it takes longer than sec seconds to complete.


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


message




::Timeout::Error message to raise with Exception Class. Omitting will use the default, “execution expired”





Returns the result of the block if the block completed before sec seconds, otherwise throws 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.



If a scheduler is defined, it will be used to handle the timeout by invoking Scheduler#timeout_after.



Note that this is both a method of module Timeout, so you can include Timeout into your classes so they have a #timeout method, as well as a module method, so you can call it directly as timeout().


  





  
Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/timeout.rb', line 167



def 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
    end
    begin
      return yield(sec)
    ensure
      request.finished
    end
  end

  if klass
    perform.call(klass)
  else
    Error.handle_timeout(message, &perform)
  end
end