farce 0.1.0-x86_64-linux-gnu → 0.3.0-x86_64-linux-gnu

data/lib/farce/task.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A unit of work that executes once and retains its result or failure.
+  #
+  # ```ruby
+  # # You can create and schedule a task with one call:
+  # task = Farce::Task.schedule { 1 + 2 }
+  # task.value # => 3
+  #
+  # # There is also a shorthand for running a task on the global Ractor pool:
+  # task = Farce::Task.in_parallel { sleep 1 }
+  # task.join
+  # task.alive? # => false
+  #
+  # # schedule accepts a custom scheduler:
+  # scheduler = Farce::Scheduler.create
+  # task      = Farce::Task.schedule(scheduler:) { 1 + 2 }
+  #
+  # # or alternatively you can manually create a task and hand it to the scheduler
+  # task = Farce::Task.new { 1 + 2 }
+  # scheduler.schedule(&task)
+  #
+  # # or execute it manually
+  # task = Farce::Task.new { Ractor.current.name.upcase }
+  # Ractor.new(task, name: "Herbert") { it.call }
+  # task.value # => "HERBERT"
+  # ```
+  class Task
+    include Abstract::Value
+    include Internal::Freeze::Delegated
+    include Internal::MarshalSupport::Reject
+
+    # Raised when an operation is attempted on a task that is in an incorrect state.
+    InvalidStateError = Class.new(RuntimeError)
+
+    # @!macro [new] task_schedule
+    #   @!macro modes
+    #   @param args [Array] the arguments to pass to the task
+    #   @param mode [Symbol] the mode for arguments and the successful result
+    #     Arguments can be overridden by {#add_argument}.
+    #   @yield [*args] the block to execute with the given arguments
+    #   @yieldparam args [Array] the arguments passed to the block
+    #   @yieldreturn [Object] the result of the block execution, will become the task's {#value}
+    #   @raise ArgumentError if the provided mode is invalid
+    #   @raise LocalJumpError if no callback is provided
+
+    # @overload in_parallel(*args, mode: :smart)
+    #   Creates a task and schedules it for execution on the {Farce.in_parallel globally shared executor pool}.
+    #   @!macro task_schedule
+    #   @return [Task] the created task
+    def self.in_parallel(*, **, &) = enqueue(false, Farce.in_parallel, *, auto_local: false, **, &)
+
+    # @overload on_main(*args, mode: :smart, auto_local: true)
+    #   Creates a task and schedules it for execution on the {Farce.on_main main scheduler}.
+    #   If `auto_local` is true (default), `mode` will be set to `:local` if the method is called from the main Ractor.
+    #
+    #   @!macro task_schedule
+    #   @param auto_local [Boolean] whether to automatically switch to local mode if called from the main Ractor
+    #   @return [Task] the created task
+    def self.on_main(*, **, &) = enqueue(false, Farce.on_main, *, **, &)
+
+    # @overload schedule(*args, mode: :smart, auto_local: true, scheduler: nil, &)
+    #   Creates a task and schedules it for execution.
+    #   A scheduler may optionally be provided.
+    #
+    #   If no scheduler is provided, then it will look for a Ractor-local scheduler if mode is `:local` or `auto_local`
+    #   is true. If none is found, one will be created automatically if `:mode` is `:local`, otherwise the
+    #   {Farce.in_parallel globally shared executor pool} will be used.
+    #
+    #   The scheduler may be a {Abstract::Executor executor}, or a Fiber scheduler.
+    #
+    #   @!macro task_schedule
+    #   @param scheduler [Abstract::Executor, Fiber::Scheduler, nil] the scheduler to use for execution
+    #   @return [Task] the created task
+    def self.schedule(*, scheduler: nil, **, &) = enqueue(false, scheduler, *, **, &)
+
+    # @overload try_schedule(*args, mode: :smart, auto_local: true, scheduler: nil, &)
+    #   Creates a task and attempts to schedule it for execution.
+    #
+    #   Behaves exactly like {.schedule}, except it uses {Abstract::Executor#try_schedule} instead of
+    #   {Abstract::Executor#schedule} if the scheduler is an executor, and that it returns `nil` if it fails to
+    #   schedule the task.
+    #
+    #   @!macro task_schedule
+    #   @return [Task, nil] the created task, or `nil` if it failed to schedule
+    def self.try_schedule(*, scheduler: nil, **, &) = enqueue(true, scheduler, *, **, &)
+
+    # @api private
+    def self.enqueue(non_block, scheduler, *, mode: :smart, auto_local: true, &) # :nodoc:
+      unless scheduler
+        scheduler = Internal.local_scheduler(create: mode == :local) if auto_local || mode == :local
+        unless scheduler
+          scheduler  = Internal::ParallelScheduler
+          auto_local = false
+        end
+      end
+
+      if scheduler.is_a?(Abstract::Executor)
+        mode = :local if auto_local && scheduler.local?(wait: false)
+        task = new(*, mode:, &)
+
+        if non_block
+          return unless scheduler.try_schedule(mode:, auto_local: false, &task)
+        else
+          scheduler.schedule(mode:, auto_local: false, &task)
+        end
+      else
+        task = new(*, mode: :local, &)
+        scheduler.fiber(&task)
+      end
+
+      task
+    end
+    private_class_method :enqueue
+
+    # @return [Symbol] the default mode used for task arguments and the return value
+    attr_reader :mode
+
+    # Creates a new task with the given arguments and callback.
+    #
+    # This does not schedule the task for execution, nor does it associate it with any executor.
+    #
+    # In fact, the task object itself is a proc-like object, that can be {call called} like a regular proc,
+    # but will track its execution state and result.
+    #
+    # @example Using a Task without an Executor
+    #   task = Farce::Task.new(1, 2) { |a, b| a + b }
+    #
+    #   task.alive?       # => true
+    #   task.call == task # => true
+    #   task.alive?       # => false
+    #   task.value        # => 3
+    #
+    # @example Passing a task to an executor
+    #   task = Farce::Task.new { puts "Hello, world!" }
+    #   Farce.in_parallel(&task)
+    #   task.join # waits for the task to complete
+    #
+    # @!macro task_schedule
+    def initialize(*args, mode: :smart, &callback)
+      raise ArgumentError, "invalid mode: #{mode}" unless MODES.include?(mode)
+      raise LocalJumpError, "no callback provided" unless block_given?
+
+      @mode   = mode
+      @ractor = Strict::Atom.new
+      @state  = Strict::Atom.new(:initialized)
+
+      if mode == :local
+        @arguments    = args
+        @callback     = callback
+        @manager      = nil
+        @ractor.value = Ractor.current
+        @result       = Unshared::Atom.new
+      else
+        @arguments = Strict::Vector.new
+        @callback  = Ractor.shareable?(callback) ? callback : Ractor.shareable_proc(&callback)
+        @manager   = ModeManager.new(mode: mode)
+        @result    = Strict::Atom.new
+        args.each { add_argument(it) }
+      end
+
+      __freeze__
+    end
+
+    # Adds an argument to the task.
+    # Can only be called before the task is frozen and before {#call} is invoked.
+    #
+    # Allows for arguments to use different modes than the return value (or other arguments).
+    # Mode is ignored for {#local? local} tasks.
+    #
+    # For non-local tasks, `mode` may only be set to `:local` for arguments added by the Ractor that will
+    # {#call execute} the task.
+    #
+    # @example A task using `move` for the return value, but `copy` for its argument
+    #   task = Farce::Task.new(mode: :move) { |arg| arg.upcase }
+    #   task.add_argument("hello", mode: :copy)
+    #   Farce.in_parallel(&task)
+    #   task.value # => "HELLO"
+    #
+    # @param argument [BasicObject] the argument to add to the task
+    # @param mode [Symbol, nil] the mode to use for the argument, or `nil` to use the task's default mode
+    # @raise ArgumentError if the provided mode is invalid
+    # @raise FrozenError if the task has already been frozen or called
+    # @raise InvalidStateError if trying to add a local argument from more than one ractor
+    # @return [self] the task itself, for chaining
+    def add_argument(argument, mode: nil)
+      check_frozen!
+
+      unless local?
+        raise ArgumentError, "invalid mode: #{mode}" unless mode.nil? || MODES.include?(mode)
+        raise InvalidStateError, "cannot add local argument to a non-local task" if mode == :local && !claim_for_ractor?
+        argument = @manager.wrap(argument, mode:)
+      end
+
+      @arguments << argument
+      self
+    end
+
+    alias << add_argument
+
+    # @return [Boolean] whether the task is currently alive (initialized or running)
+    def alive? = alive_state?(@state.value)
+
+    # Executes the task by invoking its callback with the added arguments.
+    # @raise InvalidStateError if the task has already been claimed by another ractor or has already been called
+    # @return [self] the task itself, for chaining
+    def call
+      raise InvalidStateError, "task already claimed by another ractor" unless claim_for_ractor?
+      raise InvalidStateError, "call may only be called once" unless @state.compare_and_set(:initialized, :running)
+      begin
+        arguments     = local? ? @arguments.freeze : @arguments.freeze.to_a.map! { @manager.unwrap(it) }
+        result        = @callback.call(*arguments)
+        @result.value = local? ? result : @manager.wrap(result)
+        @state.value  = :finished
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        # Every callback failure must release waiters, including ScriptError and SystemExit.
+        begin
+          @result.value = e
+        rescue Ractor::Error
+          @result.value = [RuntimeError, -"#{e.class}: #{e.message}", Ractor.make_shareable(e.backtrace)].freeze
+        end
+        @state.value = :error
+      ensure
+        if @state.value == :running
+          @result.value = [RuntimeError, -"task execution aborted"].freeze
+          @state.value  = :error
+        end
+      end
+
+      self
+    end
+
+    # Waits for the task to finish, with an optional timeout.
+    # @param timeout [Numeric, nil] the maximum time to wait, or `nil` to wait indefinitely
+    # @return [self, nil] the task itself if it finished within the timeout, or `nil` otherwise
+    def join(timeout = nil)
+      return unless @state.wait_while(timeout:) { alive_state?(it) }
+      self
+    end
+
+    # @return [Boolean] whether the task is local (i.e., its mode is `:local`)
+    def local? = @mode == :local
+
+    # Waits for the task to finish and returns its value, with an optional timeout.
+    # If the task raises an error, it will be propagated.
+    #
+    # @param timeout [Numeric, nil] the maximum time to wait, or `nil` to wait indefinitely
+    # @return [BasicObject, nil]
+    #   the value returned by the task's callback, or `nil` if the task did not finish within the timeout
+    # @raise Exception if the task raises an error
+    # @raise RuntimeError with the original class, message, and backtrace if the exception cannot be shared
+    # @raise RuntimeError if execution is aborted before producing a result or exception
+    def value(timeout = nil)
+      case @state.wait_while(timeout:) { alive_state?(it) }
+      when :finished then local? ? @result.value : @manager.unwrap(@result.value)
+      when :error    then raise(*@result.value)
+      end
+    end
+
+    # Converts the task to a Proc object.
+    # If the task is Ractor-shareable, then so is the returned Proc.
+    # @return [Proc] a Proc that calls the task's `call` method
+    def to_proc
+      return method(:call).to_proc if local?
+      task = self
+      Ractor.make_shareable(-> { task.call })
+    end
+
+    private
+
+    def alive_state?(state) = state == :initialized || state == :running
+
+    def claim_for_ractor?
+      current_ractor = Ractor.current
+      @ractor.compare_and_set(nil, current_ractor)
+      @ractor.value == current_ractor
+    end
+
+    define_method(:__freeze__, Kernel.instance_method(:freeze))
+    def freeze_backend = @arguments
+  end
+end

