philiprehberger-timeout_kit 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb17ea7722ec6fc8ea24e1a8a0893646325c69b699ca72540316246805883ae9
-  data.tar.gz: 4e0f67f146bf729e7b168f663ee8487a750a7c2db2b41dea0ba33b21b851a440
+  metadata.gz: 7a8adc873e824dbd74917d235e838e7471d7e8d5171dced00b3c551d6cd122c7
+  data.tar.gz: c32d783deeb26085d274dd7e802f0127848ad14292d25bb90edc72f8dbe1112b
 SHA512:
-  metadata.gz: fc7a2917806f244243e6c48cfd0a9fec9a86494257317242b766bbeb42a0a9748ab1810ef38834c6e2d82bd6c9909dfcfdb8eca5a627cbdc8b5bcc1db75141dc
-  data.tar.gz: 397b475df8ea8cc6b3c1139e28d2e84ec00548b49caeade1187981c1eca99daa040203e946a64d1531a22cdcb8ac6afaa0f2791fe661dd707173f70dd517c0e9
+  metadata.gz: 41d90f277f055add991dede2a122ba767b109cc1d112526ef4aab0a217b935ad16df0e38ddf78ec78b9cc54de7e4d5c8b542b2b93d6f7c95908ed0deb3c7804a
+  data.tar.gz: 39b256c071b1b339f37b02bb13c07ed76fe486b78006961178c6d6e56d0046c1f04dab90d102b0fd14aa3cfb5b6a343f239c92e654de13fa9ce79658e1c56f64

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-03-31
+
+### Changed
+- Standardize README badges, support section, and license format
+
+## [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

data/README.md

@@ -2,7 +2,7 @@
 
 [![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)
+[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-timeout-kit)](https://github.com/philiprehberger/rb-timeout-kit/commits/main)
 
 Safe timeout patterns without Thread.raise
 
@@ -65,6 +65,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 +135,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 +155,24 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+If you find this project useful:
+
+⭐ [Star the repo](https://github.com/philiprehberger/rb-timeout-kit)
+
+🐛 [Report issues](https://github.com/philiprehberger/rb-timeout-kit/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+
+💡 [Suggest features](https://github.com/philiprehberger/rb-timeout-kit/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+
+❤️ [Sponsor development](https://github.com/sponsors/philiprehberger)
+
+🌐 [All Open Source Projects](https://philiprehberger.com/open-source-packages)
+
+💻 [GitHub Profile](https://github.com/philiprehberger)
+
+🔗 [LinkedIn Profile](https://www.linkedin.com/in/philiprehberger)
+
 ## 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.1"
+    VERSION = '0.2.1'
   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.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-22 00:00:00.000000000 Z
+date: 2026-03-31 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: []