farce 0 → 0.1.0

data/lib/farce/internal/strict_lease.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Lease storage that retains shareable resource references directly.
+    class StrictLease < LeaseState
+      include Freeze::Unfreezable
+
+      private
+
+      def initialize_resource(resource)
+        @resource = StrictAtom.new(resource)
+        Freeze.publish(self)
+      end
+
+      def take_resource             = @resource.swap(nil)
+      def return_resource(resource) = @resource.store(resource)
+
+      def validate_resource!(resource)
+        super
+        return if Ractor.shareable?(resource)
+
+        raise Ractor::IsolationError, "lease resource must be Ractor-shareable"
+      end
+    end
+  end
+end

data/lib/farce/internal/strict_lease_map.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Validate shareable resources before publishing or replacing map leases.
+    class StrictLeaseMap < LeaseMap
+      private
+
+      def validate_resource!(resource)
+        super
+        return if Ractor.shareable?(resource)
+
+        raise Ractor::IsolationError, "lease resource must be Ractor-shareable"
+      end
+    end
+  end
+end

data/lib/farce/internal/strict_lease_pool.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Lease pool storage that retains shareable resource references directly.
+    class StrictLeasePool < LeasePoolState
+      include Freeze::Unfreezable
+
+      private
+
+      def initialize_storage               = @resources = StrictMap.new(compare_by_identity: true)
+      def finalize_initialization          = Freeze.publish(self)
+      def store_resource(token, resource)  = @resources.store(token, resource)
+      def take_resource(token)             = @resources.delete(token)
+      def return_resource(token, resource) = store_resource(token, resource)
+      def discard_resource(token)          = @resources.delete(token)
+
+      def validate_resource!(resource)
+        super
+        return if Ractor.shareable?(resource)
+
+        raise Ractor::IsolationError, "lease pool resource must be Ractor-shareable"
+      end
+    end
+  end
+end

