farce 0.4.1-java → 0.5.0-java

data/lib/farce/abstract/concurrent_map.rb

@@ -5,6 +5,9 @@
 module Farce
   module Abstract
     # @abstract Super class for {Map maps} with added concurrency features.
+    #
+    # Maps implement most of the interface provided by Hash,
+    # as well as `Concurrent::Map` from the `concurrent-ruby` gem.
     class ConcurrentMap < Map
       include DuplicableMap
 
@@ -34,6 +37,24 @@ module Farce
         end
       end
 
+      # Return an existing value or store a default for an absent key.
+      # A block takes precedence over the default and receives the original key.
+      # The lookup and store are separate operations. Concurrent writes can be overwritten.
+      # @param key [BasicObject] The key to look up or store.
+      # @param defaults [Array<BasicObject>] At most one default value to store when the key is absent.
+      # @see #store For supported transfer and timeout options.
+      # @yieldparam key [BasicObject] The original key.
+      # @yieldreturn [BasicObject] The value to store.
+      # @return [BasicObject, nil] The existing or newly stored value.
+      # @raise [KeyError] If the key is absent and neither a default nor a block is provided.
+      def fetch_or_store(key, *defaults, **)
+        if defaults.size > 1
+          raise ArgumentError, "wrong number of arguments (given #{defaults.size + 1}, expected 1..2)"
+        end
+        return fetch(key) if defaults.empty? && !block_given?
+        fetch(key) { store(key, block_given? ? yield(key) : defaults.first, **) }
+      end
+
       # Read the value associated with a key, waiting for atomic-update access if necessary.
       # @param key [BasicObject] The key to look up.
       # @param timeout [Numeric, nil] The maximum number of seconds to wait for access.
@@ -43,6 +64,12 @@ module Farce
       #   The associated value, nil if the key is absent, or the fallback result if the operation times out.
       def get(key, timeout: nil, &) = internal_map.get(key, timeout:, &)
 
+      # Sets a value and returns the previous value.
+      # @param key [BasicObject] The key to update.
+      # @param value [BasicObject] The value to store.
+      # @return [BasicObject, nil] The previous value, or nil if the key was absent.
+      def get_and_set(...) = swap(...)
+
       # Associate a value with a key, waiting for atomic-update access if necessary.
       # @param key [BasicObject] The key to store.
       # @param value [BasicObject] The value to store.
@@ -52,6 +79,9 @@ module Farce
       # @return [BasicObject, nil] `value` on success, or the fallback result or nil on timeout.
       def store(key, value, timeout: nil, &) = internal_map.store(key, value, timeout:, &)
 
+      # (see #store)
+      def put(...) = store(...)
+
       # Replace the value associated with a key and return its previous value.
       # @param key [BasicObject] The key to update.
       # @param replacement [BasicObject] The value to store.
@@ -71,6 +101,69 @@ module Farce
       # @raise [LocalJumpError] If no block is given.
       def store_if_absent(key, timeout: nil, &) = internal_map.store_if_absent(key, timeout:, &)
 