data/lib/farce/{thread_scheduler.rb → thread_executor.rb}

@@ -3,11 +3,11 @@
 # warn_indent: true
 
 module Farce
-  # A scheduler that starts a new thread for each scheduled task. Executes synchronous tasks inline.
+  # A task executor that starts a new thread for each scheduled task. Executes synchronous tasks inline.
   # Creating an instance starts no threads. Blocks and arguments stay local to the caller.
-  # Tasks are not tracked, and closing this stateless scheduler has no effect.
+  # Tasks are not tracked, and closing this stateless executor has no effect.
   # Default instances support Marshal. Instances with a custom thread factory reject dumping.
-  class ThreadScheduler < Farce::Abstract::Scheduler
+  class ThreadExecutor < Farce::Abstract::Executor
     include Shareable::Immutable
     include Internal::Inspect
 
@@ -18,7 +18,7 @@ module Farce
 
     # @api private
     def marshal_dump
-      raise TypeError, "scheduler factories cannot be marshaled" if @factory
+      raise TypeError, "thread factories cannot be marshaled" if @factory
       [1]
     end
 
@@ -32,7 +32,7 @@ module Farce
     #
     # @overload schedule(*args, **options)
     #   @param args [Array<Object>] Arguments passed to the block.
-    #   @param options [Hash] Scheduler options are ignored. All tasks use local arguments.
+    #   @param options [Hash] Execution options are ignored. All tasks use local arguments.
     #   @yield [*args] The task to run.
     #   @return [self]
     def schedule(*, **, &)
