farce 0.1.0-aarch64-linux-gnu → 0.3.0-aarch64-linux-gnu

data/lib/farce/integrations/sorted_set.rb

@@ -3,7 +3,7 @@
 # warn_indent: true
 
 # @!group SortedSet Integration
-require "farce"
+require "farce" unless defined?(Farce::Abstract)
 require "sorted_set"
 
 module Farce

data/lib/farce/integrations/weakref.rb

@@ -3,7 +3,7 @@
 # warn_indent: true
 
 # @!group WeakRef Integration
-require "farce"   unless defined?(Farce::Walker)
+require "farce"   unless defined?(Farce::Abstract)
 require "weakref" unless defined?(WeakRef)
 
 module Farce
@@ -21,6 +21,14 @@ module Farce
     end
   end
 
+  Farce::ModeManager::SmartRule.define(::WeakRef) do |value, mode_manager, mode|
+    ref   = value.__getobj__
+    value = Farce::WeakRef.new(ref)
+    super(value, mode_manager, mode)
+  rescue ::WeakRef::RefError
+    Farce::WeakRef::RECYCLED
+  end
+
   Internal::Converter.define(::WeakRef, WeakRef) do
     def convert!(ref)
       @seen.fetch(ref) do

data/lib/farce/integrations/yajl.rb

@@ -4,7 +4,7 @@
 
 # @!group Yajl Integration
 # Yajl 1.4.3 cannot encode or parse inside non-main native Ractors.
-require "farce"
-require "yajl" unless defined?(Yajl::Encoder)
-require "json" unless [].respond_to?(:to_json)
+require "farce" unless defined?(Farce::Abstract)
+require "yajl"  unless defined?(Yajl::Encoder)
+require "json"  unless [].respond_to?(:to_json)
 require_relative "shared/to_json"

data/lib/farce/integrations.rb

@@ -10,6 +10,7 @@ module Farce
       active_support: %w[active_support active_support/core_ext].freeze,
       bson:           %w[bson].freeze,
       cbor:           %w[cbor].freeze,
+      date:           %w[date].freeze,
       dry_types:      %w[dry/types].freeze,
       concurrent:     %w[concurrent/map concurrent/tvar concurrent].freeze,
       json:           %w[json].freeze,
@@ -61,28 +62,6 @@ module Farce
     end
     private_constant :RequireHook
 
-    # A prepended singleton hook can recurse when Zeitwerk aliases it. Preserve
-    # the original method explicitly instead of relying on super here.
-    class << Kernel
-      alias farce_original_require require
-      private :farce_original_require
-
-      # Load a feature and its integration through Kernel.require.
-      # @api private
-      # @param path [String, #to_path] The feature to load.
-      # @return [Boolean] Whether the requested feature was newly loaded.
-      def require(path, ...)
-        path        = File.path(path)
-        result      = Integrations.loading(path) { farce_original_require(path, ...) }
-        integration = PATHS[path.delete_suffix(".rb")]
-        if integration && !Integrations.loading?(integration) && Farce.config.autoload_integrations
-          integration_path = "farce/integrations/#{integration}"
-          Integrations.loading(integration_path) { farce_original_require(integration_path) }
-        end
-        result
-      end
-    end
-
     private_constant :INTEGRATIONS, :PATHS
 
     extend self
@@ -106,8 +85,39 @@ module Farce
     # Activate integrations at startup when automatic loading is enabled.
     # @api private
     def setup
+      return unless Farce.config.autoload_integrations
+      install_require_hooks
+      load_active
+    end
+
+    # Install hooks once, including when automatic loading is enabled later.
+    # @api private
+    def install_require_hooks
+      return if Object.ancestors.include?(RequireHook)
+      # The instance hook handles ordinary require calls. The singleton alias
+      # chain handles Kernel.require, which bypasses Object's instance methods.
       Object.prepend(RequireHook)
