farce 0.4.1-aarch64-linux-gnu → 0.6.0-aarch64-linux-gnu

data/lib/farce/engine/shared/weak_map/cell.rb

@@ -61,7 +61,7 @@ module Farce
       end
 
       def wait_for_change?(observed, deadline)
-        timeout = deadline - Clock.now if deadline
+        timeout = Clock.remaining(deadline)
         return false if timeout && !timeout.positive?
         !!@changes.wait(observed, timeout:) { false }
       end

data/lib/farce/engine/shared.rb

@@ -54,6 +54,8 @@ module Farce
       end
     end
 
+    def native_weak_maps? = true
+
     # define_method supplies the receiver. Rebinding first is unnecessary without
     # native Ractor isolation and can change the method context used by super.
     def prepare_method_definition(&definition) = definition

data/lib/farce/engine/truffleruby/map.rb

@@ -28,7 +28,8 @@ module Farce
         end
 
         def eql?(other)
-          result = other.is_a?(Key) && value.eql?(other.value)
+          result = other.is_a?(Key) &&
+            (BASIC_OBJECT_EQUAL_METHOD.bind_call(value, other.value) || value.eql?(other.value))
           owner = mutation_owner || (other.mutation_owner if other.is_a?(Key))
           Internal::Freeze.check(owner) if owner
           result
@@ -214,11 +215,11 @@ module Farce
       # Yield presence and value under the key reservation.
       # MAP_KEEP and MAP_DELETE are control results. Other results replace the value.
       # Return whether a change committed.
-      def modify(key) # rubocop:disable Naming/PredicateMethod
+      def modify(key, timeout: nil)
         raise LocalJumpError, "no block given" unless block_given?
         check_frozen!
         wrapped = wrap_key(key)
-        _, result = with_mutating_key_operation(wrapped, nil) do |reservation|
+        completed, result = with_mutating_key_operation(wrapped, timeout_deadline(timeout)) do |reservation|
           present, current = native_operation { [concurrent_key?(wrapped), concurrent_get(wrapped)] }
           value = yield(present, current)
           next false if MAP_KEEP.equal?(value)
@@ -231,7 +232,7 @@ module Farce
             changed!
           end
         end
-        !!result
+        completed && !!result
       end
 
       def upsert(key, initial_value, timeout: nil)
@@ -557,7 +558,8 @@ module Farce
             native_operation { concurrent_get(wrapped) }
           end
           return fallback&.call unless completed
-          ready = non_nil ? !current.nil? : !values_equal?(current, expected)
+          ready = non_nil ? !current.nil? :
+            Internal.value_changed?(current, expected, compare_values_by_identity?)
           return current if ready
           return fallback&.call unless wait_for_signal(@change_signal, generation, deadline)
         end
@@ -566,7 +568,7 @@ module Farce
       def wait_for_signal(signal, generation, deadline)
         return signal.wait(generation) unless deadline
 
-        remaining = deadline - Clock.now
+        remaining = Clock.remaining(deadline)
         return false unless remaining.positive?
         !signal.wait(generation, timeout: remaining).nil?
       end

data/lib/farce/engine/truffleruby/native/counter.rb

@@ -60,7 +60,6 @@ module Farce
           check_frozen!
         end
         change(delta)
-        self
       end
 
       def decrement(delta = 1)
@@ -70,7 +69,6 @@ module Farce
           check_frozen!
         end
         change(-delta)
-        self
       end
 
       alias value get

data/lib/farce/engine/truffleruby/native/priority_queue.rb

@@ -23,8 +23,8 @@ module Farce
       private_constant :Bucket, :TrackedItem
 
       class State
-        attr_accessor :size, :sealed, :closed, :generation, :operation_owner
-        attr_reader :buckets, :capacity, :signal, :lock, :tracked_items, :track_age
+        attr_accessor :size, :sealed, :closed, :generation, :operation_owner, :capacity
+        attr_reader :buckets, :signal, :lock, :tracked_items, :track_age
 
         def initialize(capacity:, signal:, lock:, track_age:)
           @buckets = []
@@ -139,7 +139,18 @@ module Farce
         with_queue_operation(state) { state.size.zero? } # rubocop:disable Style/ZeroLengthPredicate
       end
 