@@ -45,7 +45,7 @@ module Farce
     #
     # @overload execute(*args, **options)
     #   @param args [Array<Object>] Arguments passed to the block.
-    #   @param options [Hash] Scheduler options are ignored. All tasks use local arguments.
+    #   @param options [Hash] Execution options are ignored. All tasks use local arguments.
     #   @yield [*args] The task to run.
     #   @return [self]
     def execute(*, **)
@@ -57,7 +57,7 @@ module Farce
     # @return [self] Does not wait for or stop task threads.
     def close = self
 
-    # @return [false] This stateless scheduler is always available.
+    # @return [false] This stateless executor is always available.
     def closed? = false
 
     # @return [Symbol] Always `:running`.

data/lib/farce/timer_queue.rb

@@ -4,14 +4,14 @@
 
 module Farce
   # A shareable timer queue with transfer modes for unshareable values.
-  class TimerQueue < Abstract::TimerQueue
+  class TimerQueue < Farce::Abstract::TimerQueue
     include Internal::ManagedQueue
     include Shareable::Unfreezable
 
     # (see Farce::Abstract::TimerQueue#initialize)
     # @!macro modes
     # @param mode [Symbol] the transfer mode for unshareable values
-    def initialize(capacity: nil, mode: :copy, track_age: false)
+    def initialize(capacity: nil, mode: :smart, track_age: false)
       @manager = ModeManager.new(mode:)
       super(capacity:, track_age:)
     end
