farce 0.4.1 → 0.5.0

data/lib/farce/publisher.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A message multiplexer.
+  # Implements the publisher-subscriber protocol.
+  #
+  # @example
+  #   publisher = Farce::Publisher.new
+  #
+  #   # Count how many messages have been received
+  #   counter = Farce::Counter.new
+  #   publisher.subscribe(counter)
+  #
+  #   # Trigger a callback whenever a message is published
+  #   publisher.subscribe do |message|
+  #     puts "Received message: #{message}"
+  #   end
+  #
+  #   # Send messages to a queue
+  #   queue = Farce::Queue.new
+  #   publisher.subscribe(queue)
+  #
+  #   # Keep track of the last published value
+  #   atom = Farce::Atom.new
+  #   publisher.subscribe(atom)
+  #
+  #   # Send messages to a Ractor
+  #   ractor = Ractor.new do
+  #     while message = Ractor.receive
+  #       puts "Received message in Ractor: #{message}"
+  #     end
+  #   end
+  #   publisher.subscribe(ractor)
+  #
+  #   # Publish some messages
+  #   publisher.publish("Hello, world!")
+  #   publisher.publish("Another message")
+  #
+  #   queue.pop     # => "Hello, world!"
+  #   atom.value    # => "Another message"
+  #   counter.value # => 2
+  class Publisher < Farce::Abstract::Publisher
+    include Shareable::Unfreezable
+
+    # @overload initialize(*subscribers)
+    #   (see Farce::Abstract#initialize)
+    def initialize(*subscribers)
+      @map = Strict::Map.new
+      super()
+      subscribers.each { subscribe(it) }
+    end
+
+    private attr_reader :map
+  end
+end

data/lib/farce/signal.rb

@@ -80,7 +80,7 @@ module Farce
         result   = yield
         return result if result
 
-        remaining = deadline - Clock.now if deadline
+        remaining = Clock.remaining(deadline)
         return if remaining && !remaining.positive?
         return unless wait(observed, timeout: remaining)
       end

data/lib/farce/strict/publisher.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # Strict variant of {Farce::Publisher}.
+    class Publisher < Farce::Abstract::Publisher
+      include Shareable::Unfreezable
+
+      # @overload initialize(*subscribers)
+      #   (see Farce::Abstract#initialize)
+      def initialize(*subscribers)
+        @map = Strict::Map.new
+        super()
+        subscribers.each { subscribe(it) }
+      end
+
+      # (see Farce::Abstract::Publisher#publish)
+      def publish(message = nil)
+        return super if Ractor.shareable?(message)
+        raise Ractor::IsolationError, "value must be Ractor-shareable"
+      end
+      alias send      publish
+      alias <<        publish
+      alias broadcast publish
+
+      private attr_reader :map
+    end
+  end
+end

data/lib/farce/strict/vector.rb

@@ -8,10 +8,11 @@ module Farce
     class Vector < Abstract::Vector
       include Shareable::Delegated
 
-      # @param source [Array, nil] Initial values. The source array is not retained.
+      # @param source [Array, Integer, nil] Initial values or a size filled with nil. The source array is not retained.
       # @param compare_by_identity [Boolean] Whether values are compared by identity.
+      # @raise [ArgumentError] If the size is negative.
       def initialize(source = nil, compare_by_identity: false)
-        @vector = Internal::Vector.new(source, compare_by_identity:)
+        @vector = Internal::Vector.new(normalize_vector_source(source), compare_by_identity:)
         super()
       end
 

data/lib/farce/subscription/definitions.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Subscription
+    Farce.on_main do
+      ractors = Internal.native_ractors? ? [::Ractor] : [Internal::FakeRactor::Main, Internal::FakeRactor::NotMain]
+
+      define(Internal::BasePort, *ractors)      { subscriber.send(it)      }
+      define(Abstract::Publisher)               { subscriber.publish(it)   }
+      define(Abstract::Queue)                   { subscriber.try_push(it)  }
+      define(Internal::Counter, Local::Counter) { |_| subscriber.increment }
+      define(Internal::Flag, Local::Flag)       { |_| subscriber.set       }
+      define(Abstract::Atom)                    { subscriber.value = it    }
+      define(Abstract::Set, Abstract::Vector)   { subscriber << it         }
+      define(Signal)                            { |_| subscriber.broadcast }
+
+      define(::Thread::Queue) { subscriber.push(it) }
+      define(::Thread::SizedQueue) do |payload|
+        subscriber.push(payload, true)
+      rescue ThreadError
+        false
+      end
+    end
+  end
+end

data/lib/farce/subscription.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A publisher subscription that can be paused or permanently canceled.
+  # Disabling skips new messages. Unsubscribing drains an existing callback queue before stopping it.
+  class Subscription
+    include Internal::Freeze::Unfreezable
+    include Internal::Noncopyable
+
+    # Raised when an operation is attempted on an unsubscribed subscription.
+    UnsubscribedError = Class.new(StandardError)
+
+    REGISTER = ClassMirror.new(self)
+    private_constant :REGISTER
+
+    class << self
+      protected :new
+    end
+
+    # Register delivery behavior for subscriber classes from the main Ractor.
+    # Subclasses inherit the nearest registered delivery method.
+    #
+    # @example
+    #   Farce::Subscription.define(MyInbox) { |payload| subscriber.push(payload) }
+    #
+    # @param classes [Array<Class>] the subscriber classes to support
+    # @yieldparam payload [BasicObject] the published payload
+    # @yieldreceiver [Subscription] the subscription whose {#subscriber} receives the payload
+    # @note The block must be convertible to a shareable proc.
+    # @return [void]
+    def self.define(*classes, &)
+      raise LocalJumpError, "no block given" unless block_given?
+      definition = Internal.prepare_method_definition(&)
+      classes.each do |klass|
+        REGISTER.define(klass) do
+          define_method(:deliver, definition)
+          private :deliver
+        end
+      end
+    end
+
+    # @api private
+    def self.build(publisher, subscriber, ...)
+      handler = REGISTER[subscriber.class]
+      unless handler.private_method_defined?(:deliver)
+        raise ArgumentError, "Unsupported subscriber type: #{subscriber.class}"
+      end
+      handler.new(publisher, subscriber, ...)
+    end
+
+    # @return [BasicObject] the subscriber associated with this subscription
+    attr_reader :subscriber
+
+    # @return [Farce::Abstract::Publisher] the publisher associated with this subscription
+    attr_reader :publisher
+
+    # @api private
+    attr_reader :key
+
+    # @!visibility private
+    def initialize(publisher, subscriber, map, callback: false, source: nil)
+      # Keep Proc identities alive without making their captured state shareable.
+      @source     = source && Envelope.new(source, mode: :local)
+      @callback   = callback
+      @enabled    = Flag.new(true)
+      @key        = (source || subscriber).__id__
+      @map        = map
+      @publisher  = publisher
+      @subscribed = Flag.new(true)
+      @subscriber = subscriber
+      super()
+      __freeze__
+    end
+
+    # @api private
+    def publish(payload)
+      return unless enabled?
+      deliver(payload)
+      true
+    rescue ::ClosedQueueError, Ractor::ClosedError, FrozenError
+      unsubscribe
+      false
+    end
+
+    # @return [Boolean] whether the subscription is currently enabled
+    def enabled? = @subscribed.value && @enabled.value
+
+    # @return [Boolean] whether the subscription has not been permanently canceled
+    def subscribed? = @subscribed.value
+
+    # Enables the subscription, allowing it to receive published payloads.
+    # @raise [UnsubscribedError] if the subscription has been unsubscribed
+    # @return [void]
+    def enable
+      raise UnsubscribedError, "Cannot enable a subscription that has been unsubscribed" unless @subscribed.value
+      @enabled.value = true
+    end
+
+    # Disables the subscription, preventing it from receiving published payloads.
+    # @return [void]
+    def disable = @enabled.value = false
+
+    # Removes the subscription permanently, allowing it and the subscriber to be garbage collected.
+    # @return [BasicObject, nil] the subscriber, or nil if already unsubscribed
+    def unsubscribe
+      return unless @subscribed.compare_and_set(true, false)
+      @map.delete_pair(key, self)
+      subscriber.seal if @callback
+      subscriber
+    end
+    alias cancel unsubscribe
+
+    private
+
+    define_method(:__freeze__, Kernel.instance_method(:freeze))
+
+    require "farce/subscription/definitions"
+  end
+end

data/lib/farce/transaction/map.rb

@@ -16,8 +16,42 @@ module Farce
     class Map < Abstract::ConcurrentMap
       include MapOperations
 
+      # (see Abstract::ConcurrentMap#store_if_present)
+      # @param mode [Symbol, nil] The result's transfer mode, or nil to use the default.
+      def store_if_present(key, mode: nil)
+        require_block!(block_given?)
+        write do
+          canonical = prepare(key)
+          next unless @working.key?(canonical)
+          replacement = yield(unwrap_stored(@working[canonical]))
+          unwrap_stored(store_value(canonical, wrap(replacement, mode:)))
+        end
+      end
+
+      # (see Abstract::ConcurrentMap#replace_if_exists)
+      # @param mode [Symbol, nil] The replacement's transfer mode, or nil to use the default.
+      def replace_if_exists(key, replacement, mode: nil)
+        write do
+          canonical = prepare(key)
+          next unless @working.key?(canonical)
+          previous = @working[canonical]
+          store_value(canonical, wrap(replacement, mode:))
+          unwrap_stored(previous)
+        end
+      end
+
+      # (see Abstract::ConcurrentMap#delete_pair)
+      # A failed comparison invalidates the transaction attempt.
+      def delete_pair(key, expected)
+        removed = modify_entry(key) do |present, value|
+          present && values_equal?(value, expected) ? Internal::MAP_DELETE : Internal::MAP_KEEP
+        end
+        compared(removed)
+      end
+
       Wrapper.inherit(self, *MapOperations::READ_HELPERS, :delete_if, :reject!, :compact!, :keep_if,
-        :select!, :filter!, :transform_values!, :merge!)
+        :select!, :filter!, :transform_values!, :merge!, :put, :get_and_set, :compute_if_absent,
+        :compute_if_present, :replace_pair, :compute, :merge_pair, :fetch_or_store, :put_if_absent)
 
       private def enlist(backend) = @transaction.enlist(backend, per_key: true)
     end

data/lib/farce/unshared/pool.rb

@@ -36,7 +36,7 @@ module Farce
         Internal::LocalScheduledTask.new(args, block)
       end
 
-      def schedule_scaler(started, delay = @grow_after)
+      def schedule_scaler(started, delay = settings.grow_after)
         Internal::ThreadPoolSupervisor.current.schedule(self, started, delay)
       end
     end

data/lib/farce/unshared/publisher.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # Unshared variant of {Farce::Publisher}.
+    class Publisher < Abstract::Publisher
+      include Unshareable
+
+      # @overload initialize(*subscribers)
+      #   (see Farce::Abstract#initialize)
+      def initialize(...)
+        @map = Unshared::Map.new
+        super
+      end
+
+      private
+
+      attr_reader :map
+
+      def default_mode = :local
+    end
+  end
+end

data/lib/farce/unshared/scheduler.rb

@@ -20,12 +20,12 @@ module Farce
     #   results.pop # => :done
     #   scheduler.close
     #
-    # @!method schedule(*args, mode: :smart, auto_local: true)
+    # @!method schedule(*args, mode: :smart, auto_local: true, timeout: nil)
     #   Enqueue a task while retaining its block and argument references.
     #   `mode` is ignored when `auto_local` is true. Otherwise, only local and
     #   smart modes are accepted.
     #   @param (see Farce::Abstract::Executor#schedule)
-    #   @return [self]
+    #   @return [self, nil] self when submitted, or nil when the scheduling timeout expires.
     class Scheduler < Abstract::Scheduler
       include Unshareable
       include Internal::LocalExecutorMethods
@@ -80,7 +80,7 @@ module Farce
       def new_queue(capacity:)             = Internal::UnsharedQueue.new(capacity:)
       def launch_callback                  = ->(_scheduler, priority, name) { launch!(name, priority) }
 
-      def prepare_task(args, block, mode, auto_local)
+      def prepare_task(args, block, mode, auto_local, **)
         validate_local_mode(mode, auto_local)
         Internal::LocalScheduledTask.new(args, block)
       end

data/lib/farce/unshared/vector.rb

@@ -9,10 +9,11 @@ module Farce
       include Unshareable
       include Internal::Freeze::Delegated
 
-      # @param source [Array, nil] Initial values. Values are retained directly.
+      # @param source [Array, Integer, nil] Initial values or a size filled with nil. Values are retained directly.
       # @param compare_by_identity [Boolean] Whether values are compared by identity.
+      # @raise [ArgumentError] If the size is negative.
       def initialize(source = nil, compare_by_identity: false)
-        @vector = Internal::UnsharedVector.new(source, compare_by_identity:)
+        @vector = Internal::UnsharedVector.new(normalize_vector_source(source), compare_by_identity:)
         super()
       end
 

data/lib/farce/vector.rb

@@ -20,10 +20,12 @@ module Farce
     include Shareable::Delegated
 
     # @!macro modes
-    # @param source [Array, nil] Initial values. The source array is not retained.
+    # @param source [Array, Integer, nil] Initial values or a size filled with nil. The source array is not retained.
     # @param mode [Symbol] The default value transfer mode.
     # @param compare_by_identity [Boolean] Whether values are compared by identity.
+    # @raise [ArgumentError] If the size is negative.
     def initialize(source = nil, mode: :smart, compare_by_identity: false)
+      source = normalize_vector_source(source)
       raise TypeError, "source must be an Array" unless source.nil? || source.is_a?(Array)
       unless true.equal?(compare_by_identity) || false.equal?(compare_by_identity)
         raise ArgumentError, "compare_by_identity must be true or false"
@@ -176,11 +178,18 @@ module Farce
           replacement = @manager.wrap(replacement, mode:)
           wrapped = true
         end
-        return true if @vector.compare_and_set(index, current, replacement, timeout: remaining_timeout(deadline))
+        return true if @vector.compare_and_set(index, current, replacement, timeout: Clock.remaining(deadline))
         return false if nil.equal?(current) || (deadline && Clock.now >= deadline)
       end
     end
 
