philiprehberger-timeout_kit 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 439206c3312c3911ae57be460c6d4c6fdae897dc334307b5a7ad2fb08f5ad3f2
-  data.tar.gz: dcdf01577d2efaec47d7ca37505baf755900902aba28d758347b41266b1f3b4e
+  metadata.gz: 38648273212e92534eb7dceadb874fdff11a9f79537322caccce2b80265eb227
+  data.tar.gz: 630c54614f2001126fe6a4f251421245b83832513e1c7b7ac865866a4cf5c77a
 SHA512:
-  metadata.gz: 77126a25c3e6d01c0d1dc9be4998314d04c3be99a2b8c9cd1154626ed05834ef507b1adaaefd4336b47ef307512ef080b20478218dca3b7459a4e41f41e3f9b3
-  data.tar.gz: 1ca69dbfd8a5d414b01329c691a07cf04fc91f5b676985b7737b8d907b0f292a33d08aeac9a6990684274fd4b4fac0a8675542402579259fa2c9a4a91c37b9d1
+  metadata.gz: 21f72a37fd9180990963331e97658273e1eee1e5492ecab899fb5540c4843cd55fa2cfd2345920e6840c4b47446c711fb599e4b367a22dc4f7b04ae7de86704b
+  data.tar.gz: 1850ebc59963836b441862c3794151f225247604462f43eaa3252ac1efc46efa0b2f5eb25622e992fed1d8c200b430f89f4253e1fbd671a29bf00ca24b17944e

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-29
+
+### Added
+- Deadline callbacks via `on_expire:` keyword argument or `Deadline#on_expire` block registration, fired once on first expiry detection
+- Grace period via `grace:` keyword argument with `Deadline#in_grace?` and `Deadline#grace_remaining` accessors
+- Deadline naming via `name:` keyword argument with `Deadline#name` accessor, included in error messages
+- Full README compliance with 8 badges, Support section, and all standard sections
+- GitHub issue templates (bug report, feature request), dependabot config, and PR template
+
+## [0.1.1] - 2026-03-22
+
+### Added
+- Expanded test suite from 19 to 30+ examples covering edge cases, error hierarchy, zero/large timeouts, nested deadlines, and cooperative timeout loops
+
 ## [0.1.0] - 2026-03-22
 
 ### Added

data/README.md