@@ -20,16 +20,20 @@ module Farce
     # @!macro modes
     # @param mode [Symbol] the transfer mode for unshareable values
     def push(value, non_block = false, mode: nil, timeout: nil, **time_options) # rubocop:disable Style/OptionalBooleanParameter
-      at = Clock.parse(time_options)
-      push_to_storage(at, non_block, @manager.wrap(value, mode:), timeout:)
+      at    = Clock.parse(time_options)
+      value = @manager.wrap(value, mode:)
+      entry = Entry.new(value, at, self)
+      push_to_storage(at, non_block, value, timeout:) && entry
     end
 
     # (see Farce::Abstract::TimerQueue#try_push)
     # @!macro modes
     # @param mode [Symbol] the transfer mode for unshareable values
     def try_push(value, mode: nil, **time_options)
-      at = Clock.parse(time_options)
-      return true if @queue.push(at, @manager.wrap(value, mode:))
+      at    = Clock.parse(time_options)
+      value = @manager.wrap(value, mode:)
+      entry = Entry.new(value, at, self)
+      return entry if @queue.push(at, value)
       block_given? ? yield : false
     end
 
@@ -62,5 +66,15 @@ module Farce
       return @manager.unwrap(value) unless empty
       yield if block_given?
     end
+
+    private
+
+    def delete_from_storage(priority, value, compare_by_identity:)
+      if compare_by_identity && @manager.managed_envelope?(value)
+        @queue.delete_identity(priority, value)
+      else
+        super
+      end
+    end
   end
 end

data/lib/farce/transaction/vector.rb

@@ -18,7 +18,12 @@ module Farce
 
       # (see Abstract::Vector#[])
       # @see Abstract::Vector#[]
-      def [](index) = access { unwrap_stored(@working[index]) }
+      def [](index, length = UNDEFINED)
+        access do
+          next unwrap_stored(@working[index]) if length.equal?(UNDEFINED) && !index.is_a?(Range)
+          slice(index, length)
+        end
+      end
 
       # (see Abstract::Vector#get)
       # @see Abstract::Vector#get
@@ -34,8 +39,12 @@ module Farce
 
       # (see Abstract::Vector#[]=)
       # @see Abstract::Vector#[]=
-      def []=(index, value)
-        store(index, value)
+      def []=(index, value, replacement = UNDEFINED)
+        if replacement.equal?(UNDEFINED) && !index.is_a?(Range)
+          store(index, value)
+        else
+          write { assign_vector_slice(index, value, replacement) }
+        end
       end
 
       # (see Abstract::Vector#store)
@@ -52,15 +61,24 @@ module Farce
 
       # (see Abstract::Vector#push)
       # @see Abstract::Vector#push
-      def push(value, mode: nil)
-        write { @working.push(wrap(value, mode:)) }
+      def push(value = UNDEFINED, *rest, mode: nil)
+        write do
+          if rest.empty? && !value.equal?(UNDEFINED)
+            @working.push(wrap(value, mode:))
+          else
+            push_values(value.equal?(UNDEFINED) ? rest : [value, *rest], mode:)
+          end
+        end
         self
       end
