module Timeout

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.

Previous versions didn't use a module for namespacing, however timeout is provided for backwards compatibility. You should prefer #timeout instead.

Copyright

(C) 2000 Network Applied Communication Laboratory, Inc.

Copyright

(C) 2000 Information-technology Promotion Agency, Japan

Public Class Methods

timeout(sec, klass = nil) { |sec| ... } click to toggle source

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 number may be used, including Floats to specify fractional seconds. A value of 0 or nil will execute the block without any timeout.

klass

Exception Class to raise if the block fails to terminate in sec seconds. Omitting will use the default, Timeout::Error

Returns the result of the block if the block completed before sec seconds, otherwise throws an exception, based on the value of klass.

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.

# File lib/timeout.rb, line 51
def timeout(sec, klass = nil)   #:yield: +sec+
  return yield(sec) if sec == nil or sec.zero?
  exception = klass || Class.new(ExitException)
  begin
    begin
      x = Thread.current
      y = Thread.start {
        begin
          sleep sec
        rescue => e
          x.raise e
        else
          x.raise exception, "execution expired"
        end
      }
      return yield(sec)
    ensure
      if y
        y.kill
        y.join # make sure y is dead.
      end
    end
  rescue exception => e
    rej = /\A#{Regexp.quote(__FILE__)}:#{__LINE__-4}\z/o
    (bt = e.backtrace).reject! {|m| rej =~ m}
    level = -caller(CALLER_OFFSET).size
    while THIS_FILE =~ bt[level]
      bt.delete_at(level)
      level += 1
    end
    raise if klass            # if exception class is specified, it
                              # would be expected outside.
    raise Error, e.message, e.backtrace
  end
end

Private Instance Methods

timeout(sec, klass = nil) { |sec| ... } click to toggle source

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 number may be used, including Floats to specify fractional seconds. A value of 0 or nil will execute the block without any timeout.

klass

Exception Class to raise if the block fails to terminate in sec seconds. Omitting will use the default, Timeout::Error

Returns the result of the block if the block completed before sec seconds, otherwise throws an exception, based on the value of klass.

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.

# File lib/timeout.rb, line 51
def timeout(sec, klass = nil)   #:yield: +sec+
  return yield(sec) if sec == nil or sec.zero?
  exception = klass || Class.new(ExitException)
  begin
    begin
      x = Thread.current
      y = Thread.start {
        begin
          sleep sec
        rescue => e
          x.raise e
        else
          x.raise exception, "execution expired"
        end
      }
      return yield(sec)
    ensure
      if y
        y.kill
        y.join # make sure y is dead.
      end
    end
  rescue exception => e
    rej = /\A#{Regexp.quote(__FILE__)}:#{__LINE__-4}\z/o
    (bt = e.backtrace).reject! {|m| rej =~ m}
    level = -caller(CALLER_OFFSET).size
    while THIS_FILE =~ bt[level]
      bt.delete_at(level)
      level += 1
    end
    raise if klass            # if exception class is specified, it
                              # would be expected outside.
    raise Error, e.message, e.backtrace
  end
end