farce 0 → 0.1.0

data/lib/farce/local/lease.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable lease with one independently initialized resource in each scope.
+    #
+    # @example Keeping an independent object in each Fiber
+    #   lease = Farce::Local::Lease.new(scope: :fiber) { { name: :initial } }
+    #   lease.checkout { |state| state[:name] = :parent }
+    #
+    #   Fiber.new do
+    #     lease.checkout { |state| state[:name] = :child }
+    #   end.resume # => :child
+    #
+    #   lease.checkout { |state| state[:name] } # => :parent
+    class Lease < Abstract::Lease
+      include Shareable::Unfreezable
+      include Scoped
+
+      # Create a lease that initializes once on first use in each scope.
+      # @!macro scopes
+      # @param scope [Symbol] the scope of the lease
+      # @yield builds the resource for each initialized scope
+      # @yieldreturn [BasicObject] the initial resource for that scope
+      def initialize(scope: :ractor, &initializer)
+        raise ArgumentError, "a resource constructor block is required" unless initializer
+
+        @initializer = Ractor.shareable?(initializer) ? initializer : Ractor.shareable_proc(&initializer)
+        super(scope:)
+      end
+
+      # (see Farce::Abstract::Lease#checkout)
+      def checkout(timeout: nil, &block)
+        deadline = timeout_deadline(timeout)
+        lease    = scoped_lease(timeout: remaining_timeout(deadline))
+        raise TimeoutError, "lease checkout timed out" unless lease
+
+        timeout = remaining_timeout(deadline)
+        block ? lease.checkout(timeout:, &block) : lease.checkout(timeout:)
+      end
+
+      # (see Farce::Abstract::Lease#try_checkout)
+      def try_checkout(&block)
+        lease = scoped_lease(wait: false)
+        return unless lease
+
+        block ? lease.try_checkout(&block) : lease.try_checkout
+      end
+
+      private
+
+      def eager_scoped_value? = false
+      def new_scoped_value    = Internal::LeaseInitialization.new
+      def internal_lease      = scoped_lease
+      def scoped_lease(**)    = scoped_value.fetch(**) { Internal::UnsharedLease.new(@initializer.call) }
+
+      def timeout_deadline(timeout)
+        return if timeout.nil?
+
+        timeout = Float(timeout)
+        unless timeout.finite? && !timeout.negative?
+          raise ArgumentError, "timeout must be a finite, non-negative number or nil"
+        end
+        Clock.now + timeout
+      end
+
+      def remaining_timeout(deadline)
+        return unless deadline
+
+        remaining = deadline - Clock.now
+        remaining.positive? ? remaining : 0
+      end
+    end
+  end
+end

data/lib/farce/local/lease_map.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable lease map with independently initialized resources in each scope.
+    #
+    # @example Keeping independent resources in each Fiber
+    #   leases = Farce::Local::LeaseMap.new(scope: :fiber) { { jobs: [] } }
+    #   leases.checkout(:jobs) { |jobs| jobs << :parent }
+    #   Fiber.new { leases.checkout(:jobs, &:dup) }.resume # => []
+    #   leases.checkout(:jobs, &:dup) # => [:parent]
+    class LeaseMap < Abstract::LeaseMap
+      include Shareable::Unfreezable
+      include Scoped
+
+      # Create a map that initializes once on first use in each scope.
+      # @!macro scopes
+      # @param scope [Symbol] the scope of the lease map
+      # @yield builds the initial mapping for each initialized scope
+      # @yieldreturn [Hash, Farce::Abstract::Map, #each] the initial mapping for that scope
+      def initialize(scope: :ractor, normalize_keys: nil, &initializer)
+        raise ArgumentError, "a resource constructor block is required" unless initializer
+
+        @initializer = Ractor.shareable?(initializer) ? initializer : Ractor.shareable_proc(&initializer)
+        super(scope:, normalize_keys:)
+      end
+
+      private
+
+      def eager_scoped_value? = false
+      def new_scoped_value    = Internal::LeaseInitialization.new
+      def internal_lease_map  = scoped_lease_map
+
+      def checkout_canonical(key, missing_key:, timeout: nil, &)
+        deadline = timeout_deadline(timeout)
+        map      = scoped_lease_map(timeout: remaining_timeout(deadline))
+        raise TimeoutError, "lease checkout timed out" unless map
+
+        map.checkout(key, timeout: remaining_timeout(deadline), receiver: self, missing_key:, &)
+      end
+
+      def try_checkout_canonical(key, missing_key:, &)
+        map = scoped_lease_map(wait: false)
+        return unless map
+
+        map.try_checkout(key, receiver: self, missing_key:, &)
+      end
+
+      def scoped_lease_map(**)
+        scoped_value.fetch(**) do
+          mapping = prepare_initial_resources(@initializer.call, @key_normalizer)
+          Internal::LeaseMap.new(
+            mapping,
+            lease_class:    Farce::Unshared::Lease,
+            registry_class: Farce::Unshared::Map,
+          )
+        end
+      end
+
+      def timeout_deadline(timeout)
+        return if timeout.nil?
+
+        timeout = Float(timeout)
+        unless timeout.finite? && !timeout.negative?
+          raise ArgumentError, "timeout must be a finite, non-negative number or nil"
+        end
+        Clock.now + timeout
+      end
+
+      def remaining_timeout(deadline)
+        return unless deadline
+
+        remaining = deadline - Clock.now
+        remaining.positive? ? remaining : 0
+      end
+    end
+  end
+end