-      load_active if Farce.config.autoload_integrations
+      # A prepended singleton hook can recurse when Zeitwerk aliases it. Preserve
+      # the original method explicitly instead of relying on super here.
+      class << Kernel
+        alias farce_original_require require
+        private :farce_original_require
+
+        # Load a feature and its integration through Kernel.require.
+        # @api private
+        # @param path [String, #to_path] The feature to load.
+        # @return [Boolean] Whether the requested feature was newly loaded.
+        def require(path, ...)
+          path        = File.path(path)
+          result      = Integrations.loading(path) { farce_original_require(path, ...) }
+          integration = PATHS[path.delete_suffix(".rb")]
+          if integration && !Integrations.loading?(integration) && Farce.config.autoload_integrations
+            integration_path = "farce/integrations/#{integration}"
+            Integrations.loading(integration_path) { farce_original_require(integration_path) }
+          end
+          result
+        end
+      end
     end
 
     # Loads all integrations for gems that have already been loaded.

data/lib/farce/internal/flag_waiting.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    module FlagWaiting
+      # Wait until the current value differs from the expected value.
+      # @param expected [Boolean] the value to wait to change from
+      # @param timeout [Numeric, nil] the total seconds available
+      # @yield called when the timeout expires
+      # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
+      # @raise [ArgumentError] if expected is not true or false
+      def wait_until_changed(expected, timeout: nil)
+        unless expected.equal?(true) || expected.equal?(false)
+          raise ArgumentError, "expected value must be true or false"
+        end
+        signal = change_signal
+        Internal.with_timeout(timeout) do |_, deadline|
+          observed = signal.generation
+          current = value
+          return current unless expected == current
+          break unless signal.wait(observed, timeout: Internal.remaining_timeout(deadline))
+        end
+        yield if block_given?
+      end
+    end
+  end
+end

data/lib/farce/internal/freeze.rb

@@ -4,7 +4,7 @@
 
 module Farce
   module Internal
-    # Shared implementation for the explicit frozen-state policies in {Shareable}.
+    # Frozen-state policies for wrappers with separate backing storage.
     module Freeze
       # Structurally freeze a Ruby facade, then validate and publish its object graph.
       # This deliberately bypasses an override that controls logical frozen state.
@@ -20,14 +20,14 @@ module Farce
         raise FrozenError.new("can't modify frozen #{object.class}", receiver: object)
       end
 
-      # Delegate logical frozen state to storage owned by the wrapper.
+      # Freeze owned storage and the facade without freezing stored values.
       module Delegated
         def freeze
           backend = freeze_backend
           raise "#{self.class} is not initialized" unless backend
 
           backend.freeze
-          self
+          Object.instance_method(:freeze).bind_call(self)
         end
 
         def frozen?
@@ -39,6 +39,11 @@ module Farce
 
         def check_frozen! = Internal::Freeze.check(self)
 
+        def initialize_clone(other, freeze: nil)
+          super
+          self.freeze if is_a?(Farce::Unshareable) && (freeze.nil? ? other.frozen? : freeze)
+        end
+
         def publish_shareable_copy(other, operation:, freeze: nil)
           logically_frozen = operation == :clone && (freeze.nil? ? other.frozen? : freeze)
           self.freeze if logically_frozen

data/lib/farce/internal/lease_initialization.rb

@@ -5,7 +5,7 @@
 module Farce
   # @!visibility private
   module Internal # :nodoc: all
-    # Coordinates lazy Lease construction without running user code under a storage lock.
+    # Coordinates lazy construction without running user code under a storage lock.
     class LeaseInitialization
       def initialize
         @mutex        = Mutex.new

data/lib/farce/internal/local_executor_methods.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # The local scheduling and execution interface for Ractor-local executors.
+    module LocalExecutorMethods
+      LOCAL_MODES = %i[local smart smart_raise smart_move smart_copy].freeze
+      private_constant :LOCAL_MODES
+
+      # @param wait [Boolean] Accepted for compatibility with {Abstract::Executor#local?}.
+      # @return [true] Workers run in the calling Ractor.
+      def local?(wait: true) = true # rubocop:disable Lint/UnusedMethodArgument
+
+      # Run a task directly, preserving its block, arguments, and calling fiber.
+      # `mode` and `auto_local` follow the same validation as {#schedule}.
+      # @param (see Abstract::Executor#execute)
+      # @return [self]
+      def execute(*, mode: :smart, auto_local: true, &)
+        validate_local_mode(mode, auto_local)
+        super(*, mode: :local, auto_local: true, &)
+      end
+
+      private
+
+      def validate_local_mode(mode, auto_local)
+        return if auto_local || LOCAL_MODES.include?(mode)
+        raise ArgumentError, "only local or smart modes are supported"
+      end
+    end
+  end
+end

