farce 0.4.1 → 0.6.0

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/strict/weak_cache.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A weak cache that allows reusing previously generated values without holding strong references to them.
+    # Only shareable keys and values can be used.
+    #
+    # @example
+    #   cache = Farce::Strict::WeakCache.new
+    #   value = cache.store_if_absent(:key) { ExpensiveClass.new.freeze }
+    class WeakCache
+      include Shareable::Delegated
+      include Internal::Inspect
+
+      # Creates a new WeakCache instance if it outperforms {Strict::WeakValueMap} on the current platform.
+      # Otherwise it creates a standard WeakValueMap instance.
+      # @return [WeakCache, Strict::WeakValueMap] The created cache instance.
+      def self.create(...) = Internal.native_weak_maps? ? Strict::WeakValueMap.new(...) : WeakCache.new(...)
+
+      # @param initial_mapping [Hash, Farce::Abstract::Map, #each, nil]
+      #   The entries to store initially. Each iteration must yield a key-value pair.
+      #   Nil creates an empty map.
+      # @param compare_by_identity [Boolean]
+      #   Whether keys use object identity instead of `hash` and `eql?`.
+      def initialize(initial_mapping = nil, compare_by_identity: false)
+        @map = Strict::WeakValueMap.new(initial_mapping, compare_keys_by_identity: compare_by_identity)
+        initialize_cache
+        super()
+      end
+
+      # @api private
+      def marshal_dump = [1, @map]
+
+      # @api private
+      def marshal_load(data)
+        @map, = Internal::MarshalSupport.payload(data, 1)
+        initialize_cache
+        publish_shareable
+      end
+
+      # Retrieves or stores a value for the given key.
+      # The block is called to generate the value if the key is absent.
+      # Concurrent calls for the same key reuse the generated value.
+      # Once that value is collected, a later call generates it again.
+      #
+      # @param key [BasicObject] The key to look up.
+      # @yield Called without arguments when the key is absent.
+      # @yieldreturn [BasicObject] The value to store and return.
+      # @return [BasicObject] The associated value.
+      def store_if_absent(key, &)
+        raise LocalJumpError, "no block given" unless block_given?
+        @cache.store_if_absent(key, &)
+      end
+
+      alias compute_if_absent store_if_absent
+
+      # Store a value only when the key is absent.
+      # Existing nil and false values count as present.
+      # @param key [BasicObject] The key to look up or store.
+      # @param value [BasicObject] The value to store if the key is absent.
+      # @return [BasicObject, nil] The existing value, or nil when a value was inserted.
+      def put_if_absent(key, value)
+        inserted = false
+        previous = store_if_absent(key) do
+          inserted = true
+          value
+        end
+        inserted ? nil : previous
+      end
+
+      # Look up a value without generating it.
+      # @param key [BasicObject] The key to look up.
+      # @return [BasicObject, nil] The associated value, or nil if the key is absent.
+      def [](key) = @cache.fetch(key) { nil } # rubocop:disable Style/RedundantFetchBlock
+
+      # Return a lookup key and its associated value if present.
+      # @param key [BasicObject] The key to look up.
+      # @return [Array(BasicObject, BasicObject), nil] The pair `[key, value]`, or nil if the key is absent.
+      def assoc(key)
+        value = fetch(key) { return nil }
+        [key, value]
+      end
+
+      # Return whether a live entry exists, including entries with nil or false values.
+      # @param key [BasicObject] The key to look up.
+      # @return [Boolean]
+      def key?(key)
+        @cache.fetch(key) { return false }
+        true
+      end
+
+      alias has_key? key?
+      alias include? key?
+      alias member?  key?
+
+      # Look up a value in nested maps or arrays.
+      # @param key [BasicObject] The key to look up.
+      # @param rest [Array<BasicObject>] Additional keys or indices for the nested value.
+      # @return [BasicObject, nil] The nested value, or nil if an intermediate value is absent or nil.
+      def dig(key, *rest)
+        value = self[key]
+        return value if rest.empty? || value.nil?
+        value.dig(*rest)
+      end
+
+      # Return the stored key matching a lookup key.
+      # @param key [BasicObject] The key to look up.
+      # @return [BasicObject, nil] The stored key, or nil if the key is absent.
+      def getkey(key) = @map.getkey(key)
+
+      # Fetch the value associated with a key, using the same missing-key behavior as Hash#fetch.
+      # If both a default and a block are provided, the block takes precedence.
+      #
+      # @overload fetch(key)
+      #   @param key [BasicObject] The key to look up.
+      #   @return [BasicObject] The associated value.
+      #   @raise [KeyError] If the key is absent.
+      #
+      # @overload fetch(key, default)
+      #   @param key [BasicObject] The key to look up.
+      #   @param default [BasicObject] The value to return if the key is absent.
+      #   @return [BasicObject] The associated value or `default`.
+      #
+      # @overload fetch(key)
+      #   @param key [BasicObject] The key to look up.
+      #   @yield [key] Called if the key is absent.
+      #   @yieldparam key [BasicObject] The missing key.
+      #   @yieldreturn [BasicObject] The value to return.
+      #   @return [BasicObject] The associated value or the block result.
+      def fetch(*arguments)
+        unless arguments.length.between?(1, 2)
+          raise ArgumentError, "wrong number of arguments (given #{arguments.length}, expected 1..2)"
+        end
+
+        key, default = arguments
+        warn "block supersedes default value argument", uplevel: 1 if block_given? && arguments.length == 2
+        @cache.fetch(key) do
+          return yield(key) if block_given?
+          return default if arguments.length == 2
+          raise KeyError.new("key not found: #{key.inspect}", receiver: self, key: key)
+        end
+      end
+
+      # Fetch values in the requested order, using {#fetch} for missing keys.
+      # @param keys [Array<BasicObject>] The keys to look up.
+      # @yield [key] Called for each missing key.
+      # @yieldparam key [BasicObject] The missing key.
+      # @yieldreturn [BasicObject] The fallback value, which is not stored.
+      # @return [Array<BasicObject>] The associated values or block results.
+      def fetch_values(*keys, &) = keys.map { fetch(it, &) }
+
+      # Look up values in the requested order, returning nil for missing keys.
+      # @param keys [Array<BasicObject>] The keys to look up.
+      # @return [Array<BasicObject>] The associated values, with nil for missing keys.
+      def values_at(*keys) = keys.map { self[it] }
+
+      # @return [Boolean] Whether keys are compared by identity instead of `hash` and `eql?`.
+      def compare_keys_by_identity? = @map.compare_keys_by_identity?
+
+      # (see #compare_keys_by_identity?)
+      def compare_by_identity? = compare_keys_by_identity?
+
+      # @return [Boolean] Whether keys must be Ractor-shareable, including copied mutable strings.
+      def shareable_keys? = true
+
+      # @return [Boolean] Whether values must be Ractor-shareable.
+      def shareable_values? = true
+
+      # @return [Boolean] Whether keys are referenced weakly.
+      def weak_keys? = false
+
+      # @return [Boolean] Whether values are referenced weakly.
+      def weak_values? = true
+
+      # @api private
+      def inspect_with(inspector)
+        super do
+          yield if block_given?
+          inspector.breakable
+          inspector.group("{", "}") do
+            inspector.breakable ""
+            inspector.seplist(@map, nil, :each) do |key, value|
+              inspector.group { inspector.hash_pair(key, value) }
+            end
+          end
+        end
+      end
+
+      alias to_s inspect
+
+      private
+
+      def initialize_cache = @cache = Internal.native_weak_maps? ? @map : Internal::WeakCacheMirror.new(@map)
+      def freeze_backend   = @map
+    end
+  end
+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,18 +20,21 @@ 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)
-      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"
-      end
+      source = normalize_vector_source(source)
+      raise TypeError, "source must be an Array" unless source.nil? || Integer === source || source.is_a?(Array)
 
