farce 0 → 0.1.0

data/lib/farce/abstract/priority_queue.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Shared priority ordering and blocking behavior.
+    class PriorityQueue < Queue
+      include Internal::BlockingPriorityQueue
+
+      # @return [BasicObject] the priority used when none is passed to push
+      attr_reader :default_priority
+
+      # @return [:ascending, :descending] the priority order
+      attr_reader :order
+
+      # @param capacity [Integer, nil] the maximum number of values, or nil for
+      #   an unbounded queue
+      # @param default_priority [BasicObject] the priority used when push or
+      #   try_push is called without an explicit priority
+      # @param order [:ascending, :descending] the priority order
+      def initialize(capacity: nil, default_priority: 0, order: :ascending, track_age: false)
+        @order            = normalize_order(order)
+        @default_priority = default_priority
+        super(capacity:, reverse_order: @order == :descending, track_age:)
+      end
+
+      # Return the next value without removing it.
+      # @yield called when the queue is empty
+      # @return [BasicObject, nil] the next value or the fallback result
+      def peek(&) = internal_reverse_order? ? internal_queue.peek_last(&) : internal_queue.peek(&)
+
+      # Remove the oldest value at the lowest or highest priority, depending on {#order}, waiting when empty.
+      def pop(non_block = false, timeout: nil) # rubocop:disable Style/OptionalBooleanParameter
+        return try_pop { raise ThreadError, "queue empty" } if non_block
+        deadline = timeout_at(timeout) unless timeout.nil?
+
+        while true
+          empty  = false
+          result = if internal_reverse_order?
+                     internal_queue.pop_last { empty = true }
+                   else
+                     internal_queue.pop { empty = true }
+                   end
+
+          return result unless empty
+          remaining = remaining_timeout(deadline)
+          return block_given? ? yield : nil unless wait_pop(timeout: remaining)
+        end
+      end
+
+      # Add a value, waiting for capacity when the queue is bounded and full.
+      # @param value [BasicObject] the value to add
+      # @param non_block [Boolean] whether to raise an exception when the queue is at capacity
+      # @param priority [BasicObject] the value used to order the entry
+      # @param timeout [Numeric, nil] maximum number of seconds to wait
+      # @raise [ThreadError] when the queue is at capacity and non_block is true
+      # @return [Boolean] whether the value was added
+      def push(value, non_block = false, priority: default_priority, timeout: nil) # rubocop:disable Style/OptionalBooleanParameter
+        push_to_storage(priority, non_block, value, timeout:)
+      end
+
+      # Try to remove the oldest value at the lowest priority without waiting.
+      # @yield called when the queue is empty
+      # @return [BasicObject, nil] the next value or the fallback result
+      def try_pop(&) = internal_reverse_order? ? internal_queue.pop_last(&) : internal_queue.pop(&)
+
+      # Try to add a value without waiting.
+      # @param value [BasicObject] the value to add
+      # @param priority [BasicObject] the value used to order the entry
+      # @yield called when the queue is at capacity
+      # @return [Boolean, BasicObject] true, or the fallback result when full
+      def try_push(value, priority: default_priority)
+        return true if internal_queue.push(priority, value)
+
+        block_given? ? yield : false
+      end
+
+      # Return the next priority without removing it.
+      # @yield called when the queue is empty
+      # @return [BasicObject, nil] the priority or the fallback result
+      def first_priority(&)
+        internal_reverse_order? ? internal_queue.peek_last_priority(&) : internal_queue.peek_priority(&)
+      end
+
+      # Return the last priority without removing it.
+      # @yield called when the queue is empty
+      # @return [BasicObject, nil] the priority or the fallback result
+      def last_priority(&)
+        internal_reverse_order? ? internal_queue.peek_priority(&) : internal_queue.peek_last_priority(&)
+      end
+
+      # Delete the oldest matching value at the exact priority.
+      # @param value [BasicObject] the value to delete
+      # @param priority [BasicObject] the exact priority to search
+      # @param compare_by_identity [Boolean] compare values by identity instead of equality
+      # @return [Boolean] whether a value was deleted
+      def delete(value, priority:, compare_by_identity: false)
+        delete_from_storage(priority, value, compare_by_identity:)
+      end
+
+      # Wait until a value is available without removing it.
+      def wait_pop(timeout: nil) = wait(timeout) { size.positive? }
+
+      private
+
+      def internal_reverse_order? = @reverse_order
+
+      def normalize_order(order)
+        return :ascending if :ascending.equal?(order)
+        return :descending if :descending.equal?(order)
+
+        raise ArgumentError, "order must be :ascending or :descending"
+      end
+    end
+  end
+end

data/lib/farce/abstract/queue.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract A shared super class for all queues defined by Farce.
+    #
+    # A queue is a collection of items that can be added to and removed from in a thread-safe manner.
+    # The order is typically FIFO (first-in, first-out), but other orderings may be applied on top.
+    #
+    # Queues have a blocking and non-blocking interface.
+    #
+    # @!attribute [r] capacity
+    #   @abstract
+    #   @return [Integer, nil] The maximum number of items the queue can hold.
+    #
+    # @!attribute [r] num_waiting
+    #   @abstract
+    #   The number of threads/fibers currently waiting on the queue. This is a momentary snapshot and may be an
+    #   approximation. The number may also include threads waiting for a push to succeed, as well as threads waiting
+    #   without modifying the queue.
+    #   @return [Integer] Number of threads/fibers waiting on the queue.
+    #
+    # @!attribute [r] mode
+    #   @return [Symbol] The default mode used to transfer values between Ractors.
+    #
+    # @!attribute [r] size
+    #   @abstract
+    #   @return [Integer] The current number of items in the queue.
+    #
+    # @!method initialize(capacity: 1024, track_age: false)
+    #   @abstract Subclasses may add additional parameters to this method.
+    #   @param capacity [Integer, nil]
+    #     The maximum number of items the queue can hold.
+    #     If `nil`, the queue is unbounded.
+    #
+    #     The default may vary for subclasses.
+    #     Most notably, priority and timer queues default to `nil`.
+    #   @param track_age [Boolean] Whether to track enqueue age and queue generations.
+    #
+    # @!method clear
+    #   @abstract
+    #   Removes all items from the queue.
+    #   @return [self]
+    #
+    # @!method close
+    #   @abstract
+    #   Closes the queue, preventing any further items from being added.
+    #   @return [self]
+    #
+    # @!method closed?
+    #   @abstract
+    #   Checks whether the queue is closed.
+    #   @return [Boolean] `true` if the queue is closed, `false` otherwise.
+    #
+    # @!method seal
+    #   Stops new pushes while allowing queued items to be removed.
+    #   The queue closes automatically when it becomes empty.
+    #   @return [self]
+    #
+    # @!method sealed?
+    #   @return [Boolean] Whether the queue rejects new pushes.
+    #
+    # @!method empty?
+    #   @abstract
+    #   Checks whether the queue is empty.
+    #   @return [Boolean] `true` if the queue is empty, `false` otherwise.
+    #
+    # @!method pop(non_block = false, timeout: nil)
+    #   @abstract Subclasses may add additional parameters to this method.
+    #   Takes an item from the queue, blocking until one is available or the timeout expires.
+    #   @yield Block called if the timeout expires before an item is available.
+    #   @param non_block [Boolean] whether to raise an exception when the queue is empty
+    #   @param timeout [Numeric, nil]
+    #     The maximum time to wait for an item to be available.
+    #     If `nil`, the method will wait indefinitely.
+    #     If `0`, the method will not wait at all.
+    #   @raise [Farce::ClosedQueueError] when the queue is closed
+    #   @raise [ThreadError] when the queue is empty and non_block is true
+    #   @return [BasicObject, nil]
+    #     The item taken from the queue, or the return value of the block or `nil` if the timeout expired.
+    #
+    # @!method push(value, non_block = false, timeout: nil)
+    #   @abstract
+    #     Subclasses may add additional parameters to this method.
+    #     They may also restrict what types of values can be pushed onto the queue.
+    #     In particular, some queues may only accept Ractor-shareable values.
+    #   Pushes an item onto the queue. May block if the queue is at capacity.
+    #   If the queue is unbounded, this method will never block.
+    #   If a timeout is specified, the method will block until the item is added or the timeout expires.
+    #   @param value [BasicObject] The item to add to the queue.
+    #   @param non_block [Boolean] whether to raise an exception when the queue is full
+    #   @param timeout [Numeric, nil]
+    #     The maximum time to wait for the item to be added.
+    #     If `nil`, the method will wait indefinitely.
+    #     If `0`, the method will not wait at all.
+    #   @raise [Farce::ClosedQueueError] when the queue is closed
+    #   @raise [Farce::SealedQueueError] when the queue is sealed but not yet closed
+    #   @raise [ThreadError] when the queue is full and non_block is true
+    #   @return [Boolean] `true` if the item was added to the queue
+    #
+    # @!method try_pop
+    #   @abstract Subclasses may add additional parameters to this method.
+    #   Tries to take an item from the queue without blocking.
+    #   If no item is available, the method will call the block if given, or return `nil` if no block is given.
+    #   @yield Block called if no item is available.
+    #   @return [BasicObject, nil]
+    #     The item taken from the queue, or the return value of the block or `nil` if no item was available.
+    #
+    # @!method try_push(value)
+    #   @abstract Subclasses may add additional parameters to this method.
+    #   Tries to push an item onto the queue without blocking.
+    #   If the queue is at capacity, the method will call the block if given, or return `false` if no block is given.
+    #   @param value [BasicObject] The item to add to the queue.
+    #   @yield Block called if the queue is at capacity.
+    #   @raise [Farce::ClosedQueueError] when the queue is closed
+    #   @raise [Farce::SealedQueueError] when the queue is sealed but not yet closed
+    #   @return [Boolean]
+    #     `true` if the item was added to the queue, `false` if the queue was at capacity and no block was given.
+    #
+    # @!method wait_pop(timeout: nil)
+    #   @abstract Subclasses may add additional parameters to this method.
+    #   Waits until an item is available to pop from the queue, or the timeout expires.
+    #   Does not remove the item from the queue.
+    #   Note that this method does not guarantee a subsequent call to {#pop} or {#try_pop} will succeed,
+    #   as another thread may remove the item first.
+    #   @param timeout [Numeric, nil]
+    #     The maximum time to wait for an item to be available.
+    #     If `nil`, the method will wait indefinitely.
+    #     If `0`, the method will not wait at all.
+    #   @raise [Farce::ClosedQueueError] when the queue is closed
+    #   @return [Boolean] `true` if an item is available, `false` if the timeout expired.
+    #
+    # @!method wait_push(timeout: nil)
+    #   @abstract Subclasses may add additional parameters to this method.
+    #   Waits until there is space to push an item onto the queue, or the timeout expires.
+    #   Note that this method does not guarantee a subsequent call to {#push} or {#try_push} will succeed,
+    #   as another thread may add an item first.
+    #   @param timeout [Numeric, nil]
+    #     The maximum time to wait for space to be available.
+    #     If `nil`, the method will wait indefinitely.
+    #     If `0`, the method will not wait at all.
+    #   @raise [Farce::ClosedQueueError] when the queue is closed
+    #   @raise [Farce::SealedQueueError] when the queue is sealed but not yet closed
+    #   @return [Boolean] `true` if space is available, `false` if the timeout expired.
+    class Queue
+      include Internal::MarshalSupport::Reject
+      include Internal::Inspect
+
+      # The default mode used to transfer values between Ractors.
+      # @return [Symbol]
+      def mode = :raise
+
+      # Alias for {#pop} to match the interface of Ruby's Queue class.
+      # @return (see #pop)
+      def deq(...) = pop(...)
+      alias shift deq
+
+      # Alias for {#push} to match the interface of Ruby's Queue class.
+      # @return (see #push)
+      def enq(...) = push(...)
+      alias << enq
+
+      # Alias for {#size} to match the interface of Ruby's Queue class.
+      # @return (see #size)
+      def length = size
+
+      # The maximum number of items the queue can hold.
+      # @return [Integer, Float] the maximum number of items, or `Float::INFINITY` if the queue is unbounded.
+      def max = capacity || Float::INFINITY
+
+      # Whether the queue is at capacity.
+      # @return [Boolean] `true` if the queue is at capacity, `false` otherwise.
+      def full? = capacity && size >= capacity
+
+      def capacity = internal_queue.capacity
+
+      def clear
+        internal_queue.clear
+        self
+      end
+
+      def close
+        internal_queue.close
+        self
+      end
+
+      # Stop new pushes and close after the final queued item is removed.
+      # @return [self]
+      def seal
+        internal_queue.seal
+        self
+      end
+
+      def closed? = internal_queue.closed?
+      def sealed? = internal_queue.sealed?
+
+      # @return [Boolean] Whether enqueue-age tracking is enabled.
+      def age_tracking? = internal_queue.age_tracking?
+
+      # @return [Integer, nil] The mutation generation, or `nil` when tracking is disabled.
+      def generation = internal_queue.generation
+
+      # The timestamp is monotonic. Its origin is runtime-specific.
+      # @return [Float, nil] The monotonic enqueue time of the oldest item.
+      def oldest_enqueued_at = internal_queue.oldest_enqueued_at
+
+      # @return [Float, nil] Seconds since the oldest item was enqueued.
+      def oldest_age = internal_queue.oldest_age
+
+      def empty? = size.zero?
+
+      def num_waiting = internal_queue.num_waiting
+
+      def pop(non_block = false, timeout: nil, &) # rubocop:disable Style/OptionalBooleanParameter
+        return internal_queue.try_pop { raise ThreadError, "queue empty" } if non_block
+        timeout.nil? ? internal_queue.pop(&) : internal_queue.pop(timeout:, &)
+      end
+
+      def push(value, non_block = false, timeout: nil) # rubocop:disable Style/OptionalBooleanParameter
+        if non_block
+          return true if internal_queue.try_push(value)
+          raise ThreadError, "queue full"
+        end
+        timeout.nil? ? internal_queue.push(value) : internal_queue.push(value, timeout:)
+      end
+
+      def try_pop(&) = internal_queue.try_pop(&)
+
+      def try_push(value)
+        return true if internal_queue.try_push(value)
+        block_given? ? yield : false
+      end
+
+      def size = internal_queue.size
+
+      def wait_pop(timeout: nil) = internal_queue.wait_pop(timeout:)
+
+      def wait_push(timeout: nil) = internal_queue.wait_push(timeout:)
+
+      # @api private
+      def inspect_with(inspector)
+        super do
+          if closed?
+            inspector.breakable " "
+            inspector.text "closed"
+          else
+            inspector.attributes(inspect_info)
+          end
+        end
+      end
+
+      private
+
+      def initialize_copy(_other)
+        raise TypeError, "queues cannot be copied"
+      end
+
+      def inspect_info
+        info = { size:, capacity: }.compact
+        info[:num_waiting] = num_waiting if num_waiting.positive?
+        info
+      end
+
+      private def internal_queue = @queue
+    end
+  end
+end

