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

data/lib/farce/local/scheduler.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable handle with an independent task scheduler in each scope.
+    #
+    # {.new} leaves each scheduler unstarted. Launch it with {#launch_thread}, or
+    # install it with `Fiber.set_scheduler`. {.create} starts a worker thread in
+    # each scope when that scope is first used. The default scope is `:ractor`.
+    #
+    # Tasks retain their blocks and argument references. {#execute} runs directly
+    # in the calling fiber. A fiber scheduler
+    # constructor must be convertible to a shareable proc for use in each Ractor.
+    # {#close} closes the current scope. {#close_all} closes all scopes and prevents
+    # new schedulers from starting. {.current} returns an {Unshared::Scheduler}.
+    #
+    # @example Start one worker in each Ractor
+    #   scheduler = Farce::Local::Scheduler.create
+    #   results = Farce::Unshared::Queue.new
+    #   scheduler.schedule { results.push(:done) }
+    #   results.pop # => :done
+    #   scheduler.close_all
+    class Scheduler < Abstract::Scheduler
+      include Shareable::Unfreezable
+      include Scoped
+      include Internal::LocalExecutorMethods
+
+      # Returns the current thread's unshared scheduler, or nil when none is installed.
+      # @param (see Abstract::Scheduler.current)
+      # @return [Unshared::Scheduler, nil]
+      def self.current(**) = Unshared::Scheduler.current(**)
+
+      # Starts a worker in this scope and retains the launch settings for other scopes.
+      # Additional options and the block are forwarded to {#initialize}.
+      # @param executor [Class, nil] Thread or a custom executor that stays in each Ractor.
+      # @param name [String, nil] Optional worker name.
+      # @param priority [Integer, nil] Optional worker thread priority.
+      # @yieldreturn [Object] Fiber scheduler to install in each worker.
+      # @return [Scheduler]
+      def self.create(executor = Thread, name: nil, priority: nil, **, &)
+        raise ArgumentError, "Local schedulers cannot launch Ractor workers" if executor && executor <= Ractor
+        worker = [executor || Thread, name && -String(name), priority && Integer(priority)].freeze
+        new(**, worker:, &)
+      end
+
+      # Creates a handle whose scoped schedulers remain unstarted.
+      # The constructor block builds the fiber scheduler when a scope is launched or installed.
+      # @!macro scopes
+      # @overload initialize(capacity: 1024, backend: Farce.config.io_backend, scope: :ractor, &constructor)
+      #   @param capacity [Integer, nil] Pending-task capacity, or nil for an unbounded queue in each scope.
+      #   @param backend [Symbol] IO backend for the built-in scheduler.
+      #   @param scope [Symbol] The scheduler scope. Defaults to :ractor.
+      #   @yieldreturn [Object] Fiber scheduler to install in each scope.
+      def initialize(capacity: 1024, backend: Internal::FROZEN_CONFIG.io_backend, scope: :ractor,
+                     worker: nil, &constructor)
+        @constructor        = prepare_constructor(constructor || Internal::FROZEN_CONFIG.fiber_scheduler_constructor)
+        @backend            = backend
+        @worker             = worker
+        @schedulers         = Strict::Map.new
+        @closed_all         = Internal::Flag.new(false)
+        @initialization_key = Object.new.freeze
+        @registration_key   = Object.new.freeze
+        super(scope:, capacity: capacity && Integer(capacity), backend:)
+      end
+
+      # Enqueue a task in the current scope, preserving its block and arguments.
+      # `mode` is ignored when `auto_local` is true. Otherwise, only local and smart modes are accepted.
+      # @overload schedule(*args, mode: :smart, auto_local: true)
+      #   @param (see Farce::Abstract::Executor#schedule)
+      #   @return [self]
+      def schedule(...) = enqueue_task(false, ...)
+
+      # (see Abstract::Scheduler#try_schedule)
+      def try_schedule(...) = enqueue_task(true, ...)
+
+      # Starts a worker for the current scope. Other scopes retain their creation behavior.
+      # @param executor [Class, nil] Thread or a custom executor that stays in this Ractor.
+      # @param name [String, nil] Optional worker name.
+      # @param priority [Integer, nil] Optional worker thread priority.
+      # @return [Thread, Object] The worker.
+      # @raise [ArgumentError] If a Ractor executor is supplied.
+      def launch(executor = Thread, name: nil, priority: nil)
+        raise ArgumentError, "Local schedulers cannot launch Ractor workers" if executor && executor <= Ractor
+        raise "Scheduler may not be reused" if @closed_all.value
+        active_scoped_value.launch(executor, name:, priority:)
+      end
+
+      # Closes the current scope and rejects new submissions there.
+      # @return [self]
+      def close
+        current_scheduler&.close
+        self
+      end
+
+      # Requests shutdown in every scope and Ractor and rejects future scopes.
+      # Does not wait for queued or running tasks to finish.
+      # @return [self]
+      def close_all
+        return self unless @closed_all.compare_and_set(false, true)
+        @schedulers.each_pair do |scheduler, queue|
+          queue.push([scheduler, :close].freeze, clock: 0)
+        rescue ClosedQueueError
+          # The owning Ractor may already have shut down its supervisor.
+          nil
+        end
+        close
+      end
+
+      # @return [Symbol] The current scope's scheduler state.
+      def state = current_scheduler&.state || :closed
+
+      # @return [Exception, nil] The current scope's scheduler error.
+      def error = current_scheduler&.error
+
+      # @return [Boolean] Whether the current scope rejects new tasks.
+      def closed? = @closed_all.value || scoped_value.closed?
+
+      # @return [Boolean] Whether the current scope is dispatching tasks.
+      def alive? = current_scheduler&.alive? || false
+
+      # @return [Ractor] The current scope's owning Ractor.
+      def owner = Ractor.current
+
+      # @param value [Ractor] The current Ractor.
+      # @raise [ArgumentError] If another owner is supplied.
+      def owner=(value)
+        raise ArgumentError, "owner must be the current Ractor" unless value == Ractor.current
+      end
+
+      # @return [Boolean] Whether a fiber scheduler constructor was supplied.
+      def wraps_external? = !@constructor.nil?
+
+      # @return [Object, nil] The fiber scheduler in the current scope, when supplied by a constructor.
+      def external_scheduler = current_scheduler&.external_scheduler
+
+      # @api private
+      def inspect_with(inspector)
+        inspector.object_group(self) do
+          inspector.attribute(:scope, scope)
+          inspector.attribute(:state, state)
+          inspector.attribute(:backend, @backend)
+          yield if block_given?
+        end
+      end
+
+      private
+
+      def enqueue_task(non_block, *, mode: :smart, auto_local: true, &block)
+        raise SchedulerClosedError, "cannot schedule task on a closed scheduler" if @closed_all.value
+        scheduler = scoped_value
+        raise SchedulerClosedError, "cannot schedule task on a closed scheduler" if scheduler.closed?
+        raise LocalJumpError, "Cannot schedule without a block" unless block
+
+        validate_local_mode(mode, auto_local)
+        register_scheduler(scheduler)
+
+        submitted =
+          if non_block
+            scheduler.try_schedule(*, mode:, auto_local:, &block)
+          else
+            scheduler.schedule(*, mode:, auto_local:, &block)
+          end
+
+        submitted && self
+      end
+
+      def current_scheduler
+        return scoped_value unless @closed_all.value
+        scheduler = Internal::Storage[self, scope:]
+        scheduler&.close
+        scheduler
+      end
+
+      # Worker setup can yield. Initialize once when fibers share a scope.
+      def scoped_value
+        storage = Internal::Storage.scope(scope)
+        scheduler = storage[self]
+        return scheduler if scheduler
+
+        initializers = Internal::Storage.store_if_absent(@initialization_key) { Internal::Storage::ThreadSafe.new }
+        initializers.store_if_absent(storage) { Internal::LeaseInitialization.new }.fetch { super }
+      end
+
+      def active_scoped_value
+        scheduler = scoped_value
+        register_scheduler(scheduler)
+        scheduler
+      end
+
+      def register_scheduler(scheduler)
+        registrations = Internal::Storage.store_if_absent(@registration_key) { Internal::Storage::ThreadSafe.new }
+        registrations.store_if_absent(scheduler) do
+          queue, reference = Internal::ThreadPoolSupervisor.current.close_handle(scheduler)
+          @schedulers[reference] = queue
+          true
+        end
+        scheduler.close if @closed_all.value
+      end
+
+      def new_scoped_value(**)
+        scheduler = Unshared::Scheduler.new(**, &@constructor)
+        if @worker && !@closed_all.value
+          register_scheduler(scheduler)
+          executor, name, priority = @worker
+          scheduler.launch(executor, name:, priority:) unless @closed_all.value
+        end
+        scheduler.close if @closed_all.value
+        scheduler
+      end
+
+      def set_scheduler!(...)
+        raise "Scheduler may not be reused" if @closed_all.value
+        active_scoped_value.set_scheduler!(...)
+      end
+    end
+  end
+end