data/lib/farce/local/lease_pool.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable pool with independent capacity and resources in each scope.
+    #
+    # @example Keeping separate pools in each Fiber
+    #   pool = Farce::Local::LeasePool.new(scope: :fiber, max_size: 1) { [] }
+    #   pool.checkout { |items| items << :parent }
+    #
+    #   Fiber.new { pool.checkout(&:dup) }.resume # => []
+    #   pool.checkout(&:dup) # => [:parent]
+    class LeasePool < Abstract::LeasePool
+      include Shareable::Unfreezable
+      include Scoped
+
+      # Construct an empty pool in each scope.
+      # @!macro scopes
+      # @param scope [Symbol] the scope of the pool
+      # @param max_size [Integer] the maximum number of resources in each scope
+      # @yield builds a resource in the requesting scope
+      # @yieldreturn [BasicObject] a new resource
+      def initialize(max_size:, scope: :ractor, &factory)
+        validate_configuration!(max_size, factory)
+        @max_size = max_size
+        @factory  = Ractor.shareable?(factory) ? factory : Ractor.shareable_proc(&factory)
+        super(scope:, max_size:)
+      end
+
+      private
+
+      def new_scoped_value(max_size:) = Internal::UnsharedLeasePool.new(max_size)
+      def internal_pool = scoped_value
+    end
+  end
+end

data/lib/farce/local/lfu_map.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable LFU map with independent mutable storage and capacity in each scope.
+    #
+    # @!method initialize(entries = nil, max_size:, scope: :ractor, **options)
+    #   @!macro scopes
+    #   @param entries [Hash, Array<Array(BasicObject, BasicObject)>, Abstract::Map, #each, nil]
+    #     Initial entries for each new scope. Entries are stored sequentially and may be evicted.
+    #   @param max_size [Integer] Maximum entries retained by each new scoped map.
+    #   @param scope [Symbol] The scope of the LFU map.
+    #   @return [LFUMap]
+    class LFUMap < Abstract::LFUMap
+      include Shareable::Tracked
+      include Scoped::Tracked
+
+      State = Data.define(:map, :key_locks)
+      private_constant :State
+
+      protected
+
+      def internal_map = scoped_value.map
+
+      private
+
+      def freeze_scoped_value(state) = state.map.freeze
+
+      def new_copied_scoped_value(map)
+        locks = Internal::KeyLockMap.new(
+          registry_class:           Farce::Unshared::Map,
+          compare_keys_by_identity: map.compare_keys_by_identity?,
+        )
+        State.new(map, locks)
+      end
+
+      def with_key_lock(key, &) = scoped_value.key_locks.synchronize(key, &)
+
+      def new_scoped_value(
+        entries = nil,
+        compare_by_identity: false,
+        compare_keys_by_identity: compare_by_identity,
+        **
+      )
+        entries = convert_entries(entries)
+        map     = Internal::LFUMap.new(compare_by_identity:, compare_keys_by_identity:, **)
+        locks   = Internal::KeyLockMap.new(registry_class: Farce::Unshared::Map, compare_keys_by_identity:)
+        entries&.each { map[_1] = _2 }
+        State.new(map, locks)
+      end
+    end
+  end
+end

