deadline_machines 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c025a93a7c8b92aac8ca2e2ff49e11642a4a2f340e6d53db262234d66fa793c7
+  data.tar.gz: d2e0aa5a9c97eb1dfcfd7ed8177ffa92b1d4c2591a7c415cdfb3bd1ab667933d
+SHA512:
+  metadata.gz: 0a6c0eeeb3c2fe88f63f9298aa5d669a1f2fab1e2c736513df7b4cbdae272a492d3c1df6b9d7eb6927b37561721aef6dbc657f13e3114bf4f54b70926188ec61
+  data.tar.gz: b5303a52f3a0e5c82c7eae24d6cc43180803491cae205e1b11f742430e4fdc0ec8385ff329a31ccb259ecc6ceb39241c78b3bf83c6a2bdd99f29a37e78c2e9ae

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [0.1.1](https://github.com/seuros/deadline_machines/compare/deadline_machines-v0.1.0...deadline_machines/v0.1.1) (2026-11-01)
+
+
+### Features
+
+* **core:** add Scope, RBS signatures, release config and CI ([24018c3](https://github.com/seuros/deadline_machines/commit/24018c39edcb12634f92057d699e1f2ad936ad4a))
+* deadline propagation and cooperative cancellation ([9858496](https://github.com/seuros/deadline_machines/commit/9858496f48cc0eca1edf8df613f9974fa15abba2))
+
+
+### Bug Fixes
+
+* a block scope lets go of its child's retention too ([e5502c2](https://github.com/seuros/deadline_machines/commit/e5502c29ba21306ef386303e465195d27cb5d643))
+* a cancellation racing a registration no longer strands the child ([e387b71](https://github.com/seuros/deadline_machines/commit/e387b71e6464bb5a6b35ec17b68e898231a8eca7))
+* a failed gem push fails the release ([26678da](https://github.com/seuros/deadline_machines/commit/26678da9039c72be8457e53f3cc4473b6394f5c1))
+* a nested scope without a limit inherits the ambient budget ([f88a0d5](https://github.com/seuros/deadline_machines/commit/f88a0d56497ee199664bd96fa479d6262abcc245))
+* a parent no longer owns every deadline derived from it ([41d609c](https://github.com/seuros/deadline_machines/commit/41d609c623a480b94a3f2789c0d7c3dbf2920ee9))
+* an observer deep in a chain is held all the way to the root ([9abeb8d](https://github.com/seuros/deadline_machines/commit/9abeb8d311f85991d4eed2d4f932b147e59ed574))
+* detachment stops the retention walk, not just its first step ([44ff4d1](https://github.com/seuros/deadline_machines/commit/44ff4d108a6dc139a7731e50432d5010b2f7c2cd))
+* one failing cancel observer no longer silences its peers ([a9ddd70](https://github.com/seuros/deadline_machines/commit/a9ddd70d0d1355aacfc0170d9b874bd9c90e3309))
+* one lock per tree, so a retention chain walk is atomic ([eec49b9](https://github.com/seuros/deadline_machines/commit/eec49b9ff6a79930cfbb4cbb8de398ad7b75efaa))
+* ship the core's test files so the packaged crate builds ([0340bc6](https://github.com/seuros/deadline_machines/commit/0340bc6ec958cb1983212f4cd0b9943cc36aef5c))
+
+## 0.1.0
+
+- Initial release.
+- `DeadlineMachines::Deadline`: monotonic budgets, `derive` for child scopes that
+  cannot outlive their parent, cancellation that flows down a tree, and `check!`
+  as the only place an error is raised.
+- `DeadlineMachines.with_deadline` for a fiber-scoped ambient deadline.
+- `DeadlineMachines::TestClock` for deterministic tests across the family.
+- `deadline-machines` core crate: the same arithmetic and cancellation tree in
+  `no_std` Rust with zero dependencies, plus `Scope` pairing a budget with a
+  cancellation handle. Builds and lints clean on bare metal.
+- RBS signatures for the whole public API.

data/Cargo.toml

@@ -0,0 +1,24 @@
+[workspace]
+members = ["ext/deadline_machines_native/core"]
+resolver = "3"
+
+[workspace.package]
+edition = "2024"
+rust-version = "1.99"
+
+[workspace.dependencies]
+deadline-machines = { path = "ext/deadline_machines_native/core" }
+
+[workspace.lints.rust]
+unsafe_code = "forbid"
+unused_must_use = "warn"
+
+[workspace.lints.clippy]
+all = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+nursery = { level = "warn", priority = -1 }
+expect_used = "deny"
+unwrap_used = "deny"
+uninlined_format_args = "deny"
+needless_borrow = "deny"
+redundant_clone = "deny"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Abdelkader Boudih
+
+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,115 @@
+# DeadlineMachines ⏱️
+
+> **One clock for the whole fleet.** The tender that hands every ship the same
+> budget, so nobody spends time the mission no longer has.
+
+Deadline propagation and cooperative cancellation for Ruby.
+
+`Timeout.timeout` raises wherever the interpreter happens to be, which is why it
+corrupts connection state and why every serious library bans it. A deadline here
+is a value you pass down and check at points you choose. **AMS Layland** carries
+no weapons and trips no failures; it keeps the time the rest of the fleet
+navigates by.
+
+---
+
+## 🚀 Launch Sequence
+
+```bash
+# Add to your ship's Gemfile
+gem 'deadline_machines'
+```
+
+Requires **Ruby 4.0+**. Nothing else: no Rust toolchain, no platform gem, no
+compiled extension.
+
+---
+
+## 🎯 Mission Brief
+
+```ruby
+DeadlineMachines.with_deadline(5) do |request|
+  request.remaining        # => 5.0
+
+  request.derive(1) do |attempt|
+    attempt.remaining      # => 1.0
+    attempt.check!         # raises DeadlineMachines::Exceeded when spent
+  end
+
+  DeadlineMachines.with_deadline(60) do
+    DeadlineMachines.remaining # => 5.0, a nested scope cannot widen the budget
+  end
+
+  request.cancel('client hung up')
+  DeadlineMachines.check!  # raises DeadlineMachines::Cancelled
+end
+```
+
+---
+
+## 🛰️ Why the Fleet Needs It
+
+Without a shared budget, a retry policy will happily spend thirty seconds on a
+request the caller abandoned twenty-eight seconds ago. `clamp_sleep` is the hook
+that stops it:
+
+```ruby
+delay = deadline.clamp_sleep(backoff.next_delay) # never overruns what is left
+```
+
+`DeadlineMachines.current` is fiber-scoped, so `Async` tasks inherit the ambient
+deadline without being handed one.
+
+---
+
+## 🕰️ The Ship's Chronometer
+
+Budgets are built on `CLOCK_MONOTONIC`, so an NTP step cannot stretch them.
+Inject `TestClock` and the whole family becomes deterministic:
+
+```ruby
+clock = DeadlineMachines::TestClock.new
+DeadlineMachines.clock = clock
+deadline = DeadlineMachines::Deadline.after(1)
+clock.advance(2)
+deadline.expired? # => true
+```
+
+---
+
+## 🔻 Cancellation Runs Down the Chain of Command
+
+Cancellation flows down a tree and never up. A child derived after its parent was
+cancelled is already cancelled. `on_cancel` fires once, and a callback registered
+on an already-cancelled deadline fires immediately. The block form of `derive`
+unlinks the child on exit, so a long-lived parent does not accumulate children.
+
+---
+
+## 🔩 The Rust Core, and Why No Extension
+
+The same arithmetic and cancellation tree ships as the `deadline-machines` crate
+under `ext/deadline_machines_native/core`, `no_std` with zero dependencies and
+verified on bare metal. `Scope` there is the peer of `Deadline` here: a budget
+and a cancellation handle as one value.
+
+The gem itself is pure Ruby. Reading a monotonic clock is already a vDSO read,
+so there is nothing here worth a native extension. The crate is there for Rust
+consumers, not for this gem's install.
+
+---
+
+## 📡 Credits
+
+**AMS Layland**, NCC-0112, *Layland*-class tender.
+
+Named for C. L. Liu and James W. Layland's *Scheduling Algorithms for
+Multiprogramming in a Hard-Real-Time Environment* (1973), which gave
+earliest-deadline-first scheduling its proof and made a deadline a value a
+system reasons about rather than an alarm it waits for.
+
+---
+
+## License
+
+MIT.

data/ext/deadline_machines_native/core/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "deadline-machines"
+version = "0.2.0"
+edition.workspace = true
+rust-version.workspace = true
+authors = ["Abdelkader Boudih <oss@seuros.com>"]
+license = "MIT"
+description = "Monotonic deadline arithmetic and cooperative cancellation trees - no_std, zero dependencies"
+repository = "https://github.com/seuros/deadline_machines"
+keywords = ["deadline", "timeout", "cancellation", "resilience", "no-std"]
+categories = ["no-std", "concurrency"]
+readme = "README.md"
+
+[lib]
+name = "deadline_machines"
+crate-type = ["lib"]
+
+[features]
+default = ["std"]
+std = ["alloc"]
+alloc = []
+
+[lints]
+workspace = true

data/ext/deadline_machines_native/core/src/lib.rs

@@ -0,0 +1,331 @@
+#![cfg_attr(not(feature = "std"), no_std)]
+
+#[cfg(feature = "alloc")]
+extern crate alloc;
+
+/// Compiles and runs the README's examples as doctests.
+#[cfg(doctest)]
+#[doc = include_str!("../README.md")]
+struct ReadmeDoctests;
+
+pub const NS_PER_SECOND: u64 = 1_000_000_000;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub struct Instant(pub u64);
+
+pub trait Clock {
+    fn now_ns(&self) -> u64;
+
+    fn now(&self) -> Instant {
+        Instant(self.now_ns())
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct Deadline {
+    expires_at: Option<Instant>,
+}
+
+impl Deadline {
+    #[must_use]
+    pub const fn never() -> Self {
+        Self { expires_at: None }
+    }
+
+    #[must_use]
+    pub const fn at(instant: Instant) -> Self {
+        Self {
+            expires_at: Some(instant),
+        }
+    }
+
+    #[must_use]
+    pub const fn after(now: Instant, timeout_ns: u64) -> Self {
+        Self::at(Instant(now.0.saturating_add(timeout_ns)))
+    }
+
+    #[must_use]
+    pub const fn expires_at(&self) -> Option<Instant> {
+        self.expires_at
+    }
+
+    #[must_use]
+    pub const fn remaining_ns(&self, now: Instant) -> Option<u64> {
+        match self.expires_at {
+            Some(expiry) => Some(expiry.0.saturating_sub(now.0)),
+            None => None,
+        }
+    }
+
+    #[must_use]
+    pub const fn is_expired(&self, now: Instant) -> bool {
+        matches!(self.remaining_ns(now), Some(0))
+    }
+
+    #[must_use]
+    pub const fn derive(&self, now: Instant, timeout_ns: u64) -> Self {
+        let candidate = Instant(now.0.saturating_add(timeout_ns));
+        match self.expires_at {
+            None => Self::at(candidate),
+            Some(parent) if candidate.0 < parent.0 => Self::at(candidate),
+            Some(parent) => Self::at(parent),
+        }
+    }
+
+    #[must_use]
+    pub const fn tighten(&self, other: Self) -> Self {
+        match (self.expires_at, other.expires_at) {
+            (None, any) | (any, None) => Self { expires_at: any },
+            (Some(a), Some(b)) if a.0 < b.0 => Self::at(a),
+            (Some(_), Some(b)) => Self::at(b),
+        }
+    }
+
+    #[must_use]
+    pub const fn clamp_sleep_ns(&self, now: Instant, requested_ns: u64) -> u64 {
+        match self.remaining_ns(now) {
+            Some(left) if left < requested_ns => left,
+            _ => requested_ns,
+        }
+    }
+}
+
+#[cfg(feature = "alloc")]
+pub mod cancel {
+    use alloc::sync::Arc;
+    use core::sync::atomic::{AtomicBool, Ordering};
+
+    #[derive(Debug)]
+    struct Node {
+        cancelled: AtomicBool,
+        parent: Option<Arc<Self>>,
+    }
+
+    impl Node {
+        fn is_cancelled(&self) -> bool {
+            self.cancelled.load(Ordering::Acquire)
+                || self
+                    .parent
+                    .as_ref()
+                    .is_some_and(|parent| parent.is_cancelled())
+        }
+    }
+
+    #[derive(Debug, Clone)]
+    pub struct CancelToken {
+        node: Arc<Node>,
+    }
+
+    impl CancelToken {
+        #[must_use]
+        pub fn root() -> Self {
+            Self {
+                node: Arc::new(Node {
+                    cancelled: AtomicBool::new(false),
+                    parent: None,
+                }),
+            }
+        }
+
+        #[must_use]
+        pub fn child(&self) -> Self {
+            Self {
+                node: Arc::new(Node {
+                    cancelled: AtomicBool::new(false),
+                    parent: Some(Arc::clone(&self.node)),
+                }),
+            }
+        }
+
+        pub fn cancel(&self) {
+            self.node.cancelled.store(true, Ordering::Release);
+        }
+
+        #[must_use]
+        pub fn is_cancelled(&self) -> bool {
+            self.node.is_cancelled()
+        }
+    }
+
+    impl Default for CancelToken {
+        fn default() -> Self {
+            Self::root()
+        }
+    }
+}
+
+/// Why a [`Scope`] stopped admitting work.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Stopped {
+    /// The budget ran out.
+    Exceeded,
+    /// Someone upstream gave up.
+    Cancelled,
+}
+
+impl core::fmt::Display for Stopped {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        f.write_str(match self {
+            Self::Exceeded => "deadline exceeded",
+            Self::Cancelled => "deadline cancelled",
+        })
+    }
+}
+
+impl core::error::Error for Stopped {}
+
+#[cfg(feature = "alloc")]
+mod scope {
+    use super::{Deadline, Instant, Stopped, cancel::CancelToken};
+
+    /// A budget and a cancellation handle as one value, which is what a retry
+    /// policy or a circuit breaker actually needs to consult.
+    ///
+    /// ```
+    /// use deadline_machines::{Deadline, Instant, Scope, Stopped};
+    ///
+    /// let now = Instant(0);
+    /// let request = Scope::new(Deadline::after(now, 5_000));
+    ///
+    /// let attempt = request.derive(now, 9_000);
+    /// assert_eq!(attempt.deadline(), request.deadline());
+    ///
+    /// request.cancel();
+    /// assert_eq!(attempt.check(now), Err(Stopped::Cancelled));
+    /// ```
+    #[derive(Debug, Clone)]
+    pub struct Scope {
+        deadline: Deadline,
+        token: CancelToken,
+    }
+
+    impl Scope {
+        #[must_use]
+        pub fn new(deadline: Deadline) -> Self {
+            Self {
+                deadline,
+                token: CancelToken::root(),
+            }
+        }
+
+        /// A scope with no time limit, cancellable only.
+        #[must_use]
+        pub fn never() -> Self {
+            Self::new(Deadline::never())
+        }
+
+        #[must_use]
+        pub const fn deadline(&self) -> Deadline {
+            self.deadline
+        }
+
+        #[must_use]
+        pub const fn remaining_ns(&self, now: Instant) -> Option<u64> {
+            self.deadline.remaining_ns(now)
+        }
+
+        #[must_use]
+        pub fn is_cancelled(&self) -> bool {
+            self.token.is_cancelled()
+        }
+
+        #[must_use]
+        pub const fn is_expired(&self, now: Instant) -> bool {
+            self.deadline.is_expired(now)
+        }
+
+        #[must_use]
+        pub fn is_done(&self, now: Instant) -> bool {
+            self.is_cancelled() || self.is_expired(now)
+        }
+
+        /// Cancellation reaches every scope derived from this one, now or later.
+        pub fn cancel(&self) {
+            self.token.cancel();
+        }
+
+        /// The cooperative checkpoint.
+        ///
+        /// # Errors
+        ///
+        /// [`Stopped::Cancelled`] when this scope or an ancestor was cancelled,
+        /// which outranks [`Stopped::Exceeded`] for a spent budget. Matches the
+        /// precedence on the Ruby side.
+        pub fn check(&self, now: Instant) -> Result<(), Stopped> {
+            if self.is_cancelled() {
+                return Err(Stopped::Cancelled);
+            }
+            if self.is_expired(now) {
+                return Err(Stopped::Exceeded);
+            }
+            Ok(())
+        }
+
+        /// A child scope whose deadline is the tighter of this one and
+        /// `timeout_ns` from `now`.
+        #[must_use]
+        pub fn derive(&self, now: Instant, timeout_ns: u64) -> Self {
+            Self {
+                deadline: self.deadline.derive(now, timeout_ns),
+                token: self.token.child(),
+            }
+        }
+
+        /// A child scope with the same deadline, cancellable on its own.
+        #[must_use]
+        pub fn child(&self) -> Self {
+            Self {
+                deadline: self.deadline,
+                token: self.token.child(),
+            }
+        }
+
+        /// The longest sleep that still fits the budget. A retry policy calls
+        /// this before each backoff so it cannot outlive its caller.
+        #[must_use]
+        pub const fn clamp_sleep_ns(&self, now: Instant, requested_ns: u64) -> u64 {
+            self.deadline.clamp_sleep_ns(now, requested_ns)
+        }
+    }
+}
+
+#[cfg(feature = "alloc")]
+pub use scope::Scope;
+
+#[cfg(feature = "std")]
+mod system_clock {
+    use super::Clock;
+    use std::time::Instant as StdInstant;
+
+    #[derive(Debug, Clone, Copy)]
+    pub struct SystemClock {
+        origin: StdInstant,
+    }
+
+    impl SystemClock {
+        #[must_use]
+        pub fn new() -> Self {
+            Self {
+                origin: StdInstant::now(),
+            }
+        }
+    }
+
+    impl Default for SystemClock {
+        fn default() -> Self {
+            Self::new()
+        }
+    }
+
+    impl Clock for SystemClock {
+        fn now_ns(&self) -> u64 {
+            u64::try_from(self.origin.elapsed().as_nanos()).unwrap_or(u64::MAX)
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+pub use system_clock::SystemClock;
+
+#[cfg(test)]
+mod tests;

data/lib/deadline_machines/clock.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DeadlineMachines
+  module MonotonicClock
+    def self.now_ns
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+    end
+  end
+
+  class TestClock
+    attr_accessor :now_ns
+
+    def initialize(now_ns: 0)
+      @now_ns = now_ns
+    end
+
+    def advance(seconds)
+      @now_ns += (seconds.to_r * 1_000_000_000).round
+      self
+    end
+  end
+end

data/lib/deadline_machines/deadline.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module DeadlineMachines
+  class Deadline
+    NS_PER_SECOND = 1_000_000_000
+
+    attr_reader :expires_at_ns, :parent, :clock, :reason
+
+    class << self
+      def after(seconds, clock: DeadlineMachines.clock)
+        new(expires_at_ns: clock.now_ns + to_ns(seconds), clock: clock)
+      end
+
+      def never(clock: DeadlineMachines.clock)
+        new(expires_at_ns: nil, clock: clock)
+      end
+
+      def to_ns(seconds)
+        (seconds.to_r * NS_PER_SECOND).round
+      end
+    end
+
+    def initialize(expires_at_ns:, clock:, parent: nil)
+      @expires_at_ns = expires_at_ns
+      @clock = clock
+      @parent = parent
+      @cancelled = false
+      @detached = false
+      @reason = nil
+      @children = ObjectSpace::WeakMap.new
+      @retained = {}
+      @callbacks = []
+      @mutex = parent ? parent.mutex : Mutex.new
+    end
+
+    def remaining_ns
+      return nil unless @expires_at_ns
+
+      left = @expires_at_ns - @clock.now_ns
+      left.negative? ? 0 : left
+    end
+
+    def remaining
+      ns = remaining_ns
+      ns ? ns / NS_PER_SECOND.to_f : Float::INFINITY
+    end
+
+    def expired?
+      remaining_ns == 0
+    end
+
+    def cancelled?
+      @cancelled || !!@parent&.cancelled?
+    end
+
+    def done?
+      cancelled? || expired?
+    end
+
+    def check!
+      raise Cancelled.new(self, cancel_reason) if cancelled?
+      raise Exceeded, self if expired?
+
+      self
+    end
+
+    def clamp_sleep(seconds)
+      left = remaining
+      seconds < left ? seconds : left
+    end
+
+    def cancel(reason = nil)
+      callbacks, children = @mutex.synchronize do
+        return self if @cancelled
+
+        @cancelled = true
+        @reason = reason
+        @parent&.drop(self)
+        [@callbacks.dup, @children.keys]
+      end
+
+      failures = []
+      children.each { |child| notify(failures) { child.cancel(reason) } }
+      callbacks.each { |callback| notify(failures) { callback.call(self) } }
+      raise failures.first unless failures.empty?
+
+      self
+    end
+
+    def on_cancel(&block)
+      already = @mutex.synchronize do
+        settled = cancelled?
+        unless settled
+          @callbacks << block
+          @parent&.hold(self) unless @detached
+        end
+        settled
+      end
+
+      block.call(self) if already
+      self
+    end
+
+    def derive(seconds = nil)
+      child = self.class.new(expires_at_ns: child_expiry_ns(seconds), clock: @clock, parent: self)
+      @mutex.synchronize { @children[child] = true }
+      return child unless block_given?
+
+      begin
+        yield child
+      ensure
+        @mutex.synchronize { detach(child) }
+      end
+    end
+
+    def inspect
+      state = cancelled? ? 'cancelled' : (expired? ? 'expired' : format('%.3fs left', remaining))
+      "#<#{self.class} #{state}>"
+    end
+
+    protected
+
+    attr_reader :mutex
+    attr_writer :detached
+
+    # A derived deadline is the caller's to keep, so the parent follows it
+    # weakly. Something to deliver is the exception, and it has to be held all
+    # the way to the root: an intermediate deadline nobody else references is
+    # the one link whose collection would strand the delivery below it.
+    #
+    # Holding and dropping walk the chain, so they cannot be made atomic out of
+    # one lock per link: every deadline in a tree shares the root's lock, and
+    # both run inside a section the caller already holds.
+    def hold(child)
+      @retained[child] = true
+      @parent.hold(self) if @parent && !@detached
+    end
+
+    def drop(child)
+      @retained.delete(child)
+      @parent.drop(self) if @parent && !pending?
+    end
+
+    # A scope that has ended owns its child outright: the tree will not reach
+    # it again, so the parent holds nothing for it and an observer registered
+    # afterwards is the caller's own to keep alive.
+    def detach(child)
+      @children.delete(child)
+      child.detached = true
+      drop(child)
+    end
+
+    # Whether anything is still owed through this deadline.
+    def pending?
+      !@cancelled && !(@callbacks.empty? && @retained.empty?)
+    end
+
+    private
+
+    # Every observer and descendant is told, then the first failure is raised.
+    # One raising observer must not silence its peers.
+    def notify(failures)
+      yield
+    rescue StandardError => e
+      failures << e
+    end
+
+    protected
+
+    def cancel_reason
+      @reason || @parent&.cancel_reason
+    end
+
+    private
+
+    def child_expiry_ns(seconds)
+      return @expires_at_ns unless seconds
+
+      candidate = @clock.now_ns + self.class.to_ns(seconds)
+      @expires_at_ns ? [candidate, @expires_at_ns].min : candidate
+    end
+  end
+end

data/lib/deadline_machines/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module DeadlineMachines
+  class Error < StandardError; end
+
+  class Exceeded < Error
+    attr_reader :deadline
+
+    def initialize(deadline)
+      @deadline = deadline
+      super('deadline exceeded')
+    end
+  end
+
+  class Cancelled < Error
+    attr_reader :deadline, :reason
+
+    def initialize(deadline, reason = nil)
+      @deadline = deadline
+      @reason = reason
+      super(reason ? "deadline cancelled: #{reason}" : 'deadline cancelled')
+    end
+  end
+end

data/lib/deadline_machines/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DeadlineMachines
+  VERSION = '0.1.1'
+end

data/lib/deadline_machines.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'deadline_machines/version'
+require_relative 'deadline_machines/errors'
+require_relative 'deadline_machines/clock'
+require_relative 'deadline_machines/deadline'
+
+module DeadlineMachines
+  FIBER_KEY = :deadline_machines_deadline
+
+  class << self
+    attr_writer :clock
+
+    def clock
+      @clock ||= MonotonicClock
+    end
+
+    def current
+      Fiber[FIBER_KEY]
+    end
+
+    def with_deadline(seconds = nil, &block)
+      ambient = current
+      return ambient.derive(seconds) { |child| bind(child, &block) } if ambient
+      return bind(Deadline.after(seconds, clock: clock), &block) if seconds
+
+      bind(Deadline.never(clock: clock), &block)
+    end
+
+    def bind(deadline)
+      previous = Fiber[FIBER_KEY]
+      Fiber[FIBER_KEY] = deadline
+      begin
+        yield deadline
+      ensure
+        Fiber[FIBER_KEY] = previous
+      end
+    end
+
+    def check!
+      current&.check!
+    end
+
+    def remaining
+      current&.remaining || Float::INFINITY
+    end
+
+    def clamp_sleep(seconds)
+      current ? current.clamp_sleep(seconds) : seconds
+    end
+
+    def deadline?(object)
+      object.respond_to?(:remaining) && object.respond_to?(:done?) && object.respond_to?(:check!)
+    end
+  end
+end

data/sig/deadline_machines.rbs

@@ -0,0 +1,78 @@
+module DeadlineMachines
+  VERSION: String
+  FIBER_KEY: Symbol
+
+  # Any monotonic nanosecond time source.
+  interface _Clock
+    def now_ns: () -> Integer
+  end
+
+  class Error < StandardError
+  end
+
+  class Exceeded < Error
+    attr_reader deadline: Deadline
+    def initialize: (Deadline) -> void
+  end
+
+  class Cancelled < Error
+    attr_reader deadline: Deadline
+    attr_reader reason: untyped
+    def initialize: (Deadline, ?untyped) -> void
+  end
+
+  module MonotonicClock
+    def self.now_ns: () -> Integer
+  end
+
+  class TestClock
+    attr_accessor now_ns: Integer
+    def initialize: (?now_ns: Integer) -> void
+    def advance: (Numeric) -> self
+  end
+
+  class Deadline
+    NS_PER_SECOND: Integer
+
+    attr_reader expires_at_ns: Integer?
+    attr_reader parent: Deadline?
+    attr_reader clock: _Clock
+    attr_reader reason: untyped
+
+    def self.after: (Numeric, ?clock: _Clock) -> Deadline
+    def self.never: (?clock: _Clock) -> Deadline
+    def self.to_ns: (Numeric) -> Integer
+
+    def initialize: (expires_at_ns: Integer?, clock: _Clock, ?parent: Deadline?) -> void
+
+    # nil when there is no time limit.
+    def remaining_ns: () -> Integer?
+    def remaining: () -> Float
+    def expired?: () -> bool
+    def cancelled?: () -> bool
+    def done?: () -> bool
+    def check!: () -> self
+    def clamp_sleep: (Numeric) -> Numeric
+    def cancel: (?untyped) -> self
+    def on_cancel: () { (Deadline) -> void } -> self
+
+    # Without a block the child is returned; with one it is unlinked on exit
+    # and the block's value is returned.
+    def derive: (?Numeric?) -> Deadline
+              | [T] (?Numeric?) { (Deadline) -> T } -> T
+
+    def inspect: () -> String
+
+    private def child_expiry_ns: (Numeric?) -> Integer?
+  end
+
+  def self.clock: () -> _Clock
+  def self.clock=: (_Clock?) -> _Clock?
+  def self.current: () -> Deadline?
+  def self.with_deadline: [T] (?Numeric?) { (Deadline) -> T } -> T
+  def self.bind: [T] (Deadline) { (Deadline) -> T } -> T
+  def self.check!: () -> Deadline?
+  def self.remaining: () -> Float
+  def self.clamp_sleep: (Numeric) -> Numeric
+  def self.deadline?: (untyped) -> bool
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: deadline_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Abdelkader Boudih
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'A monotonic deadline token that derives child budgets, cancels down
+  its tree, and raises only at checkpoints you choose. The shared time contract for
+  the machines family: retries, circuit breakers and throttles read one budget instead
+  of each keeping its own clock.'
+email:
+- oss@seuros.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.toml
+- LICENSE.txt
+- README.md
+- ext/deadline_machines_native/core/Cargo.toml
+- ext/deadline_machines_native/core/src/lib.rs
+- lib/deadline_machines.rb
+- lib/deadline_machines/clock.rb
+- lib/deadline_machines/deadline.rb
+- lib/deadline_machines/errors.rb
+- lib/deadline_machines/version.rb
+- sig/deadline_machines.rbs
+homepage: https://github.com/seuros/deadline_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/deadline_machines
+  changelog_uri: https://github.com/seuros/deadline_machines/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/seuros/deadline_machines/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Deadline propagation and cooperative cancellation for Ruby
+test_files: []