philiprehberger-timeout_kit

Safe timeout patterns without Thread.raise

Requirements

• Ruby >= 3.1

Installation

Add to your Gemfile:

gem "philiprehberger-timeout_kit"

Or install directly:

gem install philiprehberger-timeout_kit

Usage

require "philiprehberger/timeout_kit"

Philiprehberger::TimeoutKit.deadline(5) do |d|
  loop do
    d.check!  # raises DeadlineExceeded if time is up
    process_next_item
  end
end

Remaining Time

Philiprehberger::TimeoutKit.deadline(10) do |d|
  while d.remaining > 1
    do_work
    d.check!
  end
  puts "Only #{d.remaining}s left, wrapping up"
end

Measuring elapsed time

Philiprehberger::TimeoutKit.deadline(10) do |d|
  do_work
  puts "Work took #{d.elapsed}s so far"
  # elapsed continues to grow past the budget even after expiration
end

Deadline Progress

deadline = Philiprehberger::TimeoutKit::Deadline.new(10)
sleep 5
deadline.progress # => 0.5 (approximately)

Nested Deadlines

Philiprehberger::TimeoutKit.deadline(30) do |outer|
  # Inner deadline is tighter, so it takes precedence
  Philiprehberger::TimeoutKit.deadline(5) do |inner|
    inner.check!
    puts inner.remaining  # <= 5
  end

  # After inner block, outer deadline is restored
  outer.check!
  puts outer.remaining  # <= 30
end

Deadline Naming

Philiprehberger::TimeoutKit.deadline(10, name: 'db_query') do |d|
  d.check!  # raises "Deadline 'db_query' exceeded" if expired
  puts d.name  # => "db_query"
end

Deadline Callbacks

Philiprehberger::TimeoutKit.deadline(10, on_expire: -> { cleanup() }) do |d|
  loop do
    d.check!  # fires callback once on first expiry detection
    process_next_item
  end
end

# Or register via block
Philiprehberger::TimeoutKit.deadline(10) do |d|
  d.on_expire { cleanup() }
  loop do
    d.check!
    process_next_item
  end
end

Grace Period

Philiprehberger::TimeoutKit.deadline(10, grace: 2) do |d|
  loop do
    d.check!  # does not raise during 2s grace period
    break if d.expired?

    process_next_item
  end

  if d.in_grace?
    puts "Grace period: #{d.grace_remaining}s left to wrap up"
  end
end

Cooperative Timeout

Philiprehberger::TimeoutKit.cooperative(5) do |t|
  items.each do |item|
    t.check!
    process(item)
  end
end

Current Deadline

Philiprehberger::TimeoutKit.deadline(10) do |_d|
  current = Philiprehberger::TimeoutKit.current_deadline
  puts current.remaining
end

API

Method	Description
.deadline(seconds, name:, grace:, on_expire:) { |d| }	Execute a block with a cooperative deadline
.cooperative(seconds) { |t| }	Execute a block with a simple cooperative timeout
.current_deadline	Return the current active deadline or nil
Deadline#check!	Raise DeadlineExceeded if the deadline has passed (respects grace period)
Deadline#remaining	Seconds remaining until the primary deadline (negative during grace)
Deadline#elapsed	Seconds elapsed since the deadline was created (continues past the budget after expiration)
Deadline#duration	The original budget passed to Deadline.new (Float)
Deadline#progress	Fraction of the budget that has elapsed (elapsed / duration); exceeds 1.0 after expiry
Deadline#expired?	Whether the primary deadline has passed
Deadline#name	The human-readable name for this deadline (nil if not set)
Deadline#in_grace?	Whether the deadline is in the grace period
Deadline#grace_remaining	Seconds remaining in the grace period (0.0 if none)
Deadline#on_expire { }	Register a callback that fires once on expiry detection
DeadlineExceeded	Raised when a deadline or timeout expires

Development

bundle install
bundle exec rspec
bundle exec rubocop

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT