farce 0.4.1-java → 0.5.0-java

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

data/lib/farce/concurrent/fiber_local_var.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Concurrent
+    # A replacement for `concurrent-ruby`'s `Concurrent::FiberLocalVar`
+    # @see https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/FiberLocalVar.html
+    #
+    # May or may not be Ractor-shareable depending on provided default values.
+    #
+    # @attribute [rw] value
+    #   @return [Object] the current value of the fiber-local variable
+    #
+    # @!method bind(value)
+    #   @param value [Object] the value to bind to the fiber-local variable
+    #   @yield the block with the value bound to the fiber-local variable
+    #   @return [BasicObject] the result of the block
+    class FiberLocalVar < LocalVar
+      # @overload initialize(default = nil)
+      #   @param default [Object] the default value for the fiber-local variable
+      #
+      # @overload initialize
+      #   @yield the block to compute the default value for the fiber-local variable
+      def initialize(...) = super(:fiber, ...)
+    end
+
+    # Alias for `FiberLocalVar` to maintain compatibility with `LockLocalVar`
+    LockLocalVar = FiberLocalVar
+  end
+end

data/lib/farce/concurrent/local_var.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Concurrent
+    # @!visibility private
+    class LocalVar # :nodoc: all
+      include Abstract::Value
+      include Internal::Freeze::Tracked
+      include Internal::MarshalSupport::Reject
+
+      def initialize(scope, default = nil, &block)
+        @scope = scope
+
+        if block
+          @default_block = try_shareable(block)
+          @default       = nil
+        else
+          @default_block = nil
+          @default       = default
+        end
+
+        super()
+        __freeze__
+      end
+
+      def bind(value)
+        check_frozen!
+        return unless block_given?
+        current_storage       = storage
+        old_value             = self.value
+        current_storage[self] = value
+
+        begin
+          yield
+        ensure
+          current_storage[self] = old_value
+        end
+      end
+
+      def value = storage.store_if_absent(self) { @default_block ? @default_block.call : @default }
+
+      def value=(new_value)
+        check_frozen!
+        storage[self] = new_value
+      end
+
+      private
+
+      def storage = Internal::Storage.scope(@scope)
+
+      def try_shareable(block)
+        return block if Ractor.shareable?(block)
+        Ractor.shareable_proc(&block)
+      rescue StandardError
+        block
+      end
+
+      define_method(:__freeze__, Kernel.instance_method(:freeze))
+    end
+
+    private_constant :LocalVar
+  end
+end

data/lib/farce/concurrent/thread_local_var.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Concurrent
+    # A replacement for `concurrent-ruby`'s `Concurrent::ThreadLocalVar`
+    # @see https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/ThreadLocalVar.html
+    #
+    # May or may not be Ractor-shareable depending on provided default values.
+    #
+    # @attribute [rw] value
+    #   @return [Object] the current value of the thread-local variable
+    #
+    # @!method bind(value)
+    #   @param value [Object] the value to bind to the thread-local variable
+    #   @yield the block with the value bound to the thread-local variable
+    #   @return [BasicObject] the result of the block
+    class ThreadLocalVar < LocalVar
+      # @overload initialize(default = nil)
+      #   @param default [Object] the default value for the thread-local variable
+      #
+      # @overload initialize
+      #   @yield the block to compute the default value for the thread-local variable
+      def initialize(...) = super(:thread, ...)
+    end
+  end
+end

data/lib/farce/concurrent/tuple.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Concurrent
+    # A replacement for `Concurrent::Tuple` from `concurrent-ruby`.
+    # @see https://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Tuple.html
+    class Tuple
+      include Enumerable
+      include Shareable::Delegated
+
+      # @return [Integer] the size of the tuple
+      attr_reader :size
+
+      # @param size [Integer] the size of the tuple
+      def initialize(size)
+        @size  = Integer(size)
+        @tuple = Vector.new(@size)
+        super()
+      end
+
+      # Retrieves the value at the given index, or `nil` if the index is out of bounds.
+      # @param index [Integer] the index of the value to retrieve
+      # @return [BasicObject, nil] the value at the given index, or `nil` if out of bounds
+      def get(index) = index.between?(0, @size - 1) ? @tuple[index] : nil
+      alias volatile_get get
+
+      # Sets the value at the given index, or does nothing if the index is out of bounds.
+      # @param index [Integer] the index of the value to set
+      # @param value [BasicObject] the value to set
+      # @return [BasicObject, nil] the value set, or `nil` if out of bounds
+      def set(index, value) = index.between?(0, @size - 1) ? @tuple[index] = value : nil
+      alias volatile_set set
+
+      # Atomically sets the value at the given index to `new_value` if the current value is equal to `old_value`.
+      # @param index [Integer] the index of the value to set
+      # @param old_value [BasicObject] the expected current value
+      # @param new_value [BasicObject] the new value to set
+      # @return [Boolean] `true` if the value was set, `false` otherwise
+      def compare_and_set(index, old_value, new_value)
+        return false unless index.between?(0, @size - 1)
+        @tuple.compare_and_set(index, old_value, new_value)
+      end
+      alias cas compare_and_set
+
+      # Iterates over each element in the tuple.
+      # @yieldparam value [BasicObject] the value of each element
+      # @return [Enumerator, self] if no block is given, self otherwise
+      def each(&)
+        return enum_for(:each) unless block_given?
+        @tuple.each(&)
+        self
+      end
+
+      # @api private
+      def marshal_dump
+        [1, @tuple.to_a.map { Internal::MarshalSupport.value(it) }, frozen?]
+      end
+
+      # @api private
+      def marshal_load(data)
+        entries, frozen = Internal::MarshalSupport.payload(data, 2)
+        initialize(entries.length)
+        entries.each_with_index do |entry, index|
+          @tuple[index] = Internal::MarshalSupport.restore_value(entry)
+        end
+        Internal::MarshalSupport.freeze(self, frozen)
+      end
+
+      private def freeze_backend = @tuple
+    end
+  end
+end

data/lib/farce/concurrent.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Module to replace some functionality of `concurrent-ruby` with.
+  #
+  # Nested in a separate module so it can easily be moved into a dedicated gem
+  # (this would only happen on a major release).
+  #
+  # Not all of them are full drop-in replacements, especially when it comes to matching superclasses.
+  #
+  # If it matches the subset of functionality you need you could replace this:
+  #
+  # ```ruby
+  # require "concurrent"
+  # ```
+  #
+  # With this:
+  #
+  # ```ruby
+  # require "farce"
+  # Concurrent = Farce::Concurrent
+  # ```
+  #
+  # If developing a gem or just part of a larger app, you can and should do this under a namespace rather than globally.
+  #
+  # @see https://ruby-concurrency.github.io/concurrent-ruby/
+  module Concurrent
+    include Internal::Autoloads
+
+    Array         = Vector
+    Atom          = Farce::Atom
+    AtomicBoolean = Flag
+    AtomicFixnum  = Counter
+    Exchanger     = Farce::Exchanger
+    Hash          = Farce::Map
+    Lock          = Farce::Lock
+    Map           = Farce::Map
+    ReadWriteLock = Farce::ReadWriteLock
+
+    autoload :LockLocalVar, "farce/concurrent/fiber_local_var"
+    private_constant :LocalVar
+
+    Farce.on_main do
+      Subscription.define(Event) { |_| subscriber.set }
+      Subscription.define(CountDownLatch) { |_| subscriber.count_down }
+    end
+  end
+end