farce 0.4.1 → 0.5.0

data/lib/farce/abstract/publisher.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Shared superclass for all publisher implementations.
+    #
+    # Implements a publisher-subscriber (pub-sub) pattern.
+    # @see Farce::Publisher
+    class Publisher
+      include Internal::Freeze::Unfreezable
+      include Internal::Noncopyable
+
+      # @param subscribers [Array]
+      #   the initial subscribers to add to the publisher, see {#subscribe}
+      def initialize(*subscribers)
+        @closed = Farce::Flag.new
+        super()
+        subscribers.each { subscribe(it) }
+      end
+
+      # @return [Boolean] whether the publisher is closed.
+      def closed? = @closed.value
+
+      # Publishes the given payload to all current subscribers.
+      #
+      # Full bounded queues drop new messages.
+      # Failed publishing attempts to closed or frozen receivers cancel their subscriptions.
+      #
+      # @param payload [BasicObject] the payload to publish
+      # @return [self] the publisher itself
+      def publish(payload = nil)
+        raise "Cannot publish to a closed publisher" if closed?
+        map.each_value { it.publish(payload) }
+        self
+      end
+      alias send      publish
+      alias <<        publish
+      alias broadcast publish
+
+      # @overload subscribe(subscriber)
+      #   Adds a subscriber to the publisher.
+      #   Register additional subscriber classes with {Subscription.define}.
+      #   Publisher subscribers forward messages synchronously to their own subscribers.
+      #   Avoid subscribing publishers in a cycle.
+      #
+      #   @example Forward messages to another publisher
+      #     upstream.subscribe(downstream)
+      #     upstream.publish(:message) # also publishes to downstream's subscribers
+      #
+      #   @param subscriber [BasicObject]
+      #     The subscriber to add.
+      #     Standard-library queues are supported by unshared and local publishers and retain the original payload.
+      #     A full `Thread::SizedQueue` drops new messages. Publishing to a closed queue cancels its subscription.
+      #
+      #     Calls one of the following methods:
+      #     * {Ractor#send}
+      #     * {Ractor::Port#send}
+      #     * {Queue#try_push}
+      #     * `Thread::Queue#push`
+      #     * `Thread::SizedQueue#push` (nonblocking)
+      #     * {Counter#increment} (without arguments)
+      #     * {Flag#set}
+      #     * {Atom#value=}
+      #     * {Set#<<}
+      #     * {Vector#<<}
+      #     * {Signal#broadcast} (without arguments)
+      #     * {Publisher#publish}
+      #     * {Farce::Concurrent::Event#set} (without arguments)
+      #     * {Farce::Concurrent::CountDownLatch#count_down} (without arguments)
+      #     * `Proc#call`
+      #
+      #     The concurrent-ruby integration supports these subscribers with unshared and local publishers:
+      #     * `Concurrent::AtomicReference#value=`
+      #     * `Concurrent::AtomicFixnum#increment` (without arguments)
+      #     * `Concurrent::AtomicBoolean#make_true`
+      #     * `Concurrent::Event#set` (without arguments)
+      #     * `Concurrent::CountDownLatch#count_down` (without arguments)
+      #
+      #     Set the default `mode`, `auto_local`, `capacity`, and similar options via initializers for these classes
+      #     to influence how data transfer is handled.
+      #
+      #     Support for additional subscribers can be added via {Subscription.define}.
+      #
+      # @overload subscribe(*args, mode: nil, scheduler: nil, capacity: nil)
+      #   Adds a subscription callback.
+      #   Messages run in order on the selected scheduler. A full queue drops new messages.
+      #   Unsubscribing drains queued messages and stops the callback.
+      #
+      #   @example
+      #     counter = Farce::Counter.new
+      #
+      #     publisher.subscribe(counter) do |counter, payload|
+      #       counter.increment
+      #       puts "Message ##{counter}: #{payload.inspect}"
+      #     end
+      #
+      #   @param args [Array] additional arguments to pass to the subscriber
+      #   @param mode [Symbol, nil] The transfer mode to use
+      #   @param scheduler [#schedule, nil] The scheduler to use for running the block
+      #   @param capacity [Integer, nil] the maximum queued messages, or nil for an unbounded queue
+      #   @yield [*args, payload] the block to be called with the given arguments and payload
+      #   @yieldparam args [Array] the additional arguments passed to the block
+      #   @yieldparam payload [Object] the payload sent via {#publish}
+      #
+      # @return [Subscription] the created subscription
+      def subscribe(...) = block_given? ? create_subscription(...) : add_subscription(...)
+      alias monitor subscribe
+
+      # @param subscriber [BasicObject] the subscriber to retrieve the subscription for
+      # @return [Subscription, nil] the subscription for the given subscriber, or nil if none exists.
+      def subscription_for(subscriber)
+        if subscriber.is_a?(Subscription)
+          return unless subscriber.publisher.equal?(self)
+          subscription = map[subscriber.key]
+          subscription if subscription.equal?(subscriber)
+        else
+          map[subscriber.__id__]
+        end
+      end
+
+      # @return [Boolean] whether the given subscriber is currently subscribed.
+      def subscribed?(subscriber) = !!subscription_for(subscriber)&.subscribed?
+
+      # Unsubscribes the given subscriber from the publisher.
+      # @param subscriber [BasicObject] the subscriber to unsubscribe
+      # @return [void]
+      def unsubscribe(subscriber) = subscription_for(subscriber)&.unsubscribe
+      alias cancel    unsubscribe
+      alias unmonitor unsubscribe
+
+      private
+
+      def default_mode = :smart
+      def map          = raise NoMethodError, "Subclasses must implement the private `map` method"
+
+      def add_subscription(subscriber)
+        if subscriber.is_a?(Subscription)
+          existing = subscription_for(subscriber)
+          return existing if existing
+          subscriber = subscriber.subscriber
+        end
+        return create_subscription(source: subscriber, &subscriber) if subscriber.is_a?(Proc)
+
+        map = self.map
+        map.store_if_absent(subscriber.__id__) { build_subscription(subscriber, map) }
+      end
+
+      def create_subscription(*, capacity: nil, mode: nil, scheduler: nil, source: nil, &callback)
+        mode      ||= default_mode
+        callback    = Ractor.shareable_proc(&callback) unless mode == :local || Ractor.shareable?(callback)
+        scheduler ||= Farce
+        queue       = Farce::Queue.new(capacity:, mode:)
+        map         = self.map
+        created     = false
+        subscription = map.store_if_absent((source || queue).__id__) do
+          created = true
+          build_subscription(queue, map, callback: true, source:)
+        end
+        return subscription unless created
+
+        scheduler.schedule(queue, callback, subscription, *, mode:) do |queue, callback, subscription, *args|
+          loop do
+            begin
+              payload = queue.pop
+            rescue ClosedQueueError
+              break
+            end
+            callback.call(*args, payload)
+          end
+        ensure
+          subscription.unsubscribe
+          queue.close
+        end
+
+        scheduled = true
+        subscription
+      ensure
+        unless scheduled
+          subscription&.unsubscribe if created
+          queue&.close
+        end
+      end
+
+      def build_subscription(...) = Subscription.build(self, ...)
+    end
+  end
+end