-      @compare_by_identity = compare_by_identity
+      @compare_by_identity = compare_by_identity ? true : false
       @manager = ModeManager.new(mode:)
-      @vector = Internal::Vector.new(source&.map { @manager.wrap(it) }, compare_by_identity: true)
+      if source && !(Integer === source)
+        source = source.map { @manager.wrap(it) }
+        raise TypeError, "source must be an Array" unless source.nil? || source.is_a?(Array)
+      end
+      @vector = Internal::Vector.new_for_modes(source)
       super()
     end
 
@@ -51,7 +54,7 @@ module Farce
     def marshal_load(data)
       entries, @manager, identity, frozen = Internal::MarshalSupport.payload(data, 4)
       @compare_by_identity = identity
-      @vector = Internal::Vector.new(compare_by_identity: true)
+      @vector = Internal::Vector.new_for_modes(nil)
       publish_shareable
       entries.each { @vector.push(Internal::MarshalSupport.restore_value(it)) }
       Internal::MarshalSupport.freeze(self, frozen)
@@ -176,11 +179,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 +199,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 +253,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.6.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
@@ -179,6 +190,24 @@ module Farce
       super(object, walker)
     end
 
+    define(Struct) do |object, walker|
+      result = walker.update(object, object.to_a) do |target, results|
+        results.each_with_index { |value, index| target[index] = value unless target[index].equal?(value) }
+        target
+      end
+      super(result, walker)
+    end
+
+    define(Range) do |object, walker|
+      names = object.instance_variables
+      values = [object.begin, object.end, *names.map { object.instance_variable_get(it) }]
+      walker.update(object, values) do |target, results|
+        names.each_with_index { |name, index| target.instance_variable_set(name, results[index + 2]) }
+        Internal.initialize_range(target, results[0], results[1], object.exclude_end?)
+        target
+      end
+    end
+
     define(Data) do |object, walker|
       walker.rebuild_data(object)
     end