farce 0.0.1.alpha2-x86_64-linux-gnu

data/lib/farce/shareable.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Mixin that makes sure instances are shareable between Ractors.
+  #
+  # @example
+  #   class MyClass
+  #     include Farce::Shareable
+  #   end
+  #
+  #   object = MyClass.new
+  #   Ractor.shareable?(object) # => true
+  module Shareable
+    # A structurally frozen wrapper whose logical frozen state is owned by its backend.
+    # The including class must implement a private `freeze_backend` method.
+    #
+    # @example Delegate freezing to a counter
+    #   class Tally
+    #     include Farce::Shareable::Delegated
+    #
+    #     def initialize
+    #       @counter = Farce::Counter.new
+    #       super
+    #     end
+    #
+    #     def increment = @counter.increment
+    #     private def freeze_backend = @counter
+    #   end
+    #
+    #   tally = Tally.new
+    #   tally.frozen?  # => false
+    #   tally.freeze
+    #   tally.increment # raises FrozenError in the counter
+    module Delegated
+      include Shareable
+      include Internal::Freeze::Delegated
+    end
+
+    # A structurally frozen wrapper with one shared logical freeze-state flag.
+    # Mutating methods must call `check_frozen!` before changing state.
+    #
+    # @example Track freezing separately from storage
+    #   class Tally
+    #     include Farce::Shareable::Tracked
+    #
+    #     def initialize
+    #       @counter = Farce::Counter.new
+    #       super
+    #     end
+    #
+    #     def increment
+    #       check_frozen!
+    #       @counter.increment
+    #     end
+    #   end
+    #
+    #   tally = Tally.new
+    #   tally.frozen? # => false
+    #   tally.freeze
+    #   tally.increment # raises FrozenError for the tally
+    module Tracked
+      include Shareable
+      include Internal::Freeze::Tracked
+    end
+
+    # A structurally frozen service object that does not support logical freezing.
+    #
+    # @example Publish a service that must remain mutable
+    #   class Inbox
+    #     include Farce::Shareable::Unfreezable
+    #
+    #     def initialize
+    #       @queue = Farce::Queue.new
+    #       super
+    #     end
+    #
+    #     def push(value) = @queue.push(value)
+    #   end
+    #
+    #   inbox = Inbox.new
+    #   inbox.frozen? # => false
+    #   inbox.freeze  # raises TypeError
+    module Unfreezable
+      include Shareable
+      include Internal::Freeze::Unfreezable
+    end
+
+    # A native object that publishes its initialized payload without structural freezing.
+    # Requires a backend that already implements safe publication and frozen checks.
+    # Including this module alone cannot make an ordinary Ruby object shareable.
+    # Native subclasses must not add Ruby instance variables on CRuby.
+    #
+    # @example Extend a counter while preserving native publication
+    #   class Tally < Farce::Counter
+    #     include Farce::Shareable::Native
+    #
+    #     def increment_twice = increment(2)
+    #   end
+    #
+    #   tally = Tally.new
+    #   tally.frozen? # => false
+    #   Ractor.shareable?(tally) # => true
+    #   tally.freeze
+    #   tally.increment_twice # raises FrozenError
+    module Native
+      include Shareable
+      include Internal::Freeze::Native
+    end
+
+    # An immutable object whose structural and logical frozen states are the same.
+    # Set instance variables before calling `super` from `initialize`.
+    #
+    # @example Publish an immutable value
+    #   class Point
+    #     include Farce::Shareable::Immutable
+    #     attr_reader :x, :y
+    #
+    #     def initialize(x, y)
+    #       @x, @y = x, y
+    #       super()
+    #     end
+    #   end
+    #
+    #   point = Point.new(1, 2)
+    #   point.frozen? # => true
+    #   Ractor.shareable?(point) # => true
+    module Immutable
+      include Shareable
+      include Internal::Freeze::Immutable
+    end
+
+    # Make sure to call `super` if you include this module.
+    # Accepts any arguments and passes them on to the superclass initializer.
+    def initialize(...)
+      super
+      publish_shareable
+    end
+
+    # @return [Boolean] true
+    # @see Unshareable#ractor_shareable?
+    def ractor_shareable? = true
+
+    private
+
+    # Publish a Ruby facade without dispatching its logical `freeze` method.
+    def publish_shareable = Internal::Freeze.publish(self)
+  end
+end

