# <!-- rdoc-file=lib/timeout.rb -->
# 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.timeout
# instead.
#
# ## Copyright
#
# Copyright
# :   (C) 2000  Network Applied Communication Laboratory, Inc.
# Copyright
# :   (C) 2000  Information-technology Promotion Agency, Japan
#
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
  # `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
  # `message`
  # :   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.timeout().
  #
  def self?.timeout: [T] (Numeric? sec, ?singleton(Exception) klass, ?String message) { (Numeric sec) -> T } -> T
end

# <!-- rdoc-file=lib/timeout.rb -->
# Raised by Timeout.timeout when the block times out.
#
class Timeout::Error < RuntimeError
  attr_reader thread: Thread?
end

Timeout::VERSION: String
