philiprehberger-timeout_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 439206c3312c3911ae57be460c6d4c6fdae897dc334307b5a7ad2fb08f5ad3f2
+  data.tar.gz: dcdf01577d2efaec47d7ca37505baf755900902aba28d758347b41266b1f3b4e
+SHA512:
+  metadata.gz: 77126a25c3e6d01c0d1dc9be4998314d04c3be99a2b8c9cd1154626ed05834ef507b1adaaefd4336b47ef307512ef080b20478218dca3b7459a4e41f41e3f9b3
+  data.tar.gz: 1ca69dbfd8a5d414b01329c691a07cf04fc91f5b676985b7737b8d907b0f292a33d08aeac9a6990684274fd4b4fac0a8675542402579259fa2c9a4a91c37b9d1

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-22
+
+### Added
+- Initial release
+- Cooperative deadline with nested support and remaining time tracking
+- Cooperative timeout with explicit cancellation checks
+- DeadlineExceeded error for expired deadlines
+- Thread-local deadline stack for nested contexts

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,110 @@
+# philiprehberger-timeout_kit
+
+[![Tests](https://github.com/philiprehberger/rb-timeout-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-timeout-kit/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-timeout_kit.svg)](https://rubygems.org/gems/philiprehberger-timeout_kit)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-timeout-kit)](LICENSE)
+
+Safe timeout patterns without Thread.raise
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-timeout_kit"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-timeout_kit
+```
+
+## Usage
+
+```ruby
+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
+
+```ruby
+Philiprehberger::TimeoutKit.deadline(10) do |d|
+  while d.remaining > 1
+    do_work
+    d.check!
+  end
+  puts "Only #{d.remaining}s left, wrapping up"
+end
+```
+
+### Nested Deadlines
+
+```ruby
+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
+```
+
+### Cooperative Timeout
+
+```ruby
+Philiprehberger::TimeoutKit.cooperative(5) do |t|
+  items.each do |item|
+    t.check!
+    process(item)
+  end
+end
+```
+
+### Current Deadline
+
+```ruby
+Philiprehberger::TimeoutKit.deadline(10) do |_d|
+  current = Philiprehberger::TimeoutKit.current_deadline
+  puts current.remaining
+end
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `.deadline(seconds) { \|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 |
+| `Deadline#remaining` | Seconds remaining until the deadline (0.0 if expired) |
+| `Deadline#expired?` | Whether the deadline has passed |
+| `DeadlineExceeded` | Raised when a deadline or timeout expires |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/philiprehberger/timeout_kit/deadline.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module TimeoutKit
+    # A cooperative deadline that tracks remaining time and supports nesting.
+    #
+    # Deadlines do not use Thread.raise. Instead, callers must explicitly
+    # call {#check!} at safe cancellation points.
+    class Deadline
+      # @return [Float] the absolute monotonic time when the deadline expires
+      attr_reader :expires_at
+
+      # Create a new deadline.
+      #
+      # @param seconds [Numeric] the number of seconds until the deadline expires
+      def initialize(seconds)
+        @expires_at = now + seconds
+      end
+
+      # Check whether the deadline has expired.
+      #
+      # @raise [DeadlineExceeded] if the deadline has passed
+      # @return [void]
+      def check!
+        raise DeadlineExceeded, "Deadline exceeded" if expired?
+      end
+
+      # Return the remaining time in seconds.
+      #
+      # @return [Float] seconds remaining (0.0 if expired)
+      def remaining
+        r = @expires_at - now
+        r.negative? ? 0.0 : r
+      end
+
+      # Whether the deadline has expired.
+      #
+      # @return [Boolean]
+      def expired?
+        now >= @expires_at
+      end
+
+      private
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/philiprehberger/timeout_kit/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module TimeoutKit
+    VERSION = "0.1.0"
+  end
+end

data/lib/philiprehberger/timeout_kit.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module TimeoutKit
+    class Error < StandardError; end
+
+    # Raised when a deadline or cooperative timeout expires.
+    class DeadlineExceeded < Error; end
+
+    # Execute a block with a deadline. The block receives a {Deadline} object
+    # that can be used to check remaining time and whether the deadline has passed.
+    #
+    # Deadlines can be nested. The innermost deadline is always the tightest
+    # constraint, but outer deadlines are also checked.
+    #
+    # @param seconds [Numeric] the number of seconds for the deadline
+    # @yield [deadline] the block to execute within the deadline
+    # @yieldparam deadline [Deadline] the deadline context
+    # @return the block's return value
+    # @raise [DeadlineExceeded] if the deadline is exceeded and {Deadline#check!} is called
+    def self.deadline(seconds, &block)
+      dl = Deadline.new(seconds)
+
+      # Support nested deadlines: use the tightest constraint
+      parent = current_deadline
+      effective = if parent && parent.expires_at < dl.expires_at
+                   parent
+                 else
+                   dl
+                 end
+
+      push_deadline(effective)
+      begin
+        block.call(effective)
+      ensure
+        pop_deadline
+      end
+    end
+
+    # Execute a block with a cooperative timeout. The block receives a timeout
+    # context that can be checked at safe cancellation points.
+    #
+    # Unlike {.deadline}, this is a simpler wrapper that does not support nesting.
+    #
+    # @param seconds [Numeric] the number of seconds for the timeout
+    # @yield [timeout] the block to execute within the timeout
+    # @yieldparam timeout [Deadline] a deadline-like context for checking timeout
+    # @return the block's return value
+    # @raise [DeadlineExceeded] if the timeout is exceeded and {Deadline#check!} is called
+    def self.cooperative(seconds)
+      dl = Deadline.new(seconds)
+      yield dl
+    end
+
+    # Return the current innermost deadline, or nil if none is active.
+    #
+    # @return [Deadline, nil]
+    def self.current_deadline
+      stack = Thread.current[:philiprehberger_timeout_kit_deadlines]
+      stack&.last
+    end
+
+    # @api private
+    def self.push_deadline(deadline)
+      Thread.current[:philiprehberger_timeout_kit_deadlines] ||= []
+      Thread.current[:philiprehberger_timeout_kit_deadlines].push(deadline)
+    end
+    private_class_method :push_deadline
+
+    # @api private
+    def self.pop_deadline
+      stack = Thread.current[:philiprehberger_timeout_kit_deadlines]
+      stack&.pop
+      Thread.current[:philiprehberger_timeout_kit_deadlines] = nil if stack&.empty?
+    end
+    private_class_method :pop_deadline
+  end
+end
+
+require_relative "timeout_kit/version"
+require_relative "timeout_kit/deadline"

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-timeout_kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 00:00:00.000000000 Z
+dependencies: []
+description: A cooperative timeout library providing deadline and timeout patterns
+  that avoid Thread.raise, with nested deadline support and explicit cancellation
+  checks.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/timeout_kit.rb
+- lib/philiprehberger/timeout_kit/deadline.rb
+- lib/philiprehberger/timeout_kit/version.rb
+homepage: https://github.com/philiprehberger/rb-timeout-kit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-timeout-kit
+  source_code_uri: https://github.com/philiprehberger/rb-timeout-kit
+  changelog_uri: https://github.com/philiprehberger/rb-timeout-kit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-timeout-kit/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Safe timeout patterns without Thread.raise
+test_files: []