data/lib/farce/local/lru_map.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable LRU map with independent mutable storage and capacity in each scope.
+    #
+    # @!method initialize(entries = nil, max_size:, scope: :ractor, **options)
+    #   @!macro scopes
+    #   @param entries [Hash, Array<Array(BasicObject, BasicObject)>, Abstract::Map, #each, nil]
+    #     Initial entries for each new scope. Entries are stored sequentially and may be evicted.
+    #   @param max_size [Integer] Maximum entries retained by each new scoped map.
+    #   @param scope [Symbol] The scope of the LRU map.
+    #   @option options [Boolean] compare_by_identity (false) whether keys and values are compared by identity
+    #   @option options [Boolean] compare_keys_by_identity (compare_by_identity) whether keys are compared by identity
+    #   @option options [Boolean] compare_values_by_identity (compare_by_identity)
+    #     whether values are compared by identity
+    #   @return [LRUMap]
+    class LRUMap < Abstract::LRUMap
+      include Shareable::Tracked
+      include Scoped::Tracked
+
+      State = Data.define(:map, :key_locks)
+      private_constant :State
+
+      protected
+
+      def internal_map = scoped_value.map
+
+      private
+
+      def freeze_scoped_value(state) = state.map.freeze
+
+      def new_copied_scoped_value(map)
+        locks = Internal::KeyLockMap.new(
+          registry_class:           Farce::Unshared::Map,
+          compare_keys_by_identity: map.compare_keys_by_identity?,
+        )
+        State.new(map, locks)
+      end
+
+      def with_key_lock(key, &) = scoped_value.key_locks.synchronize(key, &)
+
+      def new_scoped_value(
+        entries = nil,
+        compare_by_identity: false,
+        compare_keys_by_identity: compare_by_identity,
+        **
+      )
+        entries = convert_entries(entries)
+        map     = Internal::LRUMap.new(compare_by_identity:, compare_keys_by_identity:, **)
+        entries&.each { map[_1] = _2 }
+        locks = Internal::KeyLockMap.new(
+          registry_class:           Farce::Unshared::Map,
+          compare_keys_by_identity:,
+        )
+        State.new(map, locks)
+      end
+    end
+  end
+end

data/lib/farce/local/map.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable map with independent mutable storage in each scope.
+    #
+    # @!parse
+    #   class Map
+    #     # @!macro map_initialization
+    #     # Initial entries are reused for each new scope.
+    #     # @!macro scopes
+    #     # @param scope [Symbol] The scope of the map. Defaults to `:ractor`.
+    #     # @return [Map]
+    #     def initialize(
+    #       initial_mapping = nil,
+    #       scope: :ractor,
+    #       normalize_keys: nil,
+    #       compare_by_identity: false,
+    #       compare_keys_by_identity: compare_by_identity,
+    #       compare_values_by_identity: compare_by_identity
+    #     )
+    #     end
+    #   end
+    class Map < Abstract::ConcurrentMap
+      include Shareable::Tracked
+      include Scoped::Tracked
+
+      protected
+
+      def internal_map = scoped_value
+
+      private
+
+      def new_scoped_value(entries = nil, **)
+        unless @key_normalizer || Internal::KeyNormalizer.canonical_entries?(entries)
+          return Internal::UnsharedMap.new(entries, **)
+        end
+
+        map = Internal::UnsharedMap.new(nil, **)
+        entries&.each { map[_1] = _2 }
+        Internal::KeyNormalizer.wrap_concurrent(map, @key_normalizer)
+      end
+    end
+  end
+end

data/lib/farce/local/molecule.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable record with independent field values in each selected scope.
+    # Use {Abstract::Molecule.define} to declare named fields.
+    # Explicitly supplied atoms keep their own storage and comparison policies.
+    class Molecule < Abstract::Molecule
+      include Shareable
+
+      # Create a record class with a default scope for newly created field atoms.
+      # @!macro scopes
+      # @param fields [Array<Symbol, String>] the field names
+      # @param scope [Symbol, nil] the default scope, or nil to inherit
+      # @param compare_by_identity [Boolean, nil] the default comparison policy
+      # @return [Class<Molecule>]
+      def self.define(*fields, scope: nil, **)
+        raise ArgumentError, "Invalid scope: #{scope.inspect}" unless scope.nil? || Farce::SCOPES.include?(scope)
+
+        subclass = super(*fields, **)
+        subclass.class_eval "def self.default_scope = #{scope.inspect}", __FILE__, __LINE__ unless scope.nil?
+        subclass
+      end
+
+      # @return [Symbol] the default scope for new records
+      def self.default_scope = :ractor
+
+      # Initialize fields using this variant's atoms.
+      # @!macro scopes
+      # @param scope [Symbol] the scope for new field atoms, defaulting to the record class scope
+      # @see Abstract::Molecule#initialize
+      def initialize(*, scope: self.class.default_scope, **)
+        @scope = scope
+        super(*, **)
+      end
+
+      # @return [Symbol] the scope used by newly created field atoms
+      attr_reader :scope
+
+      private def create_atom(_, value) = Atom.new(value, scope:, compare_by_identity: compare_by_identity?)
+    end
+  end
+end