-      alias << push
+
+      def <<(value) = push(value)
 
       # (see Abstract::Vector#pop)
       # @see Abstract::Vector#pop
-      def pop = write { unwrap_stored(@working.pop) }
+      def pop(count = UNDEFINED)
+        write { count.equal?(UNDEFINED) ? unwrap_stored(@working.pop) : pop_values(count) }
+      end
 
       # (see Abstract::Vector#clear)
       # @see Abstract::Vector#clear
@@ -120,6 +138,17 @@ module Farce
       def internal_vector = @working
       def logical_value(value) = unwrap_stored(value)
 
+      def deletion_comparison(value)
+        return value unless @manager
+        @manager.wrap(value, mode: compare_by_identity? ? :local : :copy)
+      end
+
+      def deletion_match?(stored, expected)
+        return super unless @manager
+        unwrap_stored(stored)
+        @manager.same_value?(stored, expected, identity: compare_by_identity?)
+      end
+
       # Slice helpers return independent data rather than another participant.
       # Use an ordinary vector that remains usable after the attempt ends.
       def build_derived_vector(values)
@@ -130,10 +159,15 @@ module Farce
 
       def inspect_value(inspector, value) = super(inspector, value, @manager)
       def derived_storage(value)          = wrap(value)
+      def prepare_vector_value(value, mode: nil) = wrap(value, mode:)
 
-      Wrapper.inherit(self, :each_index, :reverse_each, :to_a, :deconstruct, :to_h, :join, :dig, :assoc,
+      Wrapper.inherit(self, :each_index, :reverse_each, :to_a, :to_ary, :deconstruct, :to_h, :join, :dig, :assoc,
         :rassoc, :at, :fetch, :fetch_values, :values_at, :slice, :rfind, :bsearch, :bsearch_index, :pack,
-        :length, :count, :compare_by_identity?, :shareable_values?)
+        :length, :count, :compare_by_identity?, :shareable_values?, :flatten, :transpose, :product,
+        :combination, :repeated_combination, :permutation, :repeated_permutation, :<=>,
+        writes: %i[delete delete_if map! collect! keep_if select! filter! reject! compact! uniq!
+                   reverse! rotate! shuffle! sort! sort_by! flatten! shift unshift prepend insert delete_at slice!
+                   replace fill append])
     end
   end
 end

data/lib/farce/transaction/wrapper.rb

@@ -15,6 +15,20 @@ module Farce
     module Wrapper
       include Internal::MarshalSupport::Reject
 
+      # Freezing an attempt view must not freeze its staged data or participant.
+      module Unfreezable
+        def append_features(mod)
+          super
+          if mod.is_a?(Class)
+            mod.class_eval { undef freeze if method_defined?(:freeze) }
+          else
+            mod.extend(Unfreezable)
+          end
+        end
+      end
+      private_constant :Unfreezable
+      extend Unfreezable
+
       # Wrappers inherit abstract container classes for their interfaces, but
       # must not initialize another ordinary container. This constructor ends
       # Unshareable's super chain after binding the existing transaction snapshot.

data/lib/farce/tree_map.rb

@@ -20,7 +20,7 @@ module Farce
     # @param entries [Hash, Array<Array(BasicObject, BasicObject)>, Abstract::Map, #each, nil]
     #   Optional initial entries for the map.
     # @param mode [Symbol] The default value transfer mode.
-    def initialize(entries = nil, mode: :copy, normalize_keys: nil, **keyword_entries)
+    def initialize(entries = nil, mode: :smart, normalize_keys: nil, **keyword_entries)
       unless keyword_entries.empty?
         raise ArgumentError, "entries given as both positional and keyword arguments" unless entries.nil?
         entries = keyword_entries

data/lib/farce/unsafe/lfu_map.rb

@@ -10,6 +10,7 @@ module Farce
     # does not coordinate competing callers, including callers loading the same key.
     class LFUMap < Abstract::LFUMap
       include Unshareable
+      include Internal::Freeze::Delegated
 
       # @!method store_if_absent(key)
       #   Read an existing value or construct and store a value for an absent key.
@@ -29,6 +30,7 @@ module Farce
       private
 
       def new_bounded_map(...) = Internal::LFUMap.new(...)
+      def freeze_backend       = @map
       def new_key_locks(**)    = nil
       def with_key_lock(_key)  = yield
     end