data/lib/farce/signal.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable notification signal for changes to separately synchronized state.
+  # Broadcast after updating the state. Waiters check that state again after each notification.
+  # A broadcast wakes all current waiters and advances the signal's generation.
+  #
+  # @example Waiting for a resource
+  #   signal    = Farce::Signal.new
+  #   resources = Farce::Strict::Queue.new
+  #   producer  = Thread.new do
+  #     resources.push(:resource)
+  #     signal.broadcast
+  #   end
+  #   resource = signal.wait_until(timeout: 1.0) { resources.try_pop }
+  #   producer.join
+  #   resource # => :resource, or nil if the timeout expires
+  #
+  class Signal
+    include Internal::Noncopyable
+    include Internal::Inspect
+    include Shareable::Unfreezable
+
+    def initialize
+      @signal = Internal::Signal.new
+      super
+    end
+
+    # Read the current generation. Take this snapshot before checking external state.
+    # @return [Integer] the current generation, initially zero
+    def generation = @signal.generation
+
+    # Advance the generation and wake all current waiters.
+    # @return [Integer] the new generation
+    def broadcast = @signal.broadcast
+
+    # @return [Integer] the number of callers currently waiting
+    def num_waiting = @signal.num_waiting
+
+    # Wait for the generation to change. Without a snapshot, wait for the next broadcast.
+    # Return immediately if the supplied generation has already changed.
+    # @param observed [Integer, nil] a generation snapshot, or nil to take a snapshot now
+    # @param timeout [Numeric, nil] the maximum seconds to wait, or nil to wait indefinitely
+    # @yield called without arguments when the timeout expires
+    # @return [Integer, BasicObject, nil] the changed generation, or the fallback result or nil on timeout
+    def wait(observed = nil, timeout: nil, &) = @signal.wait(observed, timeout:, &)
+
+    # Check a condition immediately, then after broadcasts while it remains truthy.
+    # Uses the same timeout budget and notification handling as {#wait_until}.
+    # @param timeout [Numeric, nil] the total seconds available, or nil to wait indefinitely
+    # @yield checks the condition
+    # @yieldreturn [BasicObject] a truthy value to keep waiting, or nil or false to stop
+    # @return [true, nil] true when the condition becomes false, or nil on timeout
+    # @raise [LocalJumpError] if no block is given
+    def wait_while(timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      wait_until(timeout:) { !yield }
+    end
+
+    # Check a condition immediately, then check again after broadcasts until it succeeds.
+    # Take a generation snapshot before every check so a broadcast during the check is not missed.
+    # The block runs in the caller without holding a signal lock. Synchronize access to shared state
+    # inside the block, and claim the resource there if another waiter could consume it.
+    #
+    # One timeout budget covers all checks and waits. The block is not interrupted when time expires.
+    # A timeout of zero checks once without waiting. Exceptions from the block propagate to the caller.
+    #
+    # @param timeout [Numeric, nil] the total seconds available, or nil to wait indefinitely
+    # @yield checks or claims the resource
+    # @yieldreturn [BasicObject, nil, false] a truthy result on success, or nil or false to keep waiting
+    # @return [BasicObject, nil] the first truthy block result, or nil on timeout
+    # @raise [LocalJumpError] if no block is given
+    # @raise [ArgumentError] if the timeout is negative or not finite
+    def wait_until(timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      Internal.with_timeout(timeout) do |_, deadline|
+        observed = generation
+        result   = yield
+        return result if result
+
+        remaining = deadline - Clock.now if deadline
+        return if remaining && !remaining.positive?
+        return unless wait(observed, timeout: remaining)
+      end
+    end
+
+    # @api private
+    def inspect_with(inspector)
+      super do
+        inspector.attributes({ generation:, num_waiting: })
+        yield if block_given?
+      end
+    end
+  end
+end

data/lib/farce/sorted_set.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable concurrent set maintained in ascending order.
+  # Membership uses `<=>`. Comparator-equivalent elements occupy one slot.
+  # Transfer modes have the same behavior and restrictions as Farce::Set.
+  #
+  # @example Traverse priorities in order
+  #   priorities = Farce::SortedSet[30, 10, 20]
+  #   priorities.to_a # => [10, 20, 30]
+  class SortedSet < Farce::Abstract::SortedSet
+    include Shareable::Delegated
+
+    # The default transfer mode for elements.
+    # @return [Symbol] The configured transfer mode.
+    def mode = @manager.mode
+
+    protected
+
+    def value_modes? = true
+
+    private
+
+    def initialize_value_mode(mode)
+      mode = :copy if UNDEFINED.equal?(mode)
+      @manager = ModeManager.new(mode:)
+    end
+
+    def new_map(entries = nil, compare_keys_by_identity: false, **)
+      raise ArgumentError, "sorted sets do not support identity comparison" if compare_keys_by_identity
+      Farce::Strict::TreeMap.new(entries)
+    end
+  end
+end

data/lib/farce/strict/atom.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable atomic reference that strongly retains shareable values directly.
+    # Values are stored without envelope wrapping or transfer modes.
+    #
+    # @example Updating a counter atomically
+    #   counter = Farce::Strict::Atom.new(0)
+    #   counter.update { |count| count + 1 } # => 1
+    #   counter.compare_and_set(1, 2)       # => true
+    #   counter.value                      # => 2
+    #
+    # @example Keeping an immutable snapshot
+    #   snapshot = [1, 2, 3].freeze
+    #   atom = Farce::Strict::Atom.new(snapshot)
+    #   atom.value.equal?(snapshot) # => true
+    #   atom.update { |items| (items + [4]).freeze } # => [1, 2, 3, 4]
+    class Atom < Abstract::Atom
+      include Shareable::Delegated
+
+      # @param value [BasicObject, nil] the initial shareable value
+      # @param compare_by_identity [Boolean] whether comparisons use object identity instead of equality
+      def initialize(value = nil, compare_by_identity: false)
+        @atom = Internal::StrictAtom.new(value, compare_by_identity:)
+        super()
+      end
+
+      private def freeze_backend = @atom
+    end
+  end
+end

data/lib/farce/strict/counter.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # Alias for {Farce::Counter} so {Strict} can be more easily used as a namespace.
+    Counter = Farce::Counter
+  end
+end

data/lib/farce/strict/exchanger.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable rendezvous that exchanges shareable values directly.
+    # Values retain their identity and envelopes are returned unopened.
+    class Exchanger < Abstract::Exchanger
+      include Shareable::Unfreezable
+
+      def initialize
+        @exchanger = Internal::Exchanger.new
+        super
+      end
+
+      # (see Abstract::Exchanger#exchange)
+      # @raise [Ractor::IsolationError] if the offered value is not Ractor-shareable
+      def exchange(offered, timeout: nil, &)
+        raise Ractor::IsolationError, "value must be Ractor-shareable" unless Ractor.shareable?(offered)
+        super
+      end
+    end
+  end
+end

data/lib/farce/strict/flag.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # Alias for {Farce::Flag} so {Strict} can be more easily used as a namespace.
+    Flag = Farce::Flag
+  end
+end

data/lib/farce/strict/lazy.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A shareable lazy value that retains its shareable result directly.
+    # The factory runs once, even when threads or Ractors access it concurrently.
+    # A failed factory or an unshareable result can be retried on the next access.
+    #
+    # @example Compute one shared snapshot
+    #   lazy = Farce::Strict::Lazy.new { [:ready].freeze }
+    #   lazy.value # => [:ready]
+    class Lazy < Abstract::Lazy
+      include Shareable::Tracked
+
+      # Resolve and freeze the slot without freezing the result.
+      # @return [self]
+      def freeze
+        value
+        internal_atom.freeze
+        super
+      end
+    end
+  end
+end

data/lib/farce/strict/lazy_ref.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # @!parse
+    #   # A {Reference} for a {Strict::Lazy} value.
+    #   # Delegates to the result after computing it on first access.
+    #   # Calling `freeze` resolves and freezes the target.
+    #   #
+    #   # @example
+    #   #   reference = Farce::Strict::LazyRef.new { [:ready].freeze }
+    #   #   reference.first # => :ready
+    #   class LazyRef < Farce::Reference
+    #     # @overload initialize(factory)
+    #     #   @param factory [Class, Proc, #call] the factory for the lazy value, which must be shareable
+    #     # @overload initialize(self: nil)
+    #     #   @param self [BasicObject] the receiver to bind to the block, which must be shareable
+    #     #   @yield computes the value on first access
+    #     #   @yieldreturn [BasicObject] the computed result
+    #     def initialize(...) = nil
+    #   end
+    LazyRef = Reference[Farce::Strict::Lazy]
+  end
+end

data/lib/farce/strict/lease.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable lease that stores a shareable resource directly.
+    # Construction and checkin reject non-shareable resources without freezing them.
+    # Checkout coordinates callers. Other references remain usable, so callers
+    # must honor the checkout when accessing a mutable resource.
+    #
+    # @example Coordinating several changes to shareable state
+    #   lease = Farce::Strict::Lease.new { Farce::Strict::Map.new }
+    #   lease.checkout do |state|
+    #     state[:status] = :ready
+    #     state[:generation] = 1
+    #   end
+    #   lease.checkout { |state| state[:status] } # => :ready
+    class Lease < Abstract::Lease
+      include Shareable::Unfreezable
+
+      private
+
+      def new_internal_lease(resource) = Internal::StrictLease.new(resource)
+    end
+  end
+end

data/lib/farce/strict/lease_map.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable map that stores independently leased shareable resources directly.
+    # Initial resources, insertions, and replacements must be shareable. They are
+    # not automatically frozen. Other references remain usable, so callers must
+    # honor the checkout when accessing mutable resources.
+    #
+    # @example Updating shareable resources in an automatic lease scope
+    #   leases = Farce::Strict::LeaseMap.new do
+    #     { primary: Farce::Strict::Map.new, replica: Farce::Strict::Map.new }
+    #   end
+    #   leases.auto_lease do
+    #     leases[:primary][:status] = :ready
+    #     leases[:replica][:status] = :ready
+    #   end
+    #   leases.checkout(:primary) { |state| state[:status] } # => :ready
+    class LeaseMap < Abstract::LeaseMap
+      include Shareable::Unfreezable
+
+      def shareable_values? = true
+
+      private
+
+      def new_internal_lease_map(mapping)
+        Internal::StrictLeaseMap.new(mapping, lease_class: Farce::Strict::Lease, registry_class: Farce::Strict::Map)
+      end
+    end
+  end
+end

data/lib/farce/strict/lease_pool.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable pool that stores shareable resources directly.
+    # Factory results and checkin replacements must be shareable. They are not
+    # automatically frozen. Other references remain usable during checkout,
+    # so callers must honor the checkout when accessing mutable resources.
+    #
+    # @example Reusing shareable resources with bounded concurrency
+    #   pool = Farce::Strict::LeasePool.new(max_size: 2) { Farce::Strict::Map.new }
+    #   pool.checkout { |state| state[:uses] = (state[:uses] || 0) + 1 }
+    #   pool.checkout { |state| state[:uses] } # => 1
+    class LeasePool < Abstract::LeasePool
+      include Shareable::Unfreezable
+
+      private
+
+      def prepare_factory(factory)
+        Ractor.shareable?(factory) ? factory : Ractor.shareable_proc(&factory)
+      end
+
+      def new_internal_pool(max_size) = Internal::StrictLeasePool.new(max_size)
+    end
+  end
+end

data/lib/farce/strict/lfu_map.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable LFU map that stores shareable values directly.
+    class LFUMap < Abstract::LFUMap
+      include Shareable::Delegated
+
+      # (see Abstract::Map#shareable_keys?)
+      def shareable_keys? = true
+
+      # (see Abstract::Map#shareable_values?)
+      def shareable_values? = true
+
+      private
+
+      def new_bounded_map(...) = Internal::StrictLFUMap.new(...)
+      def freeze_backend       = internal_map
+
+      def new_key_locks(compare_keys_by_identity:)
+        Internal::KeyLockMap.new(registry_class: Farce::Strict::Map, compare_keys_by_identity:)
+      end
+    end
+  end
+end

data/lib/farce/strict/lru_map.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable LRU map that stores shareable values directly.
+    # Keys must be shareable, except equality-mode mutable strings that can be snapshotted.
+    class LRUMap < Abstract::LRUMap
+      include Shareable::Delegated
+
+      # (see Abstract::Map#shareable_keys?)
+      def shareable_keys? = true
+
+      # (see Abstract::Map#shareable_values?)
+      def shareable_values? = true
+
+      private
+
+      def new_bounded_map(...) = Internal::StrictLRUMap.new(...)
+      def freeze_backend       = internal_map
+
+      def new_key_locks(compare_keys_by_identity:)
+        Internal::KeyLockMap.new(registry_class: Farce::Strict::Map, compare_keys_by_identity:)
+      end
+    end
+  end
+end

data/lib/farce/strict/map.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable concurrent map that stores shareable keys and values directly.
+    # Updates on different keys can run concurrently.
+    #
+    # Clearing the map invalidates unfinished updates so they cannot restore removed entries.
+    #
+    # `dup` and `clone` copy entries into independent storage while sharing stored values.
+    # `dup` and ordinary `clone` remain Ractor-shareable.
+    #
+    # @example Atomically counting occurrences
+    #   counts = Farce::Strict::Map.new
+    #   counts.upsert(:ruby, 1) { |count| count + 1 } # => 1
+    #   counts.upsert(:ruby, 1) { |count| count + 1 } # => 2
+    class Map < Abstract::ConcurrentMap
+      include Shareable::Delegated
+
+      # @!macro map_initialization
+      def initialize(
+        initial_mapping = nil,
+        normalize_keys: nil,
+        compare_by_identity: false,
+        compare_keys_by_identity: compare_by_identity,
+        compare_values_by_identity: compare_by_identity
+      )
+        initial_mapping = convert_entries(initial_mapping)
+        restoring  = Internal::KeyNormalizer.restoration?(normalize_keys)
+        normalizer = Internal::KeyNormalizer.build(normalize_keys, shareable: true)
+        populate   = initial_mapping && ((normalizer && !restoring) || !initial_mapping.is_a?(Hash))
+        @map       = Internal::StrictMap.new(
+          populate ? nil : initial_mapping,
+          compare_by_identity:,
+          compare_keys_by_identity:,
+          compare_values_by_identity:,
+        )
+        Internal::KeyNormalizer.install_concurrent(self, normalizer) unless restoring
+        initial_mapping.each { |key, value| self[key] = value } if populate
+        Internal::KeyNormalizer.install_concurrent(self, normalizer) if restoring
+        super()
+      end
+
+      def shareable_keys? = true
+      def shareable_values? = true
+
+      private def freeze_backend = internal_map
+
+      Internal.prepare_map_access(self, :strict)
+    end
+  end
+end

data/lib/farce/strict/molecule.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable record whose atoms retain only shareable values.
+    # Use {Abstract::Molecule.define} to declare named fields.
+    # Explicitly supplied atoms keep their own storage and comparison policies.
+    class Molecule < Abstract::Molecule
+      include Shareable
+
+      private def create_atom(_, value) = Atom.new(value, compare_by_identity: compare_by_identity?)
+    end
+  end
+end

data/lib/farce/strict/port.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable port that accepts shareable messages directly.
+    # Messages retain their identity and envelopes are returned unopened.
+    # Only the creating Ractor can receive messages or close the port.
+    #
+    # @example Receive an already prepared message
+    #   port    = Farce::Strict::Port.new
+    #   message = [:ready, 42].freeze
+    #   port << message
+    #   port.receive.equal?(message) # => true
+    #   port.close
+    #
+    # @!method initialize
+    #   Creates a port without transfer modes.
+    class Port < Internal::Port
+      include Abstract::Port
+
+      # @!visibility private
+      # (see #initialize)
+      # CRuby 3.4's backend also accepts an existing port or Ractor.
+      # Keep construction argument-free on every runtime.
+      def self.new = super # rubocop:disable Lint/UselessMethodDefinition
+
+      # (see Abstract::Port#send)
+      # @raise [Farce::Ractor::IsolationError] if the message is not Ractor-shareable
+      def send(message)
+        raise Ractor::IsolationError, "value must be Ractor-shareable" unless Ractor.shareable?(message)
+        super
+      end
+
+      # @return [String] a string representation of the port
+      def inspect = super.sub(/\A#<.+? (?=(?:to|id):#?\d+)/, "#<Farce::Strict::Port ")
+    end
+  end
+end