@@ -2,7 +2,12 @@
 
 [![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)
+[![GitHub release](https://img.shields.io/github/v/release/philiprehberger/rb-timeout-kit)](https://github.com/philiprehberger/rb-timeout-kit/releases)
+[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-timeout-kit)](https://github.com/philiprehberger/rb-timeout-kit/commits/main)
 [![License](https://img.shields.io/github/license/philiprehberger/rb-timeout-kit)](LICENSE)
+[![Bug Reports](https://img.shields.io/github/issues/philiprehberger/rb-timeout-kit/bug)](https://github.com/philiprehberger/rb-timeout-kit/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+[![Feature Requests](https://img.shields.io/github/issues/philiprehberger/rb-timeout-kit/enhancement)](https://github.com/philiprehberger/rb-timeout-kit/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
 
 Safe timeout patterns without Thread.raise
 
@@ -65,6 +70,52 @@ Philiprehberger::TimeoutKit.deadline(30) do |outer|
 end
 ```
 
+### Deadline Naming
+
+```ruby
+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
+
+```ruby
+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
+
+```ruby
+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
 
 ```ruby
@@ -89,12 +140,16 @@ end
 
 | Method | Description |
 |--------|-------------|
-| `.deadline(seconds) { \|d\| }` | Execute a block with a cooperative deadline |
+| `.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 |
-| `Deadline#remaining` | Seconds remaining until the deadline (0.0 if expired) |
-| `Deadline#expired?` | Whether the deadline has passed |
+| `Deadline#check!` | Raise `DeadlineExceeded` if the deadline has passed (respects grace period) |
+| `Deadline#remaining` | Seconds remaining until the primary deadline (negative during grace) |
+| `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
@@ -105,6 +160,13 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+If you find this package useful, consider giving it a star on GitHub — it helps motivate continued maintenance and development.
+
+[![LinkedIn](https://img.shields.io/badge/Philip%20Rehberger-LinkedIn-0A66C2?logo=linkedin)](https://www.linkedin.com/in/philiprehberger)
+[![More packages](https://img.shields.io/badge/more-open%20source%20packages-blue)](https://philiprehberger.com/open-source-packages)
+
 ## License
 
-MIT
+[MIT](LICENSE)

data/lib/philiprehberger/timeout_kit/deadline.rb

@@ -10,38 +10,97 @@ module Philiprehberger
       # @return [Float] the absolute monotonic time when the deadline expires
       attr_reader :expires_at
 
+      # @return [String, nil] the human-readable name for this deadline
+      attr_reader :name
+
       # Create a new deadline.
       #
       # @param seconds [Numeric] the number of seconds until the deadline expires
-      def initialize(seconds)
+      # @param name [String, nil] optional human-readable name for the deadline
+      # @param grace [Numeric, nil] optional grace period in seconds after the primary deadline
+      # @param on_expire [Proc, nil] optional callback that fires once when expiry is detected
+      def initialize(seconds, name: nil, grace: nil, on_expire: nil)
         @expires_at = now + seconds
+        @name = name
+        @grace_seconds = grace
+        @grace_expires_at = @grace_seconds ? @expires_at + @grace_seconds : nil
+        @on_expire = on_expire
+        @expire_callback_fired = false
+      end
+
+      # Register a callback that fires once when expiry is detected.
+      #
+      # @yield the block to call on expiry
+      # @return [void]
+      def on_expire(&block)
+        @on_expire = block
       end
 
       # Check whether the deadline has expired.
       #
-      # @raise [DeadlineExceeded] if the deadline has passed
+      # @raise [DeadlineExceeded] if the deadline has passed (and grace period, if any, has also passed)
       # @return [void]
       def check!
-        raise DeadlineExceeded, "Deadline exceeded" if expired?
+        return unless expired?
+
+        fire_expire_callback
+
+        # If we have a grace period and are still within it, don't raise
+        return if in_grace?
+
+        message = @name ? "Deadline '#{@name}' exceeded" : 'Deadline exceeded'
+        raise DeadlineExceeded, message
       end
 
-      # Return the remaining time in seconds.
+      # Return the remaining time in seconds until the primary deadline.
+      # Can be negative during the grace period.
       #
-      # @return [Float] seconds remaining (0.0 if expired)
+      # @return [Float] seconds remaining (negative if past primary deadline)
       def remaining
         r = @expires_at - now
+        if @grace_seconds
+          r
+        else
+          r.negative? ? 0.0 : r
+        end
+      end
+
+      # Return the remaining time in the grace period.
+      #
+      # @return [Float] seconds remaining in grace period (0.0 if no grace period or grace expired)
+      def grace_remaining
+        return 0.0 unless @grace_expires_at
+
+        r = @grace_expires_at - now
         r.negative? ? 0.0 : r
       end
 
-      # Whether the deadline has expired.
+      # Whether the primary deadline has expired.
       #
       # @return [Boolean]
       def expired?
         now >= @expires_at
       end
 
+      # Whether the deadline is currently in the grace period.
+      # True only when the primary deadline has expired but the grace period has not.
+      #
+      # @return [Boolean]
+      def in_grace?
+        return false unless @grace_expires_at
+
+        expired? && now < @grace_expires_at
+      end
+
       private
 
+      def fire_expire_callback
+        return if @expire_callback_fired || @on_expire.nil?
+
+        @expire_callback_fired = true
+        @on_expire.call
+      end
+
       def now
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end

data/lib/philiprehberger/timeout_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module TimeoutKit
-    VERSION = "0.1.0"
+    VERSION = '0.2.0'
   end
 end

data/lib/philiprehberger/timeout_kit.rb

@@ -14,20 +14,23 @@ module Philiprehberger
     # constraint, but outer deadlines are also checked.
     #
     # @param seconds [Numeric] the number of seconds for the deadline
+    # @param name [String, nil] optional human-readable name for the deadline
+    # @param grace [Numeric, nil] optional grace period in seconds after the primary deadline
+    # @param on_expire [Proc, nil] optional callback that fires once when expiry is detected
     # @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)
+    def self.deadline(seconds, name: nil, grace: nil, on_expire: nil, &block)
+      dl = Deadline.new(seconds, name: name, grace: grace, on_expire: on_expire)
 
       # Support nested deadlines: use the tightest constraint
       parent = current_deadline
       effective = if parent && parent.expires_at < dl.expires_at
-                   parent
-                 else
-                   dl
-                 end
+                    parent
+                  else
+                    dl
+                  end
 
       push_deadline(effective)
       begin
@@ -77,5 +80,5 @@ module Philiprehberger
   end
 end
 
-require_relative "timeout_kit/version"
-require_relative "timeout_kit/deadline"
+require_relative 'timeout_kit/version'
+require_relative 'timeout_kit/deadline'

metadata

@@ -1,18 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-timeout_kit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-22 00:00:00.000000000 Z
+date: 2026-03-30 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.
+  that avoid Thread.raise, with nested deadline support, grace periods, callbacks,
+  and explicit cancellation checks.
 email:
 - me@philiprehberger.com
 executables: []