data/lib/farce/unsafe/lru_map.rb

@@ -10,6 +10,7 @@ module Farce
     # does not coordinate competing callers, including callers loading the same key.
     class LRUMap < Abstract::LRUMap
       include Unshareable
+      include Internal::Freeze::Delegated
 
       # @!method store_if_absent(key)
       #   Read an existing value or construct and store a value for an absent key.
@@ -29,6 +30,7 @@ module Farce
       private
 
       def new_bounded_map(...) = Internal::LRUMap.new(...)
+      def freeze_backend       = @map
       def new_key_locks(**)    = nil
       def with_key_lock(_key)  = yield
     end

data/lib/farce/unsafe/tree_map.rb

@@ -8,12 +8,14 @@ module Farce
     # A {Abstract::TreeMap tree map} that is not thread-safe and cannot be shared between Ractors.
     class TreeMap < Abstract::TreeMap
       include Unshareable
+      include Internal::Freeze::Delegated
 
       undef_method :transaction_wrapper
 
       private
 
       def new_tree_map(...)   = Internal::UnsafeTreeMap.new(...)
+      def freeze_backend      = @map
       def new_key_locks       = nil
       def with_key_lock(_key) = yield
     end

data/lib/farce/unshareable.rb

@@ -4,7 +4,7 @@
 
 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.
+  # Instances may be frozen without becoming Ractor-shareable.
   #
   # @example
   #   class MyClass
@@ -12,26 +12,10 @@ module Farce
   #   end
   #
   #   object = MyClass.new
-  #   object.freeze # this would normally make it shareable
+  #   object.freeze # Preserves the Ractor restrictions.
   #
   #   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
@@ -58,7 +42,12 @@ module Farce
     def pin_unshareable
       return unless Internal.native_ractors?
       case self
-      when Movable  then Internal::Unshareable.prevent_copyable(self) unless is_a?(Copyable)
+      when Movable
+        if is_a?(Copyable)
+          Internal::Unshareable.prevent_shareable(self)
+        else
+          Internal::Unshareable.prevent_copyable(self)
+        end
       when Copyable then Internal::Unshareable.prevent_movable(self)
       else Internal::Unshareable.pin_to_current_ractor(self)
       end

data/lib/farce/unshared/atom.rb

@@ -12,6 +12,7 @@ module Farce
     #   atom.update { |items| items + [:job] }
     class Atom < Abstract::Atom
       include Unshareable
+      include Internal::Freeze::Delegated
 
       # @param value [BasicObject, nil] the initial value
       # @param compare_by_identity [Boolean] whether comparisons use object identity
@@ -19,6 +20,8 @@ module Farce
         @atom = Internal::UnsharedAtom.new(value, compare_by_identity:)
         super()
       end
+
+      private def freeze_backend = @atom
     end
   end
 end

data/lib/farce/unshared/lfu_map.rb

@@ -7,10 +7,12 @@ module Farce
     # A thread-safe LFU map for mutable keys and values used within one Ractor.
     class LFUMap < Abstract::LFUMap
       include Unshareable
+      include Internal::Freeze::Delegated
 
       private
 
       def new_bounded_map(...) = Internal::LFUMap.new(...)
+      def freeze_backend = @map
 
       def new_key_locks(compare_keys_by_identity:)
         Internal::KeyLockMap.new(registry_class: Farce::Unshared::Map, compare_keys_by_identity:)

data/lib/farce/unshared/lru_map.rb

@@ -7,10 +7,12 @@ module Farce
     # A thread-safe LRU map for mutable keys and values used within one Ractor.
     class LRUMap < Abstract::LRUMap
       include Unshareable
+      include Internal::Freeze::Delegated
 
       private
 
       def new_bounded_map(...) = Internal::LRUMap.new(...)
+      def freeze_backend = @map
 
       def new_key_locks(compare_keys_by_identity:)
         Internal::KeyLockMap.new(registry_class: Farce::Unshared::Map, compare_keys_by_identity:)

data/lib/farce/unshared/map.rb

@@ -12,6 +12,7 @@ module Farce
     # `dup` and `clone` copy entries into independent storage while sharing stored values.
     class Map < Abstract::ConcurrentMap
       include Unshareable
+      include Internal::Freeze::Delegated
 
       # @!macro map_initialization
       #
@@ -44,6 +45,8 @@ module Farce
       end
 
       Internal.prepare_map_access(self, :unshared)
+
+      private def freeze_backend = @map
     end
   end
 end