data/lib/farce/abstract/queue.rb

@@ -11,8 +11,11 @@ module Farce
     #
     # Queues have a blocking and non-blocking interface.
     #
-    # @!attribute [r] capacity
-    #   @abstract
+    # @!attribute [rw] capacity
+    #   Assign a positive limit, or `nil` for an unbounded queue.
+    #   Changes preserve queued values. Local queues change only the current scope.
+    #   On JRuby and TruffleRuby, normal FIFO queues retain their initial bounded or unbounded choice.
+    #   Switching between these states may raise `ArgumentError`. Priority and timer queues support both.
     #   @return [Integer, nil] The maximum number of items the queue can hold.
     #
     # @!attribute [r] num_waiting
@@ -173,10 +176,33 @@ module Farce
 
       # Whether the queue is at capacity.
       # @return [Boolean] `true` if the queue is at capacity, `false` otherwise.
-      def full? = capacity && size >= capacity
+      def full?
+        limit = capacity
+        limit && size >= limit
+      end
 
       def capacity = internal_queue.capacity
 
+      # Change the limit without discarding queued values. Returns immediately.
+      #
+      # New pushes wait while the queue is at or above the new limit.
+      # Increasing or removing the limit wakes blocked producers.
+      #
+      # Local queues change only the current scope. New scopes retain the constructor limit.
+      #
+      # Priority and timer queues support bounded and unbounded transitions on every engine.
+      #
+      # FIFO queues on JRuby and TruffleRuby retain their initial bounded or unbounded choice.
+      #
+      # @param value [Integer, nil] the positive capacity, or `nil` to remove the limit
+      # @return [Integer, nil] the new capacity
+      # @raise [ArgumentError] if the capacity is not positive
+      # @raise [ArgumentError] on JRuby and TruffleRuby, normal FIFO queues may reject transitions
+      #   between bounded and unbounded states
+      def capacity=(value)
+        internal_queue.capacity = value.nil? ? nil : Integer(value)
+      end
+
       def clear
         internal_queue.clear
         self