+    # (see Farce::Abstract::Vector#wait_until)
+    def wait_until(index, timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      result = Internal.wait_until(@vector, index, timeout:) { |current| yield(@manager.unwrap(current)) }
+      @manager.unwrap(result)
+    end
+
     # (see Farce::Abstract::Vector#wait_until_changed)
     def wait_until_changed(index, expected, timeout: nil)
       deadline = timeout_deadline(timeout)
@@ -189,7 +198,7 @@ module Farce
         current = @vector[index]
         return @manager.unwrap(current) unless values_equal?(current, expected)
         return if deadline && Clock.now >= deadline
-        @vector.wait_until_changed(index, current, timeout: remaining_timeout(deadline))
+        @vector.wait_until_changed(index, current, timeout: Clock.remaining(deadline))
       end
     end
 
@@ -243,11 +252,5 @@ module Farce
       raise ArgumentError, "timeout must be finite and non-negative" unless timeout.finite? && !timeout.negative?
       Clock.now + timeout
     end
-
-    def remaining_timeout(deadline)
-      return unless deadline
-      remaining = deadline - Clock.now
-      remaining.negative? ? 0 : remaining
-    end
   end
 end

data/lib/farce/version.rb

@@ -4,5 +4,5 @@
 
 module Farce
   # @return [String] the current version of Farce
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/lib/farce/walker/definitions.rb

@@ -118,8 +118,19 @@ module Farce
           if !key.equal?(new_key)
             entries << [key, new_key, result]
           elsif !value.equal?(result)
-            until target.compare_and_set(key, value, result)
-              value = target[key]
+            loop do
+              retry_update = false
+              send_to(target, :modify_entry, key, canonical: true) do |present, current|
+                next Internal::MAP_KEEP unless present
+                if Internal.value_changed?(current, value, true)
+                  value = current
+                  retry_update = true
+                  next Internal::MAP_KEEP
+                end
+                result
+              end
+              break unless retry_update
+              # Traverse replacements after releasing the key's update reservation.
               result = walker.visit(value)
             end
           end

data/lib/farce/weak_atom.rb

@@ -100,14 +100,17 @@ module Farce
       matched
     end
 
+    # (see Abstract::Atom#wait_until)
+    def wait_until(timeout: nil, &) = Internal.wait_until(@atom, timeout:, &)
+
     # (see Abstract::Atom#wait_until_changed)
     def wait_until_changed(expected, timeout: nil, &fallback)
       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 fallback&.call if TIMED_OUT.equal?(current)
         return 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 fallback&.call if TIMED_OUT.equal?(result)
       end
     end

data/lib/farce.rb

@@ -429,7 +429,9 @@ module Farce
   end
 
   # Schedules work without waiting for the block to finish.
-  # On CRuby, uses a shared Ractor pool with at most {System.cpu_count} workers.
+  # On CRuby, uses a shared Ractor pool with at most {System.cpu_count} workers by default.
+  # Set {Config}'s `parallel_pool_*` options before creating a scheduler to configure
+  # its worker limits, growth and shrink delays, per-worker task limit, and queue capacity.
   # On JRuby and TruffleRuby, starts a new thread for each task.
   #
   # Without a block, returns the shared scheduler. The CRuby pool starts workers

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: farce
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Konstantin Haase
@@ -114,6 +114,7 @@ files:
 - lib/farce/abstract/pool.rb
 - lib/farce/abstract/port.rb
 - lib/farce/abstract/priority_queue.rb
+- lib/farce/abstract/publisher.rb
 - lib/farce/abstract/queue.rb
 - lib/farce/abstract/scheduler.rb
 - lib/farce/abstract/set.rb
@@ -131,6 +132,14 @@ files:
 - lib/farce/backports.rb
 - lib/farce/class_mirror.rb
 - lib/farce/clock.rb
+- lib/farce/concurrent.rb
+- lib/farce/concurrent/count_down_latch.rb
+- lib/farce/concurrent/cyclic_barrier.rb
+- lib/farce/concurrent/event.rb
+- lib/farce/concurrent/fiber_local_var.rb
+- lib/farce/concurrent/local_var.rb
+- lib/farce/concurrent/thread_local_var.rb
+- lib/farce/concurrent/tuple.rb
 - lib/farce/config.rb
 - lib/farce/counter.rb
 - lib/farce/deduper.rb
@@ -298,6 +307,7 @@ files:
 - lib/farce/internal/mutable_ordered_key_lock_map.rb
 - lib/farce/internal/noncopyable.rb
 - lib/farce/internal/ordered_key_lock_map.rb
+- lib/farce/internal/pool_settings.rb
 - lib/farce/internal/pool_supervisor.rb
 - lib/farce/internal/pool_worker.rb
 - lib/farce/internal/portable_transaction.rb
@@ -349,6 +359,7 @@ files:
 - lib/farce/local/molecule.rb
 - lib/farce/local/pool.rb
 - lib/farce/local/priority_queue.rb
+- lib/farce/local/publisher.rb
 - lib/farce/local/queue.rb
 - lib/farce/local/scheduler.rb
 - lib/farce/local/scoped.rb
@@ -365,6 +376,7 @@ files:
 - lib/farce/lock.rb
 - lib/farce/lru_map.rb
 - lib/farce/map.rb
+- lib/farce/memoize.rb
 - lib/farce/mode_manager.rb
 - lib/farce/mode_manager/smart_rule.rb
 - lib/farce/molecule.rb
@@ -377,6 +389,7 @@ files:
 - lib/farce/proxy/register.rb
 - lib/farce/proxy/supervisor.rb
 - lib/farce/proxy/wrapper.rb
+- lib/farce/publisher.rb
 - lib/farce/queue.rb
 - lib/farce/ractor.rb
 - lib/farce/read_write_lock.rb
@@ -404,6 +417,7 @@ files:
 - lib/farce/strict/molecule.rb
 - lib/farce/strict/port.rb
 - lib/farce/strict/priority_queue.rb
+- lib/farce/strict/publisher.rb
 - lib/farce/strict/queue.rb
 - lib/farce/strict/set.rb
 - lib/farce/strict/sorted_set.rb
@@ -415,6 +429,8 @@ files:
 - lib/farce/strict/weak_map.rb
 - lib/farce/strict/weak_set.rb
 - lib/farce/strict/weak_value_map.rb
+- lib/farce/subscription.rb
+- lib/farce/subscription/definitions.rb
 - lib/farce/system.rb
 - lib/farce/task.rb
 - lib/farce/thread_executor.rb
@@ -452,6 +468,7 @@ files:
 - lib/farce/unshared/molecule.rb
 - lib/farce/unshared/pool.rb
 - lib/farce/unshared/priority_queue.rb
+- lib/farce/unshared/publisher.rb
 - lib/farce/unshared/queue.rb
 - lib/farce/unshared/scheduler.rb
 - lib/farce/unshared/set.rb