-      def capacity = initialized_state.capacity
+      def capacity
+        state = initialized_state
+        with_queue_operation(state) { state.capacity }
+      end
+
+      def capacity=(value)
+        state = initialized_state
+        value = normalize_capacity(value)
+        with_queue_operation(state) do
+          notify_and_commit(state) { state.capacity = value }
+        end
+      end
 
       def clear
         state = initialized_state
@@ -262,7 +273,10 @@ module Farce
 
       def normalize_capacity(capacity)
         return nil if capacity.nil?
-        capacity = capacity.to_int unless primitive_is_a?(capacity, Integer)
+        unless primitive_is_a?(capacity, Integer)
+          raise TypeError, "capacity must be an Integer or nil" unless capacity.respond_to?(:to_int)
+          capacity = capacity.to_int
+        end
         raise TypeError, "capacity must be an Integer or nil" unless primitive_is_a?(capacity, Integer)
         raise ArgumentError, "capacity must be positive or nil" unless capacity.positive?
         capacity

data/lib/farce/engine/truffleruby/signal.rb

@@ -43,7 +43,7 @@ module Farce
               current = generation
               break current unless current == observed
 
-              remaining = deadline - Clock.now if deadline
+              remaining = Clock.remaining(deadline)
               break TIMED_OUT if remaining && !remaining.positive?
               @num_waiting.set(@num_waiting.get + 1) unless waiting
               waiting = true

data/lib/farce/engine/truffleruby.rb

@@ -39,6 +39,15 @@ module Farce
 
     def native_ractors? = false
 
+    # Range#initialize rejects open endpoints on TruffleRuby, while Range.new accepts them.
+    def initialize_range(target, first, last, exclude_end)
+      if first.nil? || last.nil?
+        target.__send__(:initialize_copy, target.class.new(first, last, exclude_end))
+      else
+        target.__send__(:initialize, first, last, exclude_end)
+      end
+    end
+
     # @api private
     # TruffleRuby probes this additional hook before using _dump.
     def marshal_protocol_method?(name)

data/lib/farce/extension.rb

@@ -100,13 +100,15 @@ module Farce
     # @yield the block containing method definitions
     # @yieldreceiver [Module, Refinement] the module/refinement used for extending the target class.
     # @return [self] the extension instance
-    def define(*targets, &)
+    # rubocop:disable-next Naming/BlockForwarding, Style/ArgumentsForwarding
+    def define(*targets, &block)
+      # JRuby rejects repeated anonymous block forwarding inside a block.
       @lock.synchronize do
         check_state!
         targets.each do |target|
-          refine(target, &)
+          refine(target, &block)
           mixin = @definitions.store_if_absent(target) { Mixin.new(self, target) }
-          mixin.module_eval(&)
+          mixin.module_eval(&block)
           mixin.install if installed?
         end
       end

data/lib/farce/integrations/concurrent.rb

@@ -3,9 +3,14 @@
 # warn_indent: true
 
 # @!group concurrent-ruby Integration
-require "farce"           unless defined?(Farce::Abstract)
-require "concurrent/map"  unless defined?(Concurrent::Map)
-require "concurrent/tvar" unless defined?(Concurrent::TVar)
+require "farce"                              unless defined?(Farce::Abstract)
+require "concurrent/map"                     unless defined?(Concurrent::Map)
+require "concurrent/tvar"                    unless defined?(Concurrent::TVar)
+require "concurrent/atomic/atomic_reference" unless defined?(Concurrent::AtomicReference)
+require "concurrent/atomic/atomic_fixnum"    unless defined?(Concurrent::AtomicFixnum)
+require "concurrent/atomic/atomic_boolean"   unless defined?(Concurrent::AtomicBoolean)
+require "concurrent/atomic/event"            unless defined?(Concurrent::Event)
+require "concurrent/atomic/count_down_latch" unless defined?(Concurrent::CountDownLatch)
 
 module Farce
   module Integrations
@@ -109,4 +114,12 @@ module Farce
   Internal::Converter.define(::Concurrent::Map, :Map) do |instance, value|
     value.each { instance[_1] = convert(_2) }
   end