data/lib/farce/internal/thread_pool.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal
+    # Run blocks on a bounded set of reusable threads.
+    # Workers start on demand. Capacity limits the total running and queued jobs.
+    # Each caller waits for its block's result and receives any exception it raises.
+    # Queue waits can yield through Ruby's scheduler hooks when those are available.
+    #
+    # An interrupted caller cancels its job if it has not started. Once a job has
+    # started, the caller waits for it to finish before unwinding its own cleanup.
+    # Closing stops new submissions, finishes accepted jobs, and joins the workers.
+    class ThreadPool
+      # Fetch or create the pool shared by all threads and fibers in this Ractor.
+      # Closing it is explicit and terminal. Later calls return the same closed pool.
+      def self.current
+        Ractor.store_if_absent(name) { new }
+      end
+
+      # Read the configured worker limit for the current Ractor.
+      def self.default_max_threads
+        Ractor.main? ? FROZEN_CONFIG.main_thread_pool_size : FROZEN_CONFIG.additional_thread_pool_size
+      end
+
+      class Job
+        def initialize(operation)
+          @operation = operation
+          @mutex     = Thread::Mutex.new
+          @result    = Thread::Queue.new
+          @done      = Thread::Queue.new
+          @started   = @cancelled = false
+        end
+
+        def run
+          operation = @mutex.synchronize do
+            @started = true
+            @operation unless @cancelled
+          end
+          @value = operation&.call
+        rescue Exception => e # rubocop:disable Lint/RescueException -- deliver job failures without losing a worker
+          @error = e
+        ensure
+          @operation = nil
+        end
+
+        def finish
+          @done << true
+          @result << [@value, @error]
+        end
+
+        def value
+          value, error = @result.pop
+          raise error if error
+          value
+        end
+
+        def cancel_and_wait
+          # Skip a job that has not started. Otherwise wait for its block to finish
+          # before the caller can clean up resources that the block still uses.
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            skipped = @mutex.synchronize do
+              unless @started
+                @cancelled = true
+                @operation = nil
+                true
+              end
+            end
+            unless skipped
+              Fiber.respond_to?(:blocking) ? Fiber.blocking { @done.pop } : @done.pop
+            end
+          end
+        end
+      end
+      private_constant :Job
+
+      attr_reader :max_threads, :capacity
+
+      # Limit worker threads and accepted jobs. Capacity defaults to twice the thread limit.
+      def initialize(max_threads: ThreadPool.default_max_threads, capacity: nil)
+        @max_threads = Integer(max_threads)
+        @capacity    = capacity.nil? ? @max_threads * 2 : Integer(capacity)
+
+        raise ArgumentError, "max_threads must be positive" unless @max_threads.positive?
+        raise ArgumentError, "capacity must be at least max_threads" if @capacity < @max_threads
+
+        @mutex   = Thread::Mutex.new
+        @jobs    = Thread::Queue.new
+        @slots   = Thread::SizedQueue.new(@capacity)
+        @workers = []
+        @pending = 0
+        @closed  = false
+
+        @capacity.times { @slots << true }
+      end
+
+      # Wait for capacity, run the block on a worker, and return its value or raise its exception.
+      def call(&operation)
+        raise ArgumentError, "no block given" unless operation
+        admitted = @slots.pop
+        raise IOError, "thread pool is closed" unless admitted
+        job = Job.new(operation)
+        submitted = false
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          submit(job)
+          submitted = true
+        end
+        job.value
+      ensure
+        if submitted
+          job.cancel_and_wait
+        elsif admitted
+          release_slot
+        end
+      end
+
+      # Return the number of workers created so far.
+      def size = @mutex.synchronize { @workers.size }
+
+      # Report whether the pool has stopped accepting jobs.
+      def closed? = @mutex.synchronize { @closed }
+
+      # Stop accepting jobs, wake callers waiting for capacity, and finish accepted jobs.
+      def close
+        workers = @mutex.synchronize do
+          raise ThreadError, "a worker cannot close its own pool" if @workers.include?(Thread.current)
+          @closed = true
+          @slots.close
+          @jobs.close
+          @workers.dup
+        end
+        Fiber.respond_to?(:blocking) ? Fiber.blocking { workers.each(&:join) } : workers.each(&:join)
+        nil
+      end
+
+      private
+
+      def submit(job)
+        @mutex.synchronize do
+          raise IOError, "thread pool is closed" if @closed
+          @workers << Thread.new { work } if @workers.size < @max_threads && @workers.size <= @pending
+          @pending += 1
+          @jobs << job
+        end
+      end
+
+      def work
+        while job = @jobs.pop
+          job.run
+          @mutex.synchronize { @pending -= 1 }
+          release_slot
+          job.finish
+          job = nil
+        end
+      end
+
+      def release_slot
+        @slots << true
+      rescue ::ClosedQueueError
+        # Closing the pool has already woken callers waiting for capacity.
+        nil
+      end
+    end
+  end
+end

data/lib/farce/internal/transaction_conflict.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    TransactionConflict = Class.new(StandardError)
+  end
+end

