farce 0.0.1.alpha2-x86-linux-gnu

data/lib/farce/unsafe.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Module holding classes with instances which are not thread-safe and cannot be shared between Ractors.
+  module Unsafe
+    include Unshared
+    include Internal::Autoloads
+
+    # @overload enfarce(object, freeze: nil)
+    #   Converts vanilla Ruby objects into their {Farce::Unsafe} equivalents.
+    #
+    #   @example
+    #     Farce::Unsafe.enfarce({ foo: ["bar"] })
+    #     # =>  #<Farce::Unsafe::Map {foo: #<Farce::Unsafe::Vector ["bar"]>}>
+    #
+    #   @yield [object] Optional block, called with any object that doesn't have a specific conversion defined.
+    #   @yieldparam object [BasicObject] the object to convert
+    #   @yieldreturn [BasicObject] the converted object
+    #   @param object [BasicObject] The root object to convert
+    #   @param freeze [Boolean, nil]
+    #     Whether to freeze the converted objects.
+    #     If set to `nil` (default), the freezing behavior will depend on the original object's frozen state.
+    #   @return [BasicObject] the converted object
+    #   @see Farce.enfarce
+    def self.enfarce(object, **, &) = Internal::Converter.new(self, **, &).convert(object)
+  end
+end

data/lib/farce/unshareable.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Mixin that makes sure instances cannot be shared between Ractors.
+  # @note Mixin in this module will remove the `freeze` method from the class.
+  #
+  # @example
+  #   class MyClass
+  #     include Farce::Unshareable
+  #   end
+  #
+  #   object = MyClass.new
+  #   object.freeze # this would normally make it shareable
+  #
+  #   Ractor.shareable?(object) # => false
+  module Unshareable
+    # @api private
+    module UndefFreeze # :nodoc: all
+      # @api private
+      def append_features(mod)
+        super
+        if mod.is_a?(Class)
+          mod.class_eval { undef freeze if method_defined?(:freeze) }
+        else
+          mod.extend(UndefFreeze)
+        end
+      end
+    end
+
+    private_constant :UndefFreeze
+    extend UndefFreeze
+
+    # Mixin for classes that cannot be shared across Ractors, but may be moved between them.
+    module Movable
+      include Unshareable
+    end
+
+    # Mixin for classes that cannot be shared across Ractors, but may be copied between them.
+    module Copyable
+      include Unshareable
+    end
+
+    # Make sure to call `super` if you include this module.
+    # Accepts any arguments and passes them on to the superclass initializer.
+    def initialize(...)
+      pin_unshareable
+      super
+    end
+
+    # @return [Boolean] false
+    # @see Shareable#ractor_shareable?
+    def ractor_shareable? = false
+
+    private
+
+    def pin_unshareable
+      return unless Internal.native_ractors?
+      case self
+      when Movable  then Internal::Unshareable.prevent_copyable(self) unless is_a?(Copyable)
+      when Copyable then Internal::Unshareable.prevent_movable(self)
+      else Internal::Unshareable.pin_to_current_ractor(self)
+      end
+    end
+  end
+end

data/lib/farce/unshared/atom.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe atomic reference that retains values directly within one Ractor.
+    # Mutable values keep their identity. Updates are serialized between threads.
+    #
+    # @example Updating an array atomically
+    #   atom = Farce::Unshared::Atom.new([])
+    #   atom.update { |items| items + [:job] }
+    class Atom < Abstract::Atom
+      include Unshareable
+
+      # @param value [BasicObject, nil] the initial value
+      # @param compare_by_identity [Boolean] whether comparisons use object identity
+      def initialize(value = nil, compare_by_identity: false)
+        @atom = Internal::UnsharedAtom.new(value, compare_by_identity:)
+        super()
+      end
+    end
+  end
+end

data/lib/farce/unshared/counter.rb

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

data/lib/farce/unshared/flag.rb

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

data/lib/farce/unshared/lazy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe lazy value within one Ractor.
+    # Its factory may capture mutable state. The result retains its identity.
+    # Factory failures can be retried on the next access.
+    #
+    # @example Build a mutable cache on first access
+    #   lazy = Farce::Unshared::Lazy.new { {} }
+    #   lazy.value[:job] = :ready
+    #
+    # @!parse
+    #   class Lazy < Abstract::Lazy
+    #     # Without `self:`, the block keeps its original receiver.
+    #     # @overload initialize(factory)
+    #     #   @param factory [Class, Proc, #call] the factory, which may retain mutable state
+    #     # @overload initialize(self: nil)
+    #     #   @param self [BasicObject] the receiver to bind to the block
+    #     #   @yield computes the value on first access, preserving captured state
+    #     #   @yieldreturn [BasicObject] the cached result
+    #     def initialize(...) = nil
+    #   end
+    class Lazy < Abstract::Lazy
+      include Unshareable
+
+      private
+
+      def new_internal_atom = Internal::UnsharedAtom.new
+
+      def prepare_proc(factory, **options)
+        options.empty? ? factory : Farce.rebind(factory, **options)
+      end
+    end
+  end
+end