data/lib/farce/local/priority_queue.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable priority queue with independent mutable storage in each scope.
+    class PriorityQueue < Abstract::PriorityQueue
+      include Shareable::Unfreezable
+      include Scoped
+
+      # @overload initialize(capacity: nil, default_priority: 0, order: :ascending, scope: :ractor, track_age: false)
+      #   @!macro scopes
+      #   @param capacity [Integer, nil] the maximum number of values, or nil for an unbounded queue
+      #   @param default_priority [BasicObject] the shareable priority used when none is passed to push or try_push
+      #   @param order [:ascending, :descending] the priority order
+      #   @param scope [Symbol] the scope of the priority queue
+      #   @param track_age [Boolean] whether to track enqueue age and queue generations
+      #   @param fiber_wait [:auto, :io, :block] how scheduled fibers wait on CRuby
+      #   @return [PriorityQueue]
+      def initialize(
+        capacity: nil, default_priority: 0, order: :ascending, scope: :ractor,
+        track_age: false, fiber_wait: :auto
+      )
+        unless Ractor.shareable?(default_priority)
+          raise Ractor::IsolationError, "default_priority must be Ractor-shareable"
+        end
+
+        @order            = normalize_order(order)
+        @default_priority = default_priority
+        @reverse_order    = @order == :descending
+        super(capacity:, scope:, track_age:, fiber_wait:)
+      end
+
+      # @return [Symbol] always returns `:local`
+      def mode = :local
+
+      # @api private
+      def fiber_wait = internal_signal.fiber_wait
+
+      private
+
+      def eager_scoped_value? = false
+      def internal_queue      = scoped_value.first
+      def internal_signal     = scoped_value.last
+
+      def new_scoped_value(capacity: nil, fiber_wait: :auto, track_age: false)
+        signal = Internal::UnsharedSignal.for(fiber_wait)
+        [Internal::UnsharedPriorityQueue.new(capacity:, signal:, track_age:), signal]
+      end
+    end
+  end
+end

data/lib/farce/local/queue.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable queue with independent mutable storage in each scope.
+    #
+    # @!method initialize(capacity: 1024, track_age: false, scope: :ractor, **options)
+    #   @!macro scopes
+    #   @param capacity [Integer, nil] the maximum number of values, or nil for an unbounded queue
+    #   @param track_age [Boolean] whether to track enqueue age and queue generations
+    #   @param scope [Symbol] the scope of the queue
+    #   @option options [:auto, :io, :block] fiber_wait (:auto) how scheduled fibers wait on CRuby
+    #   @return [Queue]
+    class Queue < Abstract::Queue
+      include Shareable::Unfreezable
+      include Scoped
+
+      # @return [Symbol] always returns `:local`
+      def mode = :local
+
+      # @api private
+      def fiber_wait = internal_queue.fiber_wait
+
+      private
+
+      def internal_queue        = scoped_value
+      def new_scoped_value(...) = Internal::UnsharedQueue.new(...)
+    end
+  end
+end