data/lib/farce/internal/transaction_freeze_guard.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # Keep a Local handle's shared freeze state stable across a foreign commit.
+    # Reads retain the atomic flag. Only freeze and mixed commits take the lock.
+    class TransactionFreezeGuard
+      include Shareable::Immutable
+
+      attr_reader :native_flag, :lock
+
+      def initialize(value)
+        @native_flag = Flag.new(value)
+        @lock = Farce::Lock.new
+        super()
+      end
+
+      def value = @native_flag.value
+
+      def set
+        @lock.synchronize do
+          yield if block_given?
+          @native_flag.set
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/transaction_map_snapshot.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # Records map dependencies without copying unobserved entries during the block.
+    # Full-map operations validate those dependencies before capturing all entries.
+    # Commit overlays staged writes onto a current snapshot for atomic publication.
+    class TransactionMapSnapshot
+      ABSENT = Object.new.freeze
+      private_constant :ABSENT
+
+      def initialize(source)
+        @source = source
+        @partial = source.class.new(
+          compare_keys_by_identity:   source.compare_keys_by_identity?,
+          compare_values_by_identity: source.compare_values_by_identity?,
+        )
+        @observations = {}
+        @writes = {}
+        if source.compare_keys_by_identity?
+          @observations.compare_by_identity
+          @writes.compare_by_identity
+        end
+        @observed_present = 0
+        @base_size = nil
+        @dirty = false
+        @full = nil
+      end
+
+      def working = self
+
+      def write!
+        @dirty = true
+        @full&.write!
+      end
+
+      def [](key)                                     = observe(key)[key]
+      def key?(key)                                   = observe(key).key?(key)
+      def store(key, value)                           = changed(key).store(key, value)
+      def swap(key, value)                            = changed(key).swap(key, value)
+      def compare_and_set(key, expected, replacement) = changed(key).compare_and_set(key, expected, replacement)
+
+      def delete(key)
+        map = changed(key)
+        @writes[key] = true unless @full
+        map.delete(key)
+      end
+
+      def size
+        return @full.working.size if @full
+        @base_size ||= @source.respond_to?(:transaction_size) ? @source.transaction_size : @source.size
+        @base_size + @partial.size - @observed_present
+      end
+
+      def getkey(key) = promote.working.getkey(key)
+      def keys = promote.working.keys
+      def clear = promote.working.clear
+      def each(&) = promote.working.each(&)
+
+      def prepare_commit
+        return @full if @full
+        if !@dirty && @observations.empty?
+          return unless @base_size
+          return @source.transaction_size_snapshot(@base_size) if @source.respond_to?(:transaction_size_snapshot)
+        end
+        promote
+      end
+
+      private
+
+      def read(source, key)
+        return source.transaction_read(key) if source.respond_to?(:transaction_read)
+        value = source.fetch(key, ABSENT)
+        [!PortableTransaction.same?(value, ABSENT), value]
+      end
+
+      def observe(key)
+        return @full.working if @full
+        unless @observations.key?(key)
+          present, value = read(@source, key)
+          @observations[key] = [present, value]
+          if present
+            @partial.store(key, value)
+            @observed_present += 1
+          end
+        end
+        @partial
+      end
+
+      def changed(key)
+        map = observe(key)
+        @writes[key] = false unless @full || @writes.key?(key)
+        map
+      end
+
+      def promote
+        return @full if @full
+        snapshot = @source.transaction_snapshot
+        current = snapshot.working
+        raise TransactionConflict, "map size changed" if @base_size && current.size != @base_size
+        @observations.each do |key, (present, value)|
+          current_present, current_value = read(current, key)
+          unless present == current_present && (!present || PortableTransaction.same?(value, current_value))
+            raise TransactionConflict, "map observation changed"
+          end
+        end
+        @writes.each do |key, deleted|
+          # Deletion followed by reinsertion must replace the stored key object.
+          current.delete(key) if deleted
+          if @partial.key?(key)
+            current.store(@partial.getkey(key), @partial[key])
+          else
+            current.delete(key)
+          end
+        end
+        snapshot.write! if @dirty
+        @full = snapshot
+      end
+    end
+  end
+end

data/lib/farce/internal/undefined.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class Undefined < BasicObject
+      define_method(:freeze,  ::Object.instance_method(:freeze))
+      define_method(:frozen?, ::Object.instance_method(:frozen?))
+
+      def initialize(inspect)
+        @inspect = inspect
+        Ractor.make_shareable(self) if defined?(Ractor)
+        freeze
+      end
+
+      attr_reader :inspect
+
+      def nil? = false
+      alias === equal?
+    end
+  end
+end

data/lib/farce/internal/unshared_lease.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Lease storage that passes its resource directly within one Ractor.
+    class UnsharedLease < LeaseState
+      include Freeze::Unfreezable
+
+      private
+
+      def initialize_resource(resource)
+        @resource = resource
+      end
+
+      def take_resource
+        resource  = @resource
+        @resource = nil
+        resource
+      end
+
+      def return_resource(resource)
+        @resource = resource
+      end
+    end
+  end
+end