+
+  Farce.on_main do
+    Subscription.define(::Concurrent::AtomicReference) { subscriber.value = it }
+    Subscription.define(::Concurrent::AtomicFixnum) { |_| subscriber.increment }
+    Subscription.define(::Concurrent::AtomicBoolean) { |_| subscriber.make_true }
+    Subscription.define(::Concurrent::Event) { |_| subscriber.set }
+    Subscription.define(::Concurrent::CountDownLatch) { |_| subscriber.count_down }
+  end
 end

data/lib/farce/integrations/sorted_set.rb

@@ -7,5 +7,6 @@ require "farce" unless defined?(Farce::Abstract)
 require "sorted_set"
 
 module Farce
+  Farce.dedup.store(::SortedSet)
   Internal::Converter.define(::SortedSet, :SortedSet)
 end

data/lib/farce/internal/blocking_priority_queue.rb

@@ -32,7 +32,8 @@ module Farce
 
         wait(timeout) do
           raise_unwritable if sealed?
-          size < capacity
+          limit = capacity
+          !limit || size < limit
         end
       end
 
@@ -76,7 +77,7 @@ module Farce
         while true
           return true if internal_queue.push(priority, value)
           raise ThreadError, "queue full" if non_block
-          return false unless wait_push(timeout: remaining_timeout(deadline))
+          return false unless wait_push(timeout: Clock.remaining(deadline))
         end
       end
 
@@ -98,7 +99,7 @@ module Farce
           generation = internal_signal.generation
           raise ::Farce::ClosedQueueError, "queue is closed" if closed?
           return true if yield
-          return false unless internal_signal.wait(generation, timeout: remaining_timeout(deadline))
+          return false unless internal_signal.wait(generation, timeout: Clock.remaining(deadline))
         end
       end
 
@@ -111,12 +112,6 @@ module Farce
       def timeout_at(timeout)
         Clock.timeout(normalize_timeout(timeout)) unless timeout.nil?
       end
-
-      def remaining_timeout(timeout_at)
-        return unless timeout_at
-        timeout = timeout_at - Clock.now
-        timeout.positive? ? timeout : 0
-      end
     end
   end
 end

data/lib/farce/internal/fake_ractor.rb

@@ -61,7 +61,7 @@ module Farce
           STATES[self] = state
           GROUPS[group] = self
 
-          state.main_thread = Thread.new do # rubocop:disable Lint/UselessSetterCall
+          state.main_thread = Thread.new do
             current = Thread.current
             group.add(current)
             current.freeze

data/lib/farce/internal/flag_waiting.rb

@@ -21,7 +21,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/internal/freeze.rb

@@ -8,11 +8,7 @@ module Farce
     module Freeze
       # Structurally freeze a Ruby facade, then validate and publish its object graph.
       # This deliberately bypasses an override that controls logical frozen state.
-      def self.publish(object)
-        Object.instance_method(:freeze).bind_call(object)
-        ::Ractor.make_shareable(object) if Internal.native_ractors?
-        object
-      end
+      def self.publish(object) = Internal.publish_shareable(object)
 
       def self.check(object)
         return object unless object.frozen?

data/lib/farce/internal/lease_initialization.rb

@@ -31,7 +31,7 @@ module Farce
             reject_recursive_initialization!
             return unless wait
 
-            remaining = deadline - Clock.now if deadline
+            remaining = Clock.remaining(deadline)
             return if remaining && !remaining.positive?
             reject_unscheduled_fiber_wait!
             @signal.wait(observed, timeout: wait_interval(remaining))

data/lib/farce/internal/lease_pool_state.rb

@@ -108,7 +108,7 @@ module Farce
           return create_resource(factory) if reserve_creation
           return unless wait
 
-          remaining = deadline - Clock.now if deadline
+          remaining = Clock.remaining(deadline)
           raise TimeoutError, "lease pool checkout timed out" if remaining && !remaining.positive?
           interval = LeaseWaiting.wait_interval(remaining)
           changed  = Thread.handle_interrupt(Exception => :immediate) do

data/lib/farce/internal/lease_state.rb

@@ -156,7 +156,7 @@ module Farce
           resource = try_acquire(kind)
           return resource if resource
 
-          remaining = deadline - Clock.now if deadline
+          remaining = Clock.remaining(deadline)
           raise TimeoutError, "lease checkout timed out" if remaining && !remaining.positive?
           reject_unscheduled_fiber_wait!
           interval = wait_interval(remaining)