data/lib/farce/local/scoped.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # Common scope selection and storage for shareable local objects.
+    module Scoped
+      include Shareable
+
+      # Freeze the current backing before recording the handle-global state.
+      # @api private
+      module Tracked
+        include Scoped
+
+        # @!visibility private
+        def self.included(base)
+          Scoped.included(base)
+          super
+        end
+
+        def freeze
+          return Object.instance_method(:freeze).bind_call(self) unless @farce_freeze_state
+
+          state = @farce_freeze_state
+          if state.respond_to?(:native_flag)
+            state.set { freeze_scoped_value(scoped_value) }
+            self
+          else
+            freeze_scoped_value(scoped_value)
+            super
+          end
+        end
+
+        private
+
+        def scoped_value
+          value = super
+          freeze_scoped_value(value) if frozen?
+          value
+        end
+      end
+
+      module Map
+        def initialize(*arguments, normalize_keys: nil, **)
+          restoring  = Internal::KeyNormalizer.restoration?(normalize_keys)
+          normalizer = Internal::KeyNormalizer.build(normalize_keys, shareable: true)
+
+          if is_a?(Abstract::ConcurrentMap)
+            @key_normalizer = normalizer
+          else
+            Internal::KeyNormalizer.install(self, normalizer, Internal::KeyNormalizer.operations_for(self))
+          end
+
+          if !is_a?(Abstract::LeaseMap) && !arguments.empty?
+            entries = convert_entries(arguments.first)
+            if entries && ((normalizer && !restoring) || !entries.is_a?(Hash))
+              canonical = Internal::KeyNormalizer.canonical_entries
+              entries.each do |key, value|
+                key = normalizer.call(key) if normalizer && !restoring
+                canonical << [key, value]
+              end
+              entries = canonical
+            end
+            arguments = arguments.dup
+            arguments[0] = entries
+          end
+          super(*arguments, **)
+        end
+
+        private
+
+        def install_copied_map(map)      = Internal::Storage.scope(scope)[self] = new_copied_scoped_value(map)
+        def new_copied_scoped_value(map) = map
+      end
+
+      MANAGER = ModeManager.new
+      private_constant :MANAGER, :Map
+
+      # @!visibility private
+      def self.included(base)
+        base.include Map if base < Abstract::Map
+        super
+      end
+
+      # @return [Symbol] The scope used to resolve this object's contents.
+      attr_reader :scope
+
+      # Constructor arguments configure each scope's independent backing object.
+      # @!macro scopes
+      # @param arguments [Array<BasicObject>] positional arguments for the backing object
+      # @param options [Hash{Symbol => BasicObject}] keyword arguments for the backing object
+      # @param scope [Symbol] The storage scope. Defaults to :ractor.
+      def initialize(*arguments, scope: :ractor, **options)
+        initialize_scoped(arguments, options, scope:)
+      end
+
+      private
+
+      def initialize_scoped(arguments, options, scope:, configuration: nil)
+        raise ArgumentError, "Invalid scope: #{scope.inspect}" unless Farce::SCOPES.include?(scope)
+
+        if is_a?(Shareable::Tracked)
+          guard = Internal.native_ractors? ? Internal::TransactionFreezeGuard : Internal::Flag
+          @farce_freeze_state = guard.new(false)
+        end
+        @scope         = scope
+        @configuration = configuration || MANAGER.wrap([arguments.freeze, options.freeze].freeze)
+
+        Internal::Storage.scope(scope)[self] = new_scoped_value(*arguments, **options) if eager_scoped_value?
+
+        # Abstract initializers allocate instance variables. Local backing objects
+        # live in Storage instead, so initialization ends here.
+        Internal::Freeze.publish(self)
+      end
+
+      def marshal_configuration
+        value = Envelope === @configuration ? @configuration.marshal_dump[1] : @configuration
+        arguments, options = value
+        canonical = Internal::KeyNormalizer.canonical_entries?(arguments.first)
+        if canonical
+          arguments = arguments.dup
+          arguments[0] = arguments[0].to_a.freeze
+          value = [arguments.freeze, options].freeze
+        end
+        [Internal::MarshalSupport.value(value), canonical]
+      end
+
+      # @api private
+      def marshal_initialize(arguments, options, configuration)
+        options = options.dup
+        scope = options.delete(:scope)
+        if options.key?(:normalize_keys)
+          normalizer = Internal::KeyNormalizer.build(options.delete(:normalize_keys), shareable: true)
+          if is_a?(Abstract::ConcurrentMap)
+            @key_normalizer = normalizer
+          else
+            Internal::KeyNormalizer.install(self, normalizer, Internal::KeyNormalizer.operations_for(self))
+          end
+        end
+        original, canonical = configuration
+        original = Internal::MarshalSupport.restore_value(original)
+        if canonical
+          initial, settings = original
+          initial = initial.dup
+          initial[0] = Internal::KeyNormalizer.canonical_entries.concat(initial[0])
+          original = [initial.freeze, settings].freeze
+        end
+        configuration = MANAGER.wrap(original)
+        initialize_scoped(arguments, options, scope:, configuration:)
+      end
+
+      # Subclasses without initial contents can defer backing storage allocation.
+      def eager_scoped_value? = true
+      def freeze_scoped_value(value) = value.freeze
+      def scoped_configuration = MANAGER.unwrap(@configuration)
+
+      def scoped_value
+        Internal::Storage.store_if_absent(self, scope:) do
+          arguments, options = scoped_configuration
+          new_scoped_value(*arguments, **options)
+        end
+      end
+    end
+  end
+end

data/lib/farce/local/set.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable set with independent mutable contents in each scope.
+    class Set < Farce::Abstract::Set
+      include Shareable::Delegated
+
+      # The scope with independent contents.
+      # @return [Symbol] The configured scope name.
+      def scope = map_backend.scope
+
+      private def new_map(...) = Farce::Local::Map.new(...)
+    end
+  end
+end