data/lib/farce/local/scoped.rb

@@ -74,7 +74,7 @@ module Farce
         def new_copied_scoped_value(map) = map
       end
 
-      MANAGER = ModeManager.new
+      MANAGER = ModeManager.new(mode: :copy)
       private_constant :MANAGER, :Map
 
       # @!visibility private

data/lib/farce/lru_map.rb

@@ -23,7 +23,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/map.rb

@@ -30,11 +30,11 @@ module Farce
   #   class Map
   #     # @!macro map_initialization
   #     # @!macro modes
-  #     # @param mode [Symbol] The default transfer mode for values. Defaults to `:copy`.
+  #     # @param mode [Symbol] The default transfer mode for values. Defaults to `:smart`.
   #     # @return [Map]
   #     def initialize(
   #       initial_mapping = nil,
-  #       mode: :copy,
+  #       mode: :smart,
   #       normalize_keys: nil,
   #       compare_by_identity: false,
   #       compare_keys_by_identity: compare_by_identity,

data/lib/farce/mode_manager/smart_rule.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class ModeManager
+    # Class for converting values based on smart rules.
+    class SmartRule
+      SMART_MODES = %i[smart smart_raise smart_move smart_copy].freeze
+      private_constant :SMART_MODES
+
+      include Shareable::Immutable
+
+      # @note This method must be called from the main ractor.
+      # Allows you to add rules for smart wrapping of specific classes.
+      #
+      # @overload define(klass, mode = nil)
+      #   @example
+      #     # Have smart modes use the :make_shareable mode for instances of MyClass
+      #     Farce::ModeManager::SmartRule.define(MyClass, :make_shareable)
+      #
+      #   @param klass [Class] the class to define a smart wrapping rule for
+      #   @param mode [Symbol] the mode to use when wrapping instances of the class
+      #
+      # @overload define(klass)
+      #   @example
+      #     # Have smart modes use a custom block for instances of MyClass
+      #     Farce::ModeManager::SmartRule.define(MyClass) do |value, mode_manager|
+      #       raise Ractor::Error, "#{value.inspect} cannot be shared" if value.dont_share?
+      #       mode_manager.wrap(value, mode: :make_shareable)
+      #     end
+      #
+      #   @param klass [Class] the class to define a smart wrapping rule for
+      #   @yield [value, mode_manager, mode] The block will be called when wrapping an instance of klass.
+      #   @yieldparam value [BasicObject] The value being wrapped.
+      #   @yieldparam mode_manager [Farce::ModeManager] The mode manager instance.
+      #   @yieldparam mode [Symbol] The mode to use when wrapping the value, like `:smart` or `:smart_copy`.
+      #   @yieldreturn [BasicObject] The shareable version of the value.
+      #
+      # @overload define(klass)
+      #   @example
+      #     Farce::ModeManager::SmartRule.define(MyClass) do
+      #       def smart_copy(value, mode_manager) = mode_manager.wrap(value, mode: :copy)
+      #       def smart_move(value, mode_manager) = mode_manager.wrap(value, mode: :move)
+      #     end
+      #
+      #   @yield block used for defining different methods for different smart modes.
+      #   @yieldreceiver [Class] The {SmartRule} subclass.
+      #
+      # @return [Class] the defined smart rule class.
+      def self.define(klass, mode = nil, &block)
+        SMART_RULES.define(klass) do
+          if mode
+            class_eval <<~RUBY, __FILE__, __LINE__ + 1
+              def call(value, mode_manager, _) = mode_manager.wrap(value, mode: #{mode.inspect})
+            RUBY
+          end
+
+          if block_given?
+            if block.arity.zero?
+              class_eval(&block)
+              SMART_MODES.each { private it if method_defined?(it) }
+            else
+              define_method(:call, &Ractor.shareable_lambda(&block))
+            end
+          end
+        end
+      end
+
+      # @api private
+      def call(value, mode_manager, mode)
+        register = mode_manager.register || Proxy.default_register
+        return Proxy.new(value, register:) if register.dedicated_proxy?(value.class)
+        __send__(mode, value, mode_manager)
+      rescue TypeError => e
+        raise unless e.message.include?("allocator undefined for")
+        raise Ractor::IsolationError, "#{value.inspect} cannot be shared"
+      end
+
+      # @api private
+      def marshal_dump = raise TypeError, "smart rules cannot be marshaled"
+
+      private
+
+      # smart is intentionally not an alias
+      def smart(value, mode_manager)      = smart_raise(value, mode_manager)
+      def smart_raise(value, _)           = raise Ractor::IsolationError, "#{value.inspect} cannot be shared"
+      def smart_move(value, mode_manager) = mode_manager.wrap(value, mode: :move)
+
+      def smart_copy(value, mode_manager)
+        mode_manager.wrap(value, mode: :copy)
+      rescue StandardError => e
+        begin
+          mode_manager.wrap(value, mode: :marshal)
+        rescue StandardError
+          raise e, cause: e.cause
+        end
+      end
+    end
+
+    SMART_RULES = ClassMirror.new(SmartRule) { |klass, _| klass.new }
+    private_constant :SMART_RULES
+
+    SmartRule.define(Time, :make_shareable)
+
+    [Array, ::Set].each do |klass|
+      SmartRule.define(klass) do
+        def smart_copy(value, mode_manager)
+          all_shareable = true
+          mapped = value.dup.map! do |entry|
+            result = mode_manager.wrap(entry, mode: :smart_raise)
+            if mode_manager.managed_envelope?(result)
+              all_shareable = false
+              entry
+            else
+              result
+            end
+          rescue StandardError
+            all_shareable = false
+            entry
+          end
+          return super unless all_shareable
+          Ractor.make_shareable(mapped)
+        end
+
+        def smart(value, mode_manager)
+          return super unless value.all? { Ractor.shareable?(it) }
+          Ractor.make_shareable(value)
+        end
+      end
+    end
+
+    SmartRule.define(Hash) do |value, mode_manager, mode|
+      return super(value, mode_manager, mode) unless value.all? { _1.is_a?(Symbol) && Ractor.shareable?(_2) }
+      Ractor.make_shareable(value)
+    end
+  end
+end

data/lib/farce/mode_manager.rb

@@ -2,6 +2,8 @@
 # shareable_constant_value: literal
 # warn_indent: true
 
+require "farce/mode_manager/smart_rule"
+
 module Farce
   # A mode manager encapsulates logic for dealing with Ruby objects that aren't Ractor-shareable.
   # It is a perfect companion piece for APIs that require Ractor-shareable objects.
@@ -17,7 +19,7 @@ module Farce
   # class MyQueue
   #   include Farce::Shareable
   #
-  #   def initialize(capacity: 1024, mode: :copy)
+  #   def initialize(capacity: 1024, mode: :smart)
   #     @queue   = Ratomic::Queue.new(capacity)
   #     @manager = Farce::ModeManager.new(mode:)
   #   end
@@ -55,10 +57,13 @@ module Farce
     # @return [Symbol] The default mode to use when wrapping values.
     attr_reader :mode
 
+    # @return [Farce::Proxy::Register, nil] The register used for generating Farce::Proxy instances.
+    attr_reader :register
+
     # @!macro modes
     # @param mode [Symbol] The default mode to use when wrapping values. Must be one of the valid modes.
     # @param register [Proxy::Register, nil] The register to use for generating Farce::Proxy instances.
-    def initialize(mode: :copy, register: nil)
+    def initialize(mode: :smart, register: nil)
       raise ArgumentError, "invalid mode: #{mode.inspect}" unless Farce::MODES.include?(mode)
       @mode     = mode
       @register = register
@@ -87,7 +92,10 @@ module Farce
     def wrap(value, mode: nil)
       return value if Ractor.shareable?(value)
 
-      case mode || self.mode
+      case mode ||= self.mode
+      when :smart, :smart_copy, :smart_move, :smart_raise
+        return Ractor.make_shareable(-value) if value.is_a?(String)
+        SMART_RULES[value.class].call(value, self, mode)
       when :copy           then Envelope::Copy.new(value, self)
       when :dedup          then Ractor.make_shareable(Farce.dedup(value))
       when :local          then Envelope::Local.new(value, self)
@@ -97,6 +105,7 @@ module Farce
       when :raise          then raise Ractor::IsolationError, "value is not Ractor-shareable: #{value.inspect}"
       when :shareable_copy then Ractor.make_shareable(value, copy: true)
       when :proxy          then Proxy.new(value, register: @register)
+      when :marshal        then Envelope::Marshal.new(value, self)
       else raise ArgumentError, "invalid mode: #{mode.inspect}"
       end
     end

data/lib/farce/molecule.rb

@@ -21,7 +21,7 @@ module Farce
     # Create a record class with defaults for newly created atoms.
     # @!macro modes
     # @param fields [Array<Symbol, String>] the field names
-    # @param mode [Symbol, nil] the default transfer mode, or nil for :copy
+    # @param mode [Symbol, nil] the default transfer mode, or nil for :smart
     # @param compare_by_identity [Boolean, nil] the default comparison policy
     # @return [Class<Molecule>]
     def self.define(*fields, mode: nil, **, &)
@@ -32,7 +32,7 @@ module Farce
     end
 
     # @return [Symbol] the default transfer mode for new records
-    def self.default_mode = :copy
+    def self.default_mode = :smart
 
     # @!visibility private
     def self.define_member(field)