@@ -180,7 +180,7 @@ module Farce
           outcome  = try_acquire_block(block)
           return outcome.first if outcome
 
-          remaining = deadline - Clock.now if deadline
+          remaining = Clock.remaining(deadline)
           raise TimeoutError, "lease checkout timed out" if remaining && !remaining.positive?
           reject_unscheduled_fiber_wait!
           interval = wait_interval(remaining)

data/lib/farce/internal/local_executor_methods.rb

@@ -16,10 +16,10 @@ module Farce
       # Run a task directly, preserving its block, arguments, and calling fiber.
       # `mode` and `auto_local` follow the same validation as {#schedule}.
       # @param (see Abstract::Executor#execute)
-      # @return [self]
-      def execute(*, mode: :smart, auto_local: true, &)
+      # @return [self, nil]
+      def execute(*, mode: :smart, auto_local: true, timeout: nil, &)
         validate_local_mode(mode, auto_local)
-        super(*, mode: :local, auto_local: true, &)
+        super(*, mode: :local, auto_local: true, timeout:, &)
       end
 
       private

data/lib/farce/internal/map_value_modes.rb

@@ -22,9 +22,7 @@ module Farce
                      compare_keys_by_identity: compare_by_identity, compare_values_by_identity: compare_by_identity)
         initial_mapping = convert_entries(initial_mapping)
 
-        identity         = BasicObject.instance_method(:equal?)
-        valid_comparison = identity.bind_call(compare_values_by_identity, true) ||
-          identity.bind_call(compare_values_by_identity, false)
+        valid_comparison = true.equal?(compare_values_by_identity) || false.equal?(compare_values_by_identity)
 
         raise ArgumentError, "compare_values_by_identity must be a boolean" unless valid_comparison
         @compare_values_by_identity = compare_values_by_identity
@@ -33,9 +31,11 @@ module Farce
         @map     = new_map(compare_by_identity:, compare_keys_by_identity:, compare_values_by_identity: true)
         KeyNormalizer.prepare_concurrent(@map)
 
-        restoring  = KeyNormalizer.restoration?(normalize_keys)
-        normalizer = KeyNormalizer.build(normalize_keys, shareable: true)
-        KeyNormalizer.install_concurrent(self, normalizer) unless restoring
+        unless nil.equal?(normalize_keys)
+          restoring  = KeyNormalizer.restoration?(normalize_keys)
+          normalizer = KeyNormalizer.build(normalize_keys, shareable: true)
+          KeyNormalizer.install_concurrent(self, normalizer) unless restoring
+        end
 
         initial_mapping&.each { |key, value| self[key] = value }
         KeyNormalizer.install_concurrent(self, normalizer) if restoring
@@ -143,18 +143,26 @@ module Farce
         end
       end
 