data/lib/farce/abstract/scheduler.rb

@@ -169,6 +169,15 @@ module Farce
         super()
       end
 
+      # Pending-task capacity. Nil means the queue is unbounded.
+      def capacity = @queue.capacity
+
+      # Resize the pending queue without discarding tasks.
+      # JRuby and TruffleRuby cannot switch between bounded and unbounded queues.
+      def capacity=(value)
+        @queue.capacity = value.nil? ? nil : Integer(value)
+      end
+
       # @return [Exception, nil] The error encountered by the scheduler, if any.
       def error
         value = @error.value
@@ -305,7 +314,10 @@ module Farce
       # Otherwise, the block must be convertible to a Ractor-shareable proc.
       # Pass task data as arguments so the selected transfer mode can be applied to it.
       #
-      # @overload schedule(*args, mode: :smart, auto_local: true)
+      # A `timeout` limits the combined wait for ownership and queue space.
+      # Expiry returns `nil` without enqueuing the task. Accepted tasks have no execution timeout.
+      #
+      # @overload schedule(*args, mode: :smart, auto_local: true, timeout: nil)
       #   @!macro modes
       #
       #   @param args [Array<Object>] Positional arguments passed to the task block.
@@ -313,8 +325,9 @@ module Farce
       #     Argument transfer mode from {Farce::MODES}, including `:copy`, `:marshal`, and `:local`.
       #     See {ModeManager#wrap}.
       #   @param auto_local [Boolean] Whether to override mode with `:local` in the owning Ractor.
+      #   @param timeout [Numeric, nil] Maximum scheduling wait in seconds. Nil waits indefinitely, zero polls.
       #   @yield [*args] The task to execute.
-      #   @return [Scheduler] self.
+      #   @return [self, nil] self when submitted, or nil when the scheduling timeout expires.
       #   @raise [SchedulerClosedError] If the handle is closing, closed, or in an error state.
       #   @see Ractor.shareable_proc
       def schedule(...) = enqueue_task(false, ...)
@@ -324,9 +337,13 @@ module Farce
       # it still waits for ownership to be assigned.
       #
       # @overload try_schedule(*args, mode: :smart, auto_local: true)
-      #   @param (see Farce::Abstract::Executor#schedule)
+      #   @param args (see Farce::Abstract::Executor#schedule)
+      #   @param mode (see Farce::Abstract::Executor#schedule)
+      #   @param auto_local (see Farce::Abstract::Executor#schedule)
       #   @return [self, nil] self when submitted, or nil when the queue is full.
-      def try_schedule(...) = enqueue_task(true, ...)
+      def try_schedule(*, mode: :smart, auto_local: true, &)
+        enqueue_task(true, *, mode:, auto_local:, &)
+      end
 
       # (see Farce::Abstract::Executor#local?)
       def local?(wait: true)
@@ -418,13 +435,15 @@ module Farce
 
       private
 
-      def enqueue_task(non_block, *args, mode: :smart, auto_local: true, &block)
+      def enqueue_task(non_block, *args, mode: :smart, auto_local: true, timeout: nil, &block)
         raise SchedulerClosedError, "cannot schedule task on a closed scheduler" if closed?
 
         raise LocalJumpError, "Cannot schedule without a block" unless block
 