data/lib/farce/abstract/scheduler.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract A shared super class for all scheduler implementations.
+    #
+    # @!method schedule(*args, mode: :copy, auto_local: true)
+    #   @abstract This method must be implemented by concrete scheduler subclasses.
+    #
+    #   Schedules a block for execution.
+    #   What actually happens depends on the concrete scheduler implementation.
+    #   Some schedulers may ignore the `auto_local` option. Some might treat every mode as `:local`.
+    #
+    #   The scheduler may choose to block until the task has been executed, but most will add it to a queue of pending
+    #   tasks, only blocking when that queue's capacity has been reached.
+    #
+    #   @!macro modes
+    #
+    #   @param args [Array]
+    #     Arguments to pass to the scheduled block.
+    #     May be handled according to `mode`.
+    #
+    #   @param mode [Symbol]
+    #     The mode in which to schedule the task. Defaults to `:copy`.
+    #     May be ignored by some schedulers.
+    #
+    #   @param auto_local [Boolean]
+    #     Whether to automatically use a local mode when possible. Defaults to `true`.
+    #     May be ignored by some schedulers.
+    #
+    #   @yield [*args] The block to be executed by the scheduler.
+    #   @yieldparam args [Array] The arguments passed to the block.
+    #   @yieldreceiver [BasicObject, nil]
+    #     Local mode will not touch the block's binding (self stays the same), but other modes may change it to `nil`.
+    #
+    #   @return [self]
+    #
+    # @!method close
+    #   @abstract This method must be implemented by concrete scheduler subclasses.
+    #   Closes the scheduler, releasing any resources it holds.
+    #   Once closed, the scheduler cannot be used to schedule new tasks.
+    #   Will drain any pending tasks before fully closing. If tasks are running indefinitely, it may block.
+    #   @return [self]
+    #
+    # @!method closed?
+    #   @abstract This method must be implemented by concrete scheduler subclasses.
+    #   @return [Boolean] Whether the scheduler is closed.
+    #
+    # @!method state
+    #   @abstract This method must be implemented by concrete scheduler subclasses.
+    #   @return [Symbol]
+    #     The current state of the scheduler.
+    #
+    #     Common states include:
+    #     * `:initialized`, `:launching` and `:setup` for the setup phase.
+    #     * `:running` for the execution phase.
+    #     * `:closing`, `:closed`, and `:error` for the termination phase.
+    #
+    #     Not all schedulers will implement every state.
+    #
+    # @!method ractor_safe?
+    #   @abstract Schedulers should include {Shareable} or {Unshareable}, which implement this method.
+    #   @return [Boolean] Whether the scheduler is safe to use across Ractors.
+    class Scheduler
+      include Internal::Noncopyable
+
+      # An error that occurred during the scheduler's operation, if any.
+      # This is primarily for scheduling errors, not execution errors.
+      # You can check this if the {#state} is `:error`.
+      def error = nil
+
+      # @param wait [Boolean] Whether to wait for the owner to be non-nil before checking if the scheduler is local.
+      # @return [Boolean] Whether the scheduler is local for the current Ractor.
+      def local?(wait: true) = false # rubocop:disable Lint/UnusedMethodArgument
+
+      # Like {#schedule}, with two differences:
+      # 1. If {#local?} returns true, and it would run in local mode (either due to `auto_local` or explicitly set
+      #    `mode: :local`), it executes the block directly without enqueuing it.
+      # 2. It blocks until the block has been executed, either immediately in local mode or after being scheduled.
+      #
+      # @param (see #schedule)
+      # @return [self]
+      def execute(*, mode: :copy, auto_local: true, &callback)
+        raise LocalJumpError, "Cannot yield without a block" unless block_given?
+        raise SchedulerClosedError, "cannot execute task on a closed scheduler" if closed?
+
+        if (auto_local || mode == :local) && local?
+          raise SchedulerClosedError, "cannot execute task on a closed scheduler" if closed?
+          yield(*)
+          return self
+        end
+
+        ran      = Farce::Flag.new(false)
+        signal   = Signal.new
+        callback = Ractor.shareable_proc(&callback) unless Ractor.shareable?(callback)
+
+        schedule(callback, ran, signal, *, mode:, auto_local:) do |callback, ran, signal, *args|
+          callback.call(*args)
+        ensure
+          ran.set
+          signal.broadcast
+        end
+
+        signal.wait_until { ran.value }
+        self
+      end
+    end
+  end
+end