+      # (see Abstract::ConcurrentMap#wait_until)
+      def wait_until(key, timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        result = Internal.wait_until(@map, key, timeout:) { |current| yield(unwrap_value(current)) }
+        unwrap_value(result)
+      end
+
       def wait_until_changed(key, expected, timeout: nil, &)
         prepared_key = @map.normalize_external_key(key)
         expected = wrap_comparison(expected)
         deadline = Internal.timeout_deadline(timeout)
-        loop do
-          current = @map.get_prepared(prepared_key, timeout: Internal.remaining_timeout(deadline)) { TIMED_OUT }
+        # JRuby rejects repeated anonymous block forwarding inside a block.
+        while true
+          current = @map.get_prepared(prepared_key, timeout: Clock.remaining(deadline)) { TIMED_OUT }
           return unwrap_result(current, &) if TIMED_OUT.equal?(current)
           return unwrap_value(current) unless values_equal?(nil.equal?(current) ? NIL_VALUE : current, expected)
           result = @map.wait_until_changed_prepared(
             prepared_key,
             current,
-            timeout: Internal.remaining_timeout(deadline),
+            timeout: Clock.remaining(deadline),
           ) { TIMED_OUT }
           return unwrap_result(result, &) if TIMED_OUT.equal?(result)
         end

data/lib/farce/internal/pool_settings.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    PoolSettings = Data.define(:min_size, :max_size, :max_inflight, :grow_after, :shrink_after, :generation)
+  end
+end

data/lib/farce/internal/pool_worker.rb

@@ -9,46 +9,59 @@ module Farce
       include Shareable::Unfreezable
 
       def initialize(pool)
-        @pool       = pool
-        @inflight   = Counter.new if pool.max_inflight || pool.shrink_after
-        @pressure   = pool.min_size < pool.max_size
+        @pool = pool
+        @inflight = Counter.new
         @registered = Atom.new(true)
         super()
       end
 
-      def idle_timeout = @pool.shrink_after
-
-      def wait_for_admission(scheduler, runnable_count)
-        return false if @pool.drained?
-        limit = @pool.max_inflight
-        return true unless limit
+      def settings = @pool.settings
+      def idle_timeout = settings.shrink_after
 
+      def wait_for_admission(scheduler, runnable_count, settings = self.settings)
         loop do
           return false if @pool.drained?
-          return true if @pool.closing? || @pool.at_max_size? || @inflight.value < limit
-          return true if runnable_count && scheduler.public_send(runnable_count).zero?
+          return settings if @pool.closing?
+          count = @pool.size
+          limit = settings.max_inflight
+          return false if count > settings.max_size && retire?(excess: true)
+          # Busy workers keep queued dependencies runnable until they become idle.
+          return settings if !limit || count >= settings.max_size || @inflight.value < limit
+          return settings if runnable_count && scheduler.public_send(runnable_count).zero?
 
+          # Read the generation before rechecking state to avoid a lost configuration wakeup.
           generation = @pool.admission_generation
-          next if @pool.closing? || @pool.at_max_size? || @inflight.value < limit
+          settings = self.settings
+          count = @pool.size
+          limit = settings.max_inflight
+          next if @pool.closing? || !limit || count >= settings.max_size || @inflight.value < limit
           @pool.wait_for_admission(generation)
+          settings = self.settings
         end
       end
 
-      def task_started
-        @inflight&.increment
-        @pool.task_taken if @pressure
+      def task_started(settings = self.settings)
+        @inflight.increment
+        @pool.task_taken(settings)
       end
 
       def task_finished
-        return unless @inflight
         @inflight.decrement
-        @pool.admission_changed if @pool.max_inflight && !@pool.at_max_size?
+        settings = self.settings
+        count = @pool.size
+        if count > settings.max_size
+          @inflight.value.zero? ? @pool.wake_retiring_workers : @pool.admission_changed
+        elsif settings.max_inflight && count < settings.max_size
+          @pool.admission_changed
+        end
       end
 
-      def retire?
-        return false unless @inflight&.value&.zero?
-        return false unless @pool.retire_worker
-        @registered.compare_and_set(true, false)
+      def retire?(excess: false, expected: nil)
+        return false unless @inflight.value.zero?
+        return false unless @pool.retire_worker(excess:, expected:)
+        retired = @registered.compare_and_set(true, false)
+        @pool.worker_retired if retired
+        retired
       end
 
       def stopped(error, replace: true) # rubocop:disable Naming/PredicateMethod

data/lib/farce/internal/reservation_waiting.rb

@@ -9,7 +9,7 @@ module Farce
     module ReservationWaiting
       def self.wait(signal, generation, deadline)
         while true
-          remaining = deadline - Clock.now if deadline
+          remaining = Clock.remaining(deadline)
           return false if remaining && !remaining.positive?
 
           # LeaseWaiting supplies the full remaining timeout on default engines

data/lib/farce/internal/scheduler_lifecycle.rb

@@ -146,8 +146,8 @@ module Farce
           service_policy
           break if idle?
           deadline = @timers.peek_priority
-          timeout = deadline ? deadline - Clock.now : nil
-          timeout = 0 if timeout&.negative? || ready? || !@mailbox.empty?
+          timeout = Clock.remaining(deadline)
+          timeout = 0 if ready? || !@mailbox.empty?
           dispatch(timeout, @timers.empty? ? @dispatch_budget : 256)
         end
 

data/lib/farce/internal/weak_map_value_modes.rb

@@ -24,6 +24,11 @@ module Farce
         super
       end
 
+      def replace_if_exists(key, replacement, mode: nil, **)
+        @manager.validate_mode!(mode)
+        super
+      end
+
       def store_if_absent(key, mode: nil, **)
         raise LocalJumpError, "no block given" unless block_given?
         @manager.validate_mode!(mode)

data/lib/farce/internal.rb

@@ -77,18 +77,12 @@ module Farce
       Clock.now + timeout
     end
 
-    def remaining_timeout(deadline)
-      return unless deadline
-      remaining = deadline - Clock.now
-      remaining.negative? ? 0 : remaining
-    end
-
     # Repeat with one timeout budget. Even a zero timeout permits the first check.
     def with_timeout(timeout)
       raise LocalJumpError, "no block given" unless block_given?
       deadline = timeout_deadline(timeout)
       loop do
-        yield remaining_timeout(deadline), deadline
+        yield Clock.remaining(deadline), deadline
         return if deadline && Clock.now >= deadline
       end
     end
@@ -98,10 +92,16 @@ module Farce
       with_timeout(timeout) do |_, deadline|
         current = keys.empty? ? receiver.value : receiver[*keys]
         return current if yield(current)
-        receiver.wait_until_changed(*keys, current, timeout: remaining_timeout(deadline)) { return }
+        receiver.wait_until_changed(*keys, current, timeout: Clock.remaining(deadline)) { return }
       end
     end
 
+    # An unchanged observation must permit waiting even when its equality is non-reflexive.
+    def value_changed?(current, expected, identity)
+      return false if BasicObject.instance_method(:equal?).bind_call(current, expected)
+      identity || !(current == expected) # rubocop:disable Style/InverseMethods -- != can be overridden independently.
+    end
+
     def garbage_collectable?(object)
       case object
       when Integer, Float, Complex, Rational, Symbol, true, false, nil then false
@@ -113,9 +113,20 @@ module Farce
     def storage_thread(thread)            = thread
     def prepare_mutable_numeric(_)        = nil
     def prepare_map_access(_klass, _kind) = nil
+    def prepare_shareable_class(_base)    = nil
     def finalize_engine                   = nil
     def with_scheduler_thread_group       = yield(ThreadGroup.new)
 
+    def initialize_range(target, first, last, exclude_end)
+      target.__send__(:initialize, first, last, exclude_end)
+    end
+
+    def publish_shareable(object)
+      Object.instance_method(:freeze).bind_call(object)
+      ::Ractor.make_shareable(object) if native_ractors?
+      object
+    end
+
     def delegate(from, to, *methods)
       methods.each do |method|
         if to.is_a?(Module)

data/lib/farce/lazy.rb

@@ -59,6 +59,9 @@ module Farce
   # # Will only compute the expensive attribute once, and return the same value to all Ractors.
   # 5.times { Ractor.new(object) { it.expensive_attribute } }
   # ```
+  #
+  # @see Farce::Memoize
+  # @see Farce::LazyRef
   class Lazy < Farce::Abstract::Lazy
     include Shareable::Tracked
 

data/lib/farce/lazy_ref.rb

@@ -22,6 +22,9 @@ module Farce
   #   #   initialized.value # => 0
   #   #   lazy_ref[:key] = :value
   #   #   initialized.value # => 1
+  #   #
+  #   # @see Farce::Memoize
+  #   # @see Farce::Lazy
   #   class LazyRef < Farce::Reference
   #     # @!macro modes
   #     # @overload initialize(factory, mode: :smart)

data/lib/farce/local/counter.rb

@@ -50,19 +50,13 @@ module Farce
 
       # Increment the counter atomically.
       # @param by [Numeric, String, #to_int] the amount, converted to an Integer
-      # @return [self]
-      def increment(by = 1)
-        internal_counter.increment(by)
-        self
-      end
+      # @return [Integer] the value produced by this atomic update
+      def increment(by = 1) = internal_counter.increment(by)
 
       # Decrement the counter atomically.
       # @param by [Numeric, String, #to_int] the amount, converted to an Integer
-      # @return [self]
-      def decrement(by = 1)
-        internal_counter.decrement(by)
-        self
-      end
+      # @return [Integer] the value produced by this atomic update
+      def decrement(by = 1) = internal_counter.decrement(by)
 
       alias subtract decrement
       alias remove   decrement