data/lib/farce/internal/unshared_lease_pool.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Lease pool storage that passes resource references within one Ractor.
+    class UnsharedLeasePool < LeasePoolState
+      include Freeze::Unfreezable
+
+      private
+
+      def initialize_storage
+        @resource_lock = Mutex.new
+        @resources     = {}
+      end
+
+      def store_resource(token, resource)
+        @resource_lock.synchronize { @resources[token] = resource }
+      end
+
+      def take_resource(token)
+        @resource_lock.synchronize { @resources.delete(token) }
+      end
+
+      alias return_resource store_resource
+
+      def discard_resource(token)
+        @resource_lock.synchronize { @resources.delete(token) }
+      end
+    end
+  end
+end

data/lib/farce/internal/unshared_queue_waiting.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    module UnsharedQueueWaiting
+      # The resolved fiber waiting strategy. Other Ruby engines may return :auto.
+      attr_reader :fiber_wait
+
+      # @param fiber_wait [:auto, :io, :block] how scheduled fibers wait on CRuby
+      def initialize(fiber_wait: :auto, **)
+        @fiber_wait = fiber_wait
+        super(**)
+      end
+
+      private
+
+      def queue_signal
+        signal = Internal::UnsharedSignal.for(@fiber_wait)
+        @fiber_wait = signal.fiber_wait
+        signal
+      end
+
+      def queue_storage_class = Internal::UnsharedPriorityQueue
+    end
+  end
+end

data/lib/farce/internal/value_serialization.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Extension point for integrations that serialize a container's current value.
+    # @api private
+    module ValueSerialization
+    end
+  end
+end

data/lib/farce/internal/weak_map_value_modes.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    module WeakMapValueModes
+      include MapValueModes
+
+      # Values follow the selected mode. Keys must already be shareable.
+      # @param mode [Symbol] :raise, :make_shareable, or :dedup
+      def initialize(initial_mapping = nil, mode: :raise, **options)
+        super
+      end
+
+      def store(key, value, mode: nil, **)
+        @manager.validate_mode!(mode)
+        super
+      end
+
+      def swap(key, replacement, mode: nil, **)
+        @manager.validate_mode!(mode)
+        super
+      end
+
+      def store_if_absent(key, mode: nil, **)
+        raise LocalJumpError, "no block given" unless block_given?
+        @manager.validate_mode!(mode)
+        super
+      end
+
+      def update(key, mode: nil, **)
+        raise LocalJumpError, "no block given" unless block_given?
+        @manager.validate_mode!(mode)
+        super
+      end
+
+      def upsert(key, initial, mode: nil, **)
+        raise LocalJumpError, "no block given" unless block_given?
+        @manager.validate_mode!(mode)
+        super
+      end
+
+      def compare_and_set(key, expected, replacement, mode: nil, **)
+        @manager.validate_mode!(mode)
+        super
+      end
+
+      private
+
+      def new_mode_manager(mode:) = WeakModeManager.new(mode:)
+
+      # Expected values are comparison operands, not values to publish.
+      def wrap_comparison(value) = nil.equal?(value) ? NIL_VALUE : value
+    end
+  end
+end

data/lib/farce/internal/weak_mode_manager.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Prepare values without introducing a wrapper with an independent lifetime.
+    class WeakModeManager < ModeManager
+      MODES = %i[raise make_shareable dedup].freeze
+
+      def initialize(mode: :raise)
+        validate_mode!(mode)
+        super
+      end
+
+      def validate_mode!(mode)
+        selected = nil.equal?(mode) ? self.mode : mode
+        return selected if MODES.include?(selected)
+        raise ArgumentError, "unsupported weak value mode: #{selected.inspect}"
+      end
+
+      def wrap(value, mode: nil) = super(value, mode: validate_mode!(mode))
+    end
+  end
+end