data/lib/farce/unshared/lazy_ref.rb

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

data/lib/farce/unshared/lease.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe lease that passes one resource directly within a Ractor.
+    #
+    # @example Updating one object from multiple threads
+    #   lease = Farce::Unshared::Lease.new { { count: 0 } }
+    #   workers = 3.times.map do
+    #     Thread.new do
+    #       lease.checkout { |state| state[:count] += 1 }
+    #     end
+    #   end
+    #   workers.each(&:join)
+    #
+    #   lease.checkout { |state| state[:count] } # => 3
+    class Lease < Abstract::Lease
+      include Unshareable
+
+      private
+
+      def new_internal_lease(resource) = Internal::UnsharedLease.new(resource)
+    end
+  end
+end

data/lib/farce/unshared/lease_map.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe map that passes independently leased resources within one Ractor.
+    #
+    # @example Coordinating mutable resources between threads
+    #   leases = Farce::Unshared::LeaseMap.new { { jobs: [] } }
+    #   workers = 2.times.map do
+    #     Thread.new { leases.checkout(:jobs) { |jobs| jobs << :finished } }
+    #   end
+    #   workers.each(&:join)
+    #   leases.checkout(:jobs, &:length) # => 2
+    class LeaseMap < Abstract::LeaseMap
+      include Unshareable
+
+      private
+
+      def new_internal_lease_map(mapping)
+        Internal::LeaseMap.new(mapping, lease_class: Farce::Unshared::Lease, registry_class: Farce::Unshared::Map)
+      end
+    end
+  end
+end

data/lib/farce/unshared/lease_pool.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe pool that passes resource references within one Ractor.
+    #
+    # @example Reusing objects from multiple threads
+    #   pool = Farce::Unshared::LeasePool.new(max_size: 1) { { uses: 0 } }
+    #   workers = 2.times.map do
+    #     Thread.new { pool.checkout { |state| state[:uses] += 1 } }
+    #   end
+    #   workers.each(&:join)
+    #
+    #   pool.checkout { |state| state[:uses] } # => 2
+    class LeasePool < Abstract::LeasePool
+      include Unshareable
+
+      private
+
+      def new_internal_pool(max_size) = Internal::UnsharedLeasePool.new(max_size)
+    end
+  end
+end

data/lib/farce/unshared/lfu_map.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe LFU map for mutable keys and values used within one Ractor.
+    class LFUMap < Abstract::LFUMap
+      include Unshareable
+
+      private
+
+      def new_bounded_map(...) = Internal::LFUMap.new(...)
+
+      def new_key_locks(compare_keys_by_identity:)
+        Internal::KeyLockMap.new(registry_class: Farce::Unshared::Map, compare_keys_by_identity:)
+      end
+    end
+  end
+end

data/lib/farce/unshared/lru_map.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe LRU map for mutable keys and values used within one Ractor.
+    class LRUMap < Abstract::LRUMap
+      include Unshareable
+
+      private
+
+      def new_bounded_map(...) = Internal::LRUMap.new(...)
+
+      def new_key_locks(compare_keys_by_identity:)
+        Internal::KeyLockMap.new(registry_class: Farce::Unshared::Map, compare_keys_by_identity:)
+      end
+    end
+  end
+end

data/lib/farce/unshared/map.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe concurrent map for mutable objects used within one Ractor.
+    # 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.
+    class Map < Abstract::ConcurrentMap
+      include Unshareable
+
+      # @!macro map_initialization
+      #
+      # @example Atomically updating a mutable value
+      #   counters = Farce::Unshared::Map.new({ jobs: [] })
+      #   counters.update(:jobs) { |jobs| jobs << :finished }
+      #   counters[:jobs] # => [:finished]
+      #
+      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: false)
+        populate   = initial_mapping && ((normalizer && !restoring) || !initial_mapping.is_a?(Hash))
+        @map       = Internal::UnsharedMap.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
+
+      Internal.prepare_map_access(self, :unshared)
+    end
+  end
+end

data/lib/farce/unshared/molecule.rb

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

data/lib/farce/unshared/priority_queue.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A priority queue that stores and returns values directly.
+    class PriorityQueue < Abstract::PriorityQueue
+      include Unshareable
+      include Internal::UnsharedQueueWaiting
+
+      # @return [Symbol] always returns :local
+      def mode = :local
+    end
+  end
+end

data/lib/farce/unshared/queue.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A FIFO queue that stores and returns values directly.
+    class Queue < Abstract::Queue
+      include Unshareable
+
+      # @overload initialize(capacity: 1024, track_age: false)
+      #   (see Farce::Abstract::Queue#initialize)
+      def initialize(capacity: 1024, fiber_wait: :auto, track_age: false)
+        @queue = Internal::UnsharedQueue.new(capacity:, fiber_wait:, track_age:)
+        super()
+      end
+
+      # (see Farce::Abstract::Queue#mode)
+      # @return [Symbol] always returns :local
+      def mode = :local
+
+      # The resolved fiber waiting strategy. Other Ruby engines may return :auto.
+      # @api private
+      def fiber_wait = @queue.fiber_wait
+    end
+  end
+end