data/lib/farce/internal/local_scheduled_task.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # A Ractor-local task that retains its block and argument references.
+    class LocalScheduledTask
+      include Noncopyable
+      include Farce::Unshareable
+
+      def initialize(args, block)
+        @args  = args
+        @block = block
+        super()
+      end
+
+      def to_proc(completion = nil)
+        lambda do
+          @block.call(*@args)
+        ensure
+          completion&.task_finished
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/map_value_modes.rb

@@ -18,7 +18,7 @@ module Farce
       # @param compare_by_identity [Boolean] the default comparison mode for keys and values
       # @param compare_keys_by_identity [Boolean] whether keys are compared by identity
       # @param compare_values_by_identity [Boolean] whether values are compared by identity
-      def initialize(initial_mapping = nil, mode: :copy, normalize_keys: nil, compare_by_identity: false,
+      def initialize(initial_mapping = nil, mode: :smart, 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)
 

data/lib/farce/internal/scheduled_task.rb

@@ -12,7 +12,7 @@ module Farce
       MANAGER = ModeManager.new
 
       def initialize(args, block, mode)
-        @block  = Ractor.shareable_proc(&block)
+        @block  = Ractor.shareable?(block) ? block : Ractor.shareable_proc(&block)
         @unwrap = false
         @args   = args.map! do |arg|
           wrapped = MANAGER.wrap(arg, mode:)

data/lib/farce/internal/scheduler_lifecycle.rb

@@ -15,7 +15,7 @@ module Farce
     module SchedulerLifecycle
       include Farce::Unshareable
 
-      # Prepending bypasses Unshareable's include hook, so remove freeze here.
+      # A live scheduler must keep updating its own lifecycle state.
       def self.prepended(scheduler)
         scheduler.undef_method(:freeze)
       end

data/lib/farce/internal/thread_pool_supervisor.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # A Ractor-local service for delayed pool growth and executor shutdown requests.
+    class ThreadPoolSupervisor
+      include Farce::Unshareable
+
+      def self.current = Storage.store_if_absent(self) { new }
+
+      def initialize
+        @queue  = TimerQueue.new(mode: :raise)
+        @closed = Atom.new(false)
+        @worker = Thread.new do
+          loop do
+            entry = @queue.pop
+            break if entry == :stop
+            pool, token = entry
+            pool = pool.value
+            token == :close ? pool.close : pool.scale_if_needed(token)
+          end
+        end
+        super
+      end
+
+      def close_handle(pool) = [@queue, Envelope::Local.new(pool)].freeze
+
+      def schedule(pool, token, delay)
+        raise ::Farce::ClosedQueueError, "pool supervisor is closed" if @closed.value
+        @queue.push([Envelope::Local.new(pool), token].freeze, delay:)
+      end
+
+      def close
+        return unless @closed.compare_and_set(false, true)
+        @queue.push(:stop, clock: 0)
+        @worker.join
+        @queue.close
+      end
+    end
+
+    at_exit { Storage[ThreadPoolSupervisor]&.close }
+  end
+end

data/lib/farce/internal/unshared_pool_worker.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # A worker coordinator pinned to its pool's Ractor.
+    class UnsharedPoolWorker < PoolWorker
+      include Farce::Unshareable
+
+      private def publish_shareable = pin_unshareable
+    end
+  end
+end

data/lib/farce/internal.rb

@@ -54,6 +54,19 @@ module Farce
       new_self
     end
 
+    # @api private
+    # @return [Abstract::Executor, Fiber::Scheduler, nil]
+    def local_scheduler(create: false)
+      if Fiber.respond_to?(:scheduler) && fiber_scheduler = Fiber.scheduler
+        return fiber_scheduler
+      end
+      return Internal::MainScheduler if Ractor.main?
+      return Internal::Storage[:local_scheduler] unless create
+      Internal::Storage.store_if_absent(:local_scheduler) do
+        Internal.native_ractors? ? Scheduler.create(Thread) : ThreadExecutor.new
+      end
+    end
+
     def timeout_deadline(timeout)
       return if timeout.nil?
 
@@ -101,6 +114,7 @@ module Farce
     def prepare_mutable_numeric(_)        = nil
     def prepare_map_access(_klass, _kind) = nil
     def finalize_engine                   = nil
+    def with_scheduler_thread_group       = yield(ThreadGroup.new)
 
     def delegate(from, to, *methods)
       methods.each do |method|

data/lib/farce/lazy.rb

@@ -5,7 +5,7 @@
 module Farce
   # A ractor-shareable lazy value that is computed on demand.
   # The factory runs once. Its result is transferred according to {#mode}.
-  # With the default `:copy` mode, each Ractor receives its own cached copy.
+  # The default `:smart` mode prepares results using smart rules or dedicated proxies.
   # The factory and its bound receiver must remain Ractor-shareable.
   # Use {Strict::Lazy} for direct shareable results or {Unshared::Lazy} for local factories.
   #
@@ -63,15 +63,15 @@ module Farce
     include Shareable::Tracked
 
     # @!macro modes
-    # @overload initialize(factory, mode: :copy)
+    # @overload initialize(factory, mode: :smart)
     #   @param factory [Class, Proc, #call] the shareable factory for the value
     #   @param mode [Symbol] the transfer mode for the computed result
-    # @overload initialize(mode: :copy, self: nil)
+    # @overload initialize(mode: :smart, self: nil)
     #   @param mode [Symbol] the transfer mode for the computed result
     #   @param self [BasicObject] the shareable receiver to bind to the block
     #   @yield computes the value on first access
     #   @yieldreturn [BasicObject] the result to transfer
-    def initialize(factory = nil, mode: :copy, **, &)
+    def initialize(factory = nil, mode: :smart, **, &)
       @manager = marshal_mode_manager(mode)
       super(factory, **, &)
     end

data/lib/farce/lazy_ref.rb

@@ -6,7 +6,7 @@ module Farce
   # @!parse
   #   # A {Reference} for a {Lazy} value.
   #   #
-  #   # Results use the lazy value's transfer mode, which defaults to `:copy`.
+  #   # Results use the lazy value's transfer mode, which defaults to `:smart`.
   #   #
   #   # Calling `freeze` resolves and freezes the target. Checking `frozen?` before
   #   # the first successful freeze does not resolve it.
@@ -24,11 +24,11 @@ module Farce
   #   #   initialized.value # => 1
   #   class LazyRef < Farce::Reference
   #     # @!macro modes
-  #     # @overload initialize(factory, mode: :copy)
+  #     # @overload initialize(factory, mode: :smart)
   #     #   @param mode [Symbol] the transfer mode for the computed result
   #     #   @param [Class, Proc, #call] factory The factory to use for creating the value. Must be ractor-shareable.
   #     #
-  #     # @overload initialize(self: nil, mode: :copy)
+  #     # @overload initialize(self: nil, mode: :smart)
   #     #   @param mode [Symbol] the transfer mode for the computed result
   #     #   @yield The block to use for creating the value. Must be ractor-shareable.
   #     #   @yieldreceiver [BasicObject] The `self` parameter provided, or `nil` if not provided.

data/lib/farce/lfu_map.rb

@@ -13,7 +13,7 @@ module Farce
     # @param entries [Hash, Array<Array(BasicObject, BasicObject)>, Abstract::Map, #each, nil]
     #   Optional initial entries. Entries are stored sequentially and may be evicted.
     # @param mode [Symbol] The default value transfer mode.
-    def initialize(entries = nil, mode: :copy, **)
+    def initialize(entries = nil, mode: :smart, **)
       @manager = marshal_mode_manager(mode)
       super(entries, **)
     end

data/lib/farce/local/flag.rb

@@ -35,6 +35,9 @@ module Farce
       # @return [Boolean] the new value
       def store(value) = scoped_value.store(value)
 
+      # (see Abstract::Flag#wait_until_changed)
+      def wait_until_changed(...) = scoped_value.wait_until_changed(...)
+
       alias value= store
 
       # Replace the value and return its previous state.
@@ -60,6 +63,7 @@ module Farce
       end
 
       def new_scoped_value(...) = Internal::Flag.new(...)
+      def change_signal         = scoped_value.change_signal
     end
   end
 end

data/lib/farce/local/pool.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable handle with an independent thread pool in each scope.
+    #
+    # Each pool uses the scaling settings and fiber scheduler configured at
+    # construction. Tasks always keep their block and argument references. Only
+    # local and smart modes are accepted when `auto_local` is false. A scheduler
+    # constructor must be convertible to a shareable proc for use in each Ractor.
+    # {#close} drains only the current scope's pool. {#close_all} drains every pool
+    # across all scopes and Ractors, and prevents new pools from starting.
+    #
+    # @example Keep task state within each Ractor
+    #   pool    = Farce::Local::Pool.new(max_size: 2)
+    #   results = Farce::Unshared::Queue.new
+    #   pool.schedule { results.push(:done) }
+    #   results.pop # => :done
+    #   pool.close_all
+    class Pool < Abstract::Pool
+      include Shareable::Unfreezable
+      include Scoped
+      include Internal::LocalExecutorMethods
+
+      # (see Farce::Abstract::Pool#initialize)
+      # @!macro scopes
+      # @param scope [Symbol] The scope of the pool. Defaults to `:ractor`.
+      def initialize(min_size: 0, max_size: 4, max_inflight: 64,
+                     grow_after: 0.005, shrink_after: 30, capacity: 1024, scope: :ractor,
+                     backend: Internal::FROZEN_CONFIG.io_backend, &constructor)
+        initialize_configuration(min_size:, max_size:, max_inflight:, grow_after:, shrink_after:, backend:)
+        @constructor = prepare_constructor(constructor || Internal::FROZEN_CONFIG.fiber_scheduler_constructor)
+        @pools       = Strict::Map.new
+        @closed_all  = Internal::Flag.new(false)
+        @initialization_key = Object.new.freeze
+        super(scope:, min_size: @min_size, max_size: @max_size, max_inflight: @max_inflight,
+              grow_after: @grow_after, shrink_after: @shrink_after, capacity:, backend:)
+      end
+
+      # Stop accepting work in this scope and drain its queued tasks.
+      # @return [self]
+      def close
+        pool = @closed_all.value ? Internal::Storage[self, scope:] : scoped_value
+        pool&.close
+        self
+      end
+
+      # Stop accepting work in every scope and Ractor and request draining.
+      # Future scopes also reject submissions. Does not wait for running tasks.
+      # @return [self]
+      def close_all
+        return self unless @closed_all.compare_and_set(false, true)
+        @pools.each_pair do |pool, queue|
+          queue.push([pool, :close].freeze, clock: 0)
+        rescue ClosedQueueError
+          # The owning Ractor may already have shut down its supervisor.
+          nil
+        end
+        close
+      end
+
+      # @return [Integer] Running and starting workers in this scope.
+      def size = current_pool&.size || 0
+
+      # @return [Symbol] The current scope's pool state.
+      def state = current_pool&.state || :closed
+
+      # @return [Exception, nil] The first worker error in this scope.
+      def error = current_pool&.error
+
+      # @return [Boolean] Whether this scope rejects new tasks.
+      def closed? = @closed_all.value || super
+
+      Internal.delegate(self, :scoped_value, :drained?, :admission_generation, :wait_for_admission,
+        :admission_changed, :task_taken, :retire_worker, :worker_stopped, :scale_if_needed)
+
+      private
+
+      def enqueue_task(non_block, ...)
+        raise PoolClosedError, "cannot schedule task on a closed pool" if @closed_all.value
+        pool = scoped_value
+        submitted = non_block ? pool.try_schedule(...) : pool.schedule(...)
+        submitted && self
+      end
+
+      def current_pool
+        @closed_all.value ? Internal::Storage[self, scope:] : scoped_value
+      end
+
+      # Worker setup can yield. Initialize once when fibers share a scope.
+      def scoped_value
+        storage = Internal::Storage.scope(scope)
+        pool    = storage[self]
+        return pool if pool
+
+        initializers = Internal::Storage.store_if_absent(@initialization_key) { Internal::Storage::ThreadSafe.new }
+        initializers.store_if_absent(storage) { Internal::LeaseInitialization.new }.fetch { super }
+      end
+
+      def new_scoped_value(**)
+        pool              = Unshared::Pool.new(**, &@constructor)
+        queue, reference  = Internal::ThreadPoolSupervisor.current.close_handle(pool)
+        @pools[reference] = queue
+        pool.close if @closed_all.value
+        pool
+      end
+    end
+  end
+end