-        task = prepare_task(args, block, mode, auto_local)
-        return unless non_block ? @queue.try_push(task) : @queue.push(task)
+        deadline = scheduling_deadline(timeout)
+        task     = prepare_task(args, block, mode, auto_local, timeout: Clock.remaining(deadline))
+        return unless task
+        return unless non_block ? @queue.try_push(task) : @queue.push(task, timeout: Clock.remaining(deadline))
         self
       rescue ClosedQueueError
         raise unless closed?
@@ -433,10 +452,11 @@ module Farce
 
       def new_queue(capacity:) = Internal::Queue.new(capacity:)
 
-      def prepare_task(args, block, mode, auto_local)
+      def prepare_task(args, block, mode, auto_local, timeout: nil)
         if auto_local
-          owner = @owner.wait_until_non_nil
+          owner = @owner.wait_until_non_nil(timeout:)
           raise SchedulerClosedError, "cannot schedule task on a closed scheduler" if closed?
+          return unless owner
           mode = :local if owner == Ractor.current
         elsif mode == :local && (owner = @owner.value) && owner != Ractor.current
           raise Ractor::IsolationError, "cannot schedule local task outside the owning Ractor"
@@ -493,18 +513,25 @@ module Farce
         failure = nil
         @state.compare_and_set(:setup, :running)
         while keep_processing?
-          break if @pool_worker && !@pool_worker.wait_for_admission(scheduler, runnable_count)
+          if @pool_worker
+            settings = @pool_worker.settings
+            settings = @pool_worker.wait_for_admission(scheduler, runnable_count, settings)
+            break unless settings
+          end
           timed_out = false
-          timeout = @pool_worker&.idle_timeout
-          task = @queue.pop(timeout:) { timed_out = true }
+          task = if @pool_worker
+                   @queue.pop_interruptible(settings, settings.shrink_after) { timed_out = true }
+                 else
+                   @queue.pop { timed_out = true }
+                 end
           if timed_out
-            break if @pool_worker&.retire?
+            break if @pool_worker&.retire?(expected: settings)
             next
           end
           next unless task
           task = task.value if task.is_a?(Envelope)
           if task
-            @pool_worker&.task_started
+            @pool_worker&.task_started(settings)
             yield task
           end
         end

data/lib/farce/abstract/timer_queue.rb

@@ -156,18 +156,18 @@ module Farce
           timestamp = internal_queue.peek_priority
           wake_after = nil
           if timestamp
-            delay = timestamp - Clock.now
+            delay = Clock.remaining(timestamp)
             return timestamp unless delay.positive?
             wake_after = delay if delay.finite?
           end
 
-          remaining = remaining_timeout(deadline)
+          remaining = Clock.remaining(deadline)
 
           wait_for = wake_after && remaining ?
             (wake_after < remaining ? wake_after : remaining) :
             wake_after || remaining
           changed = internal_signal.wait(generation, timeout: wait_for)
-          return UNDEFINED if !changed && deadline && remaining_timeout(deadline).zero?
+          return UNDEFINED if !changed && deadline && Clock.remaining(deadline).zero?
         end
       end
     end

data/lib/farce/abstract/vector.rb

@@ -1290,7 +1290,7 @@ module Farce
       # @param timeout [Numeric, nil] the total seconds available
       # @return [BasicObject, nil] the matching value, or nil on timeout
       # @raise [LocalJumpError] if no block is given
-      def wait_until(index, timeout: nil, &) = Internal.wait_until(self, index, timeout:, &)
+      def wait_until(index, timeout: nil, &) = Internal.wait_until(internal_vector, index, timeout:, &)
 
       # Wait while the block returns a truthy value.
       # @yieldparam value [BasicObject, nil] the current value
@@ -1390,6 +1390,8 @@ module Farce
 
       private
 
+      def normalize_vector_source(source) = source.is_a?(Integer) ? Array.new(source) : source
+
       def mutate_vector(timeout: nil)
         result = nil
         completed = internal_vector.batch_update(timeout:) { |values| result = yield values }

data/lib/farce/atom.rb

@@ -217,6 +217,13 @@ module Farce
       unwrap_value(result)
     end
 