data/lib/farce/unshared/set.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe set for mutable elements used within one Ractor.
+    class Set < Farce::Abstract::Set
+      include Unshareable
+
+      private def new_map(...) = Farce::Unshared::Map.new(...)
+    end
+  end
+end

data/lib/farce/unshared/sorted_set.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe set maintained in ascending order within one Ractor.
+    class SortedSet < Farce::Abstract::SortedSet
+      include Unshareable
+
+      class MutableTreeMap < Farce::Unshared::TreeMap # :nodoc:
+        private
+
+        def prepare_key(key) = key
+        def new_key_locks = Internal::MutableOrderedKeyLockMap.new
+        def new_tree_map(...) = Internal::MutableTreeMap.new(...)
+      end
+      private_constant :MutableTreeMap
+
+      private
+
+      def new_map(entries = nil, compare_keys_by_identity: false, **)
+        raise ArgumentError, "sorted sets do not support identity comparison" if compare_keys_by_identity
+        MutableTreeMap.new(entries)
+      end
+    end
+  end
+end

data/lib/farce/unshared/timer_queue.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A timer queue that stores and returns values directly.
+    class TimerQueue < Abstract::TimerQueue
+      include Unshareable
+      include Internal::UnsharedQueueWaiting
+
+      # @return [Symbol] always returns :local
+      def mode = :local
+    end
+  end
+end

data/lib/farce/unshared/tree_map.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe map that keeps entries sorted by key within one Ractor.
+    # Mutable string keys become immutable. Values are stored directly and may be mutable.
+    #
+    # @example Keeping mutable values in key order
+    #   value = []
+    #   map = Farce::Unshared::TreeMap.new(2 => value, 1 => [])
+    #
+    #   map[2].equal?(value) # => true
+    class TreeMap < Abstract::TreeMap
+      include Unshareable
+
+      private def new_tree_map(...) = Internal::TreeMap.new(...)
+    end
+  end
+end

data/lib/farce/unshared/vector.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe vector for mutable values used within one Ractor.
+    class Vector < Abstract::Vector
+      include Unshareable
+
+      # @param source [Array, nil] Initial values. Values are retained directly.
+      # @param compare_by_identity [Boolean] Whether values are compared by identity.
+      def initialize(source = nil, compare_by_identity: false)
+        @vector = Internal::UnsharedVector.new(source, compare_by_identity:)
+        super()
+      end
+    end
+  end
+end

data/lib/farce/unshared/weak_atom.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe weak atomic reference for values used within one Ractor.
+    #
+    # @example Referencing a mutable object within one Ractor
+    #   items = []
+    #   atom  = Farce::Unshared::WeakAtom.new(items)
+    #   atom.value.equal?(items) # => true
+    #   items << :job
+    #   atom.value # => [:job]
+    #
+    #   items = nil
+    #   # Once the array is collected, atom.value returns nil.
+    #
+    # @example Atomically replacing the referenced object
+    #   original    = []
+    #   replacement = [:job]
+    #   atom        = Farce::Unshared::WeakAtom.new(original, compare_by_identity: true)
+    #   atom.compare_and_set(original, replacement) # => true
+    #   atom.value.equal?(replacement)              # => true
+    class WeakAtom < Abstract::WeakAtom
+      include Unshareable
+
+      private def internal_atom_class = Internal::UnsharedWeakAtom
+    end
+  end
+end

data/lib/farce/unshared/weak_key_map.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe map with weak keys for use within one Ractor.
+    #
+    # @example Associating data with a mutable object
+    #   owner      = Object.new
+    #   map        = Farce::Unshared::WeakKeyMap.new
+    #   map[owner] = []
+    #   map[owner] << :job
+    #
+    #   # The entry can disappear once its key is collected.
+    #   owner = nil
+    class WeakKeyMap < Abstract::WeakKeyMap
+      include Unshareable
+
+      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: false)
+        populate   = initial_mapping && ((normalizer && !restoring) || !initial_mapping.is_a?(Hash))
+        @map       = Internal::UnsharedWeakKeyMap.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
+    end
+  end
+end

data/lib/farce/unshared/weak_map.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe map with weak keys and values for use within one Ractor.
+    #
+    # @example Keeping a relationship while both mutable objects remain alive
+    #   key   = Object.new
+    #   value = Object.new
+    #   map   = Farce::Unshared::WeakMap.new({ key => value })
+    #   map[key].equal?(value) # => true
+    #
+    #   # The entry can disappear once its key or value is collected
+    #   value = nil
+    class WeakMap < Abstract::WeakMap
+      include Unshareable
+
+      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: false)
+        populate   = initial_mapping && ((normalizer && !restoring) || !initial_mapping.is_a?(Hash))
+        @map       = Internal::UnsharedWeakMap.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
+    end
+  end
+end