+      # (see #store_if_absent)
+      def compute_if_absent(...) = store_if_absent(...)
+
+      # Atomically store a value only when the key is absent.
+      # Existing nil and false values are preserved.
+      # @param key [BasicObject] The key to look up or store.
+      # @param value [BasicObject] The value to store when the key is absent.
+      # @see #store_if_absent For supported transfer and timeout options.
+      # @return [BasicObject, nil] The existing value, or nil when a value was inserted or access timed out.
+      def put_if_absent(key, value, **)
+        inserted = false
+        previous = store_if_absent(key, **) do
+          inserted = true
+          value
+        end
+        inserted ? nil : previous
+      end
+
+      # Atomically replace an existing value and return its previous value.
+      # An absent key is left unchanged. Existing nil and false values can be replaced.
+      # @param key [BasicObject] The key to update.
+      # @param replacement [BasicObject] The value to store.
+      # @param timeout [Numeric, nil] The maximum number of seconds to wait for access.
+      # @see #store For supported transfer options.
+      # @return [BasicObject, nil] The previous value, or nil when the key is absent or access timed out.
+      def replace_if_exists(key, replacement, timeout: nil, **)
+        map = internal_map
+        previous = nil
+        changed = map.modify(key, timeout:) do |present, value|
+          next Internal::MAP_KEEP unless present
+          previous = value
+          map.check_mutation
+          wrap_value(replacement, **)
+        end
+        unwrap_value(previous) if changed
+      end
+
+      # Atomically replace the value associated with a key if it is present.
+      # The block receives the current value and should return the new value to store.
+      # The block is not called for an absent key. A stored nil is passed to the block.
+      # @param key [BasicObject] The key to update.
+      # @param timeout [Numeric, nil] The maximum number of seconds to wait for access.
+      # @yield [value] Called with the current value if the key is present.
+      # @yieldparam value [BasicObject] The current value.
+      # @yieldreturn [BasicObject] The new value to store.
+      # @return [BasicObject, nil] The newly stored value, or nil if the key was absent or the operation timed out.
+      # @raise [LocalJumpError] If no block is given.
+      def store_if_present(key, timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        map = internal_map
+        result = nil
+        changed = map.modify(key, timeout:) do |present, value|
+          next Internal::MAP_KEEP unless present
+          replacement = yield(unwrap_value(value))
+          map.check_mutation
+          result = wrap_value(replacement)
+        end
+        unwrap_value(result) if changed
+      end
+
+      # (see #store_if_present)
+      def compute_if_present(...) = store_if_present(...)
+
       # Atomically replace a value if the key is present and its current value matches `expected`.
       # The configured value-comparison mode determines whether matching uses equality or identity.
       # @param key [BasicObject] The key to update.
@@ -82,6 +175,23 @@ module Farce
         internal_map.compare_and_set(key, expected, replacement, timeout:)
       end
 
+      # (see #compare_and_set)
+      def replace_pair(...) = compare_and_set(...)
+
+      # Atomically remove a key if its current value matches `expected`.
+      # The configured value-comparison mode determines whether matching uses equality or identity.
+      # Missing keys and mismatched values are left unchanged.
+      # @param key [BasicObject] The key to remove.
+      # @param expected [BasicObject] The expected current value.
+      # @param timeout [Numeric, nil] The maximum number of seconds to wait for access.
+      # @return [Boolean] Whether the entry was removed. Returns false on timeout.
+      def delete_pair(key, expected, timeout: nil)
+        expected = wrap_comparison(expected)
+        internal_map.modify(key, timeout:) do |present, value|
+          present && values_equal?(value, expected) ? Internal::MAP_DELETE : Internal::MAP_KEEP
+        end
+      end
+
       # Atomically replace the value associated with a key with the block result.
       # The block receives nil when the key is absent or its current value is nil.
       # @param key [BasicObject] The key to update.
@@ -93,6 +203,9 @@ module Farce
       # @raise [LocalJumpError] If no block is given.
       def update(key, timeout: nil, &) = internal_map.update(key, timeout:, &)
 
+      # (see #update)
+      def compute(...) = update(...)
+
       # Atomically insert `initial` for an absent key or replace an existing value with the block result.
       # The block is not called when the key is absent.
       # @param key [BasicObject] The key to insert or update.
@@ -105,6 +218,9 @@ module Farce
       # @raise [LocalJumpError] If no block is given.
       def upsert(key, initial, timeout: nil, &) = internal_map.upsert(key, initial, timeout:, &)
 
+      # (see #upsert)
+      def merge_pair(...) = upsert(...)
+
       # Wait until a block condition matches the current value.
       # One timeout budget covers all checks and waits. The block is not interrupted.
       # @yieldparam value [BasicObject, nil] the current value
@@ -344,6 +460,12 @@ module Farce
 
       private
 
+      def wrap_comparison(value) = value
+
+      def values_equal?(left, right)
+        compare_values_by_identity? ? left.equal?(right) : left == right
+      end
+
       def modify_entry(key, canonical: false)
         map = internal_map
         map = map.instance_variable_get(:@map) if canonical && map.is_a?(Internal::KeyNormalizer::ConcurrentMap)

data/lib/farce/abstract/counter.rb

@@ -7,6 +7,22 @@ module Farce
     # @abstract Common numeric interface and atomic operations for counters.
     # @note This is a module rather than a class so {Farce::Counter} can inherit
     #   directly from the native counter and avoid delegation overhead.
+    #
+    # @!method initial
+    #   @return [Integer] The initial value retained by reset and copies.
+    #
+    # @!method value
+    #   @return [Integer] The current value of the counter.
+    #
+    # @!method increment(by = 1)
+    #   Increment the counter by the given amount (default is 1).
+    #   @param [Numeric, String, #to_int] by The amount, converted to an Integer.
+    #   @return [self] Returns self for chaining.
+    #
+    # @!method decrement(by = 1)
+    #   Decrement the counter by the given amount (default is 1).
+    #   @param [Numeric, String, #to_int] by The amount, converted to an Integer.
+    #   @return [self] Returns self for chaining.
     module Counter
       include Internal::MarshalSupport::Counter
       include Internal::Copyable
@@ -24,6 +40,24 @@ module Farce
       include Value
       include Internal::ValueSerialization
 
+      # Pass the current value to the given block, replacing it with the block's result.
+      # May retry if the value changes during the block's execution.
+      #
+      # Provided for compatibility with `Concurrent::AtomicFixnum`.
+      #
+      # @yield [count] Calculate the new value based on the current value.
+      # @yieldparam count [Integer] the current value of the atomic fixnum.
+      # @yieldreturn [Integer] the new value to replace the current value.
+      # @return [Integer] the new value after the block has been applied.
+      def update
+        raise LocalJumpError, "no block given" unless block_given?
+        while true
+          current   = value
+          new_value = yield(current)
+          return new_value if compare_and_set(current, new_value)
+        end
+      end
+
       # Wait until the current value differs from the expected value.
       # @param expected [Integer] the value to wait to change from
       # @param timeout [Numeric, nil] the total seconds available
@@ -35,7 +69,7 @@ module Farce
           observed = signal.generation
           current = value
           return current unless expected == current
-          break unless signal.wait(observed, timeout: Internal.remaining_timeout(deadline))
+          break unless signal.wait(observed, timeout: Clock.remaining(deadline))
         end
         yield if block_given?
       end

data/lib/farce/abstract/executor.rb

@@ -12,7 +12,7 @@ module Farce
     #
     # @abstract Use a scheduler or pool class.
     #
-    # @!method schedule(*args, mode: :smart, auto_local: true)
+    # @!method schedule(*args, mode: :smart, auto_local: true, timeout: nil)
     #   @abstract This method must be implemented by concrete executor subclasses.
     #
     #   Schedules a block for execution.
@@ -36,12 +36,18 @@ module Farce
     #     Whether to automatically use a local mode when possible. Defaults to `true`.
     #     May be ignored by some executors.
     #
+    #   @param timeout [Numeric, nil]
+    #     Maximum seconds to wait for ownership and queue space. Nil waits indefinitely.
+    #     Zero only submits if no waiting is needed. Must be finite and non-negative.
+    #     An expired attempt returns `nil` and does not enqueue the task.
+    #     This does not limit task execution time. Executors without a queue may ignore it.
+    #
     #   @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]
+    #   @return [self, nil] self when submitted, or nil when the scheduling timeout expires.
     #
     # @!method close
     #   @abstract This method must be implemented by concrete executor subclasses.
@@ -84,7 +90,9 @@ module Farce
       # Attempts to submit a task. Queue-based executors return `nil` when full
       # instead of waiting for space. Other executors behave like {#schedule}.
       #
-      # @param (see #schedule)
+      # @param args (see #schedule)
+      # @param mode (see #schedule)
+      # @param auto_local (see #schedule)
       # @return [self, nil] self when submitted, or nil when the queue is full.
       def try_schedule(...) = schedule(...)
 
@@ -98,14 +106,16 @@ module Farce
       # 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.
+      # A `timeout` only limits scheduling waits. Once submitted, this waits for completion without a timeout.
       #
       # @param (see #schedule)
-      # @return [self]
-      def execute(*, mode: :smart, auto_local: true, &callback)
+      # @return [self, nil] self after execution, or nil when the scheduling timeout expires.
+      def execute(*, mode: :smart, auto_local: true, timeout: nil, &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?
+        deadline = scheduling_deadline(timeout)
+        if (auto_local || mode == :local) && local?(wait: timeout.nil?)
           raise SchedulerClosedError, "cannot execute task on a closed scheduler" if closed?
           yield(*)
           return self
@@ -115,16 +125,29 @@ module Farce
         signal   = Signal.new
         callback = Ractor.shareable_proc(&callback) unless Ractor.shareable?(callback)
 
-        schedule(callback, ran, signal, *, mode:, auto_local:) do |callback, ran, signal, *args|
+        submitted = schedule(callback, ran, signal, *, mode:, auto_local:,
+          timeout: Clock.remaining(deadline)) do |callback, ran, signal, *args|
           callback.call(*args)
         ensure
           ran.set
           signal.broadcast
         end
+        return unless submitted
 
         signal.wait_until { ran.value }
         self
       end
+
+      private
+
+      def scheduling_deadline(timeout)
+        return if timeout.nil?
+        timeout = Float(timeout)
+        unless timeout.finite? && !timeout.negative?
+          raise ArgumentError, "timeout must be a finite, non-negative number or nil"
+        end
+        Clock.timeout(timeout)
+      end
     end
   end
 end

data/lib/farce/abstract/flag.rb

@@ -61,9 +61,21 @@ module Farce
 
       # @return [Boolean] whether the flag is set
       def set? = value
+      alias true? set?
 
       # @return [Boolean] whether the flag is unset
       def unset? = !value
+      alias false? unset?
+
+      # Explicitly sets the value to true.
+      # Provided for compatibility with `Concurrent::AtomicBoolean`.
+      # @return [Boolean] true if the value has changed
+      def make_true = compare_and_set(false, true)
+
+      # Explicitly sets the value to false.
+      # Provided for compatibility with `Concurrent::AtomicBoolean`.
+      # @return [Boolean] true if the value has changed
+      def make_false = compare_and_set(true, false)
 
       # Wait until the flag becomes true.
       # @param timeout [Numeric, nil] the total seconds available