+    # (see Abstract::Atom#wait_until)
+    def wait_until(timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      result = Internal.wait_until(@atom, timeout:) { |current| yield(unwrap_value(current)) }
+      unwrap_value(result)
+    end
+
     # Wait until the current value no longer matches an expected value.
     # @param expected [BasicObject, nil] the value to compare with the current value
     # @param timeout [Numeric, nil] the maximum number of seconds to wait
@@ -227,11 +234,11 @@ module Farce
       deadline = Internal.timeout_deadline(timeout)
 
       while true
-        current = @atom.get(timeout: Internal.remaining_timeout(deadline)) { TIMED_OUT }
+        current = @atom.get(timeout: Clock.remaining(deadline)) { TIMED_OUT }
         return unwrap_result(current, &) if TIMED_OUT.equal?(current)
         return unwrap_value(current) unless values_equal?(current, expected)
 
-        result = @atom.wait_until_changed(current, timeout: Internal.remaining_timeout(deadline)) { TIMED_OUT }
+        result = @atom.wait_until_changed(current, timeout: Clock.remaining(deadline)) { TIMED_OUT }
         return unwrap_result(result, &) if TIMED_OUT.equal?(result)
       end
     end

data/lib/farce/clock.rb

@@ -31,6 +31,18 @@ module Farce
     # @return [Float] the clock time in seconds
     def current = Process.clock_gettime(CLOCK_MONOTONIC) - MONOTONIC
 
+    # Returns the seconds left until a monotonic clock deadline.
+    # Expired deadlines return zero. Nil means there is no deadline and returns nil.
+    #
+    # @param deadline [Numeric, nil] a deadline from {#clock} or {#timeout}
+    # @raise [ArgumentError] if the deadline is NaN
+    # @return [Float, Integer, nil] the remaining seconds, zero, or nil
+    def remaining(deadline)
+      return if deadline.nil?
+      remaining = validate_timestamp(deadline - now)
+      remaining.positive? ? remaining : 0
+    end
+
     # Converts the given value to a monotonic clock time in seconds.
     #
     # @param value [nil, Numeric, Time, ActiveSupport::Duration, Hash]

data/lib/farce/concurrent/count_down_latch.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Concurrent
+    # A replacement for `concurrent-ruby`'s `CountDownLatch` implementation.
+    # @see https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/CountDownLatch.html
+    class CountDownLatch
+      include Shareable::Delegated
+      include Internal::Noncopyable
+
+      # @param count [Integer] the initial count for the latch.
+      # @raise [ArgumentError] if the count is not a non-negative integer.
+      def initialize(count = 1)
+        raise ArgumentError, "count must be a non-negative integer" unless count.is_a?(Integer) && count >= 0
+        @counter = Counter.new(count)
+        super()
+      end
+
+      # @!attribute [r] count
+      #   @return [Integer] the current count of the latch.
+      def count = @counter.value
+
+      # Decrements the count of the latch by 1 if it is above 0.
+      # @return [void]
+      def count_down = @counter.decrement_if_above(0)
+
+      # Waits until the count reaches 0 or the optional timeout is reached.
+      # @param timeout [Numeric, nil] the maximum time to wait in seconds, or nil to wait indefinitely.
+      # @return [Boolean] true if the count reached 0, false if the timeout was reached.
+      def wait(timeout = nil) = !!@counter.wait_while_above(0, timeout:) # rubocop:disable Naming/PredicateMethod
+
+      private def freeze_backend = @counter
+    end
+  end
+end

data/lib/farce/concurrent/cyclic_barrier.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Concurrent
+    # A replacement for `concurrent-ruby`'s `CyclicBarrier` implementation.
+    # @see https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/CyclicBarrier.html
+    class CyclicBarrier
+      include Shareable::Delegated
+      include Internal::Noncopyable
+
+      # @api private
+      class Generation
+        include Shareable::Delegated
+
+        attr_reader :waiting
+
+        def initialize
+          @waiting = Counter.new
+          @state   = Strict::Atom.new(:waiting)
+          super
+        end
+
+        def wait(timeout)  = @state.wait_until_changed(:waiting, timeout:)
+        def state          = @state.value
+        def number_waiting = state == :waiting ? @waiting.value : 0
+
+        def state=(value)
+          @state.value = value
+        end
+
+        private def freeze_backend = @waiting
+      end
+      private_constant :Generation
+
+      # @return [Integer] the number of parties required to trip the barrier.
+      attr_reader :parties
+
+      # @param parties [Integer] the number of parties required to trip the barrier.
+      # @raise [ArgumentError] if parties is not a positive integer.
+      # @yield
+      #   Optional block to trigger after the last waiter has arrived at the barrier but before they are released.
+      #   Will be made Ractor-shareable. If it raises, the barrier breaks and the exception propagates to its caller.
+      def initialize(parties, &)
+        raise ArgumentError, "parties must be a positive integer" unless parties.is_a?(Integer) && parties.positive?
+        @parties    = parties
+        @action     = block_given? ? Ractor.shareable_proc(&) : nil
+        @generation = Strict::Atom.new(Generation.new)
+        super()
+      end
+
+      # @return [Boolean] whether the barrier is in a broken state.
+      def broken? = generation.state == :broken
+
+      # @return [Integer] the number of parties currently waiting at the barrier.
+      def number_waiting = generation.number_waiting
+
+      # Waits for all parties to reach the barrier. Successful generations can be reused immediately.
+      # A timeout breaks the barrier for all waiters until {#reset} is called.
+      # @param timeout [Numeric, nil] the maximum time to wait for the barrier.
+      # @return [Boolean] true if the barrier was successfully reached, false if it was broken by a timeout or reset.
+      def wait(timeout = nil) # rubocop:disable Naming/PredicateMethod
+        deadline = Internal.timeout_deadline(timeout)
+        waiting  = nil
+        update do |current|
+          waiting = current
+          next current unless current.state == :waiting
+          current.waiting.increment
+          next current if current.waiting.value < @parties
+
+          completed = false
+          begin
+            @action&.call
+            completed = true
+          ensure
+            current.state = completed ? :fulfilled : :broken
+          end
+          Generation.new
+        end
+
+        unless waiting.wait(Clock.remaining(deadline))
+          update do |current|
+            # A trip or reset may have won the race with this waiter's timeout.
+            waiting.state = :broken if waiting.state == :waiting
+            current
+          end
+        end
+        waiting.state == :fulfilled
+      end
+
+      # Breaks the current generation and starts a new one. Existing waiters return false.
+      # @return [nil]
+      def reset
+        update do |current|
+          current.state = :broken
+          Generation.new
+        end
+        nil
+      end
+
+      private
+
+      def freeze_backend = @generation
+      def generation     = @generation.value
+      def update(&)      = @generation.update(&)
+    end
+  end
+end

data/lib/farce/concurrent/event.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Concurrent
+    # A replacement for `concurrent-ruby`'s `Event` implementation.
+    # @see https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Event.html
+    class Event
+      include Shareable::Delegated
+      include Internal::Noncopyable
+
+      def initialize
+        # Odd generations are set. Even generations are reset without forgetting earlier signals.
+        @state = Strict::Atom.new(0)
+        super
+      end
+
+      # @return [Boolean] whether the event is currently set.
+      def set? = @state.value.odd?
+
+      # Sets the event.
+      # @return [true] always returns `true`.
+      def set # rubocop:disable Naming/PredicateMethod
+        try?
+        true
+      end
+
+      # @return [Boolean] `true` if the event was successfully set, `false` otherwise.
+      def try?
+        changed = false
+        @state.update do |current|
+          next current if current.odd?
+          changed = true
+          current + 1
+        end
+        changed
+      end
+
+      # @return [true] always returns `true`.
+      def reset # rubocop:disable Naming/PredicateMethod
+        @state.update { |current| current.odd? ? current + 1 : current }
+        true
+      end
+
+      # Waits for the event to be set or for the specified timeout to elapse.
+      # Resetting the event does not retract a signal already sent to current waiters.
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait, or `nil` to wait indefinitely.
+      # @return [Boolean] `true` if the event was set, `false` if the timeout elapsed.
+      def wait(timeout = nil) # rubocop:disable Naming/PredicateMethod
+        deadline = Internal.timeout_deadline(timeout)
+        observed = @state.value
+        return true if observed.odd?
+        !!@state.wait_until_changed(observed, timeout: Clock.remaining(deadline))
+      end
+
+      private def freeze_backend = @state
+    end
+  end
+end