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

data/lib/farce/config.rb

@@ -24,7 +24,7 @@ module Farce
   class Config
     # Automatically load integrations when their dependencies are loaded. Defaults to true.
     # Can also be set via `FARCE_AUTOLOAD_INTEGRATIONS` (`true`/`false` or `1`/`0`).
-    # Set before requiring Farce to also disable startup integration loading.
+    # Set before requiring Farce to disable startup integration loading and require hooks.
     # @return [Boolean]
     attr_reader :autoload_integrations
 
@@ -63,6 +63,7 @@ module Farce
     end
 
     # Enable or disable automatic integration loading. Already loaded integrations remain active.
+    # Enabling this option installs require hooks if they are not already installed.
     # @param value [Boolean, String] true, false, or their environment variable representations.
     # @raise [ArgumentError] If the value is not a supported boolean.
     def autoload_integrations=(value)
@@ -71,6 +72,11 @@ module Farce
                                when false, "false", "0" then false
                                else raise ArgumentError, "autoload_integrations must be a boolean"
                                end
+      if @autoload_integrations && Farce.const_defined?(:Integrations, false) &&
+          !Farce.autoload?(:Integrations) && Farce.config.equal?(self)
+        Integrations.install_require_hooks
+      end
+      @autoload_integrations
     end
 
     # Default fiber scheduler for Pool and Scheduler.

data/lib/farce/engine/jruby/signal.rb

@@ -48,10 +48,13 @@ module Farce
         timeout = parse_timeout(timeout)
         observed ||= generation
 
-        scheduler = Fiber.current_scheduler if Fiber.respond_to?(:current_scheduler)
-        # JRuby may run a later scheduled fiber on a backing thread where this is nil.
-        scheduler ||= Fiber.scheduler if !Fiber.current.blocking? && Fiber.respond_to?(:scheduler)
-        return wait_with_scheduler(scheduler, observed, timeout) { yield if block_given? } if scheduler
+        # During shutdown JRuby can expose a scheduler to a blocking fiber.
+        unless Fiber.current.blocking?
+          scheduler = Fiber.current_scheduler if Fiber.respond_to?(:current_scheduler)
+          # JRuby may run a later scheduled fiber on a backing thread where this is nil.
+          scheduler ||= Fiber.scheduler if Fiber.respond_to?(:scheduler)
+          return wait_with_scheduler(scheduler, observed, timeout) { yield if block_given? } if scheduler
+        end
 
         wait_with_phaser(observed, timeout) { yield if block_given? }
       end

data/lib/farce/engine/jvm/flag.rb

@@ -8,23 +8,30 @@ module Farce
   # @!visibility private
   module Internal # :nodoc: all
     class Flag
+      include FlagWaiting
+
       def initialize(value = false) # rubocop:disable Style/OptionalBooleanParameter
         raise "Flag is already initialized" if defined?(@reference)
         check_frozen!
+        @signal = Signal.new
         @reference = JVMContainers::AtomicBoolean.new(validate_boolean(value, "initial value"))
       end
 
+      def change_signal = @signal
+
       def value = @reference.get
 
       def set # rubocop:disable Naming/PredicateMethod
         check_frozen!
         @reference.set(true)
+        @signal.broadcast
         true
       end
 
       def unset # rubocop:disable Naming/PredicateMethod
         check_frozen!
         @reference.set(false)
+        @signal.broadcast
         false
       end
 
@@ -32,20 +39,21 @@ module Farce
         check_frozen!
         value = validate_boolean(value, "value")
         @reference.set(value)
+        @signal.broadcast
         value
       end
 
       def swap(value)
         check_frozen!
         value = validate_boolean(value, "value")
-        @reference.getAndSet(value)
+        @reference.getAndSet(value).tap { @signal.broadcast }
       end
 
       def compare_and_set(expected_value, replacement_value)
         check_frozen!
         expected_value    = validate_boolean(expected_value, "expected value")
         replacement_value = validate_boolean(replacement_value, "replacement value")
-        @reference.compareAndSet(expected_value, replacement_value)
+        @reference.compareAndSet(expected_value, replacement_value).tap { |changed| @signal.broadcast if changed }
       end
 
       def toggle
@@ -53,7 +61,10 @@ module Farce
         loop do
           current = @reference.get
           replacement = !current
-          return replacement if @reference.compareAndSet(current, replacement)
+          if @reference.compareAndSet(current, replacement)
+            @signal.broadcast
+            return replacement
+          end
         end
       end
 
@@ -72,6 +83,7 @@ module Farce
       end
 
       def initialize_copy(other)
+        @signal = Signal.new
         @reference = JVMContainers::AtomicBoolean.new(other.value)
       end
     end

data/lib/farce/engine/ruby/shared/require_hook.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+# Ruby 3.4.11 and 4.0 prepend a Ractor-aware require to Kernel on activation.
+# Detect that wrapper so versions that install it on Object need no relocation.
+# A later Kernel alias captures that wrapper and loses its super target.
+# Keep the original implementation above Object so aliases capture Kernel's
+# underlying require while secondary Ractors still use Ruby's loader service.
+ractor_require = Kernel.ancestors.find { it.name == "<RactorRequire>" }
+if ractor_require
+  replacement = Module.new
+  replacement.set_temporary_name("<FarceRactorRequire>")
+  replacement.define_method(:require, ractor_require.instance_method(:require))
+  replacement.send(:private, :require)
+  Object.prepend(replacement)
+  ractor_require.remove_method(:require)
+end

data/lib/farce/engine/ruby.rb

@@ -14,6 +14,13 @@ module Farce
     ENGINE_PATH = "farce/engine/ruby/#{RUBY_VERSION[/^\d+\.\d+/]}".freeze
     private_constant :ENGINE_PATH
 
+    require "farce/engine/ruby/shared/require_hook"
+    # Older Ractor activation defines a public Object#require. Keep Ruby's
+    # ordinary private visibility even when integration hooks are disabled.
+    if Object.instance_method(:require).source_location&.first == "<internal:ractor>"
+      Object.class_eval { private :require }
+    end
+
     begin
       require "#{ENGINE_PATH}/rebind"
       require "#{ENGINE_PATH}/farce"

data/lib/farce/engine/shared/main_scheduler.rb

@@ -4,13 +4,13 @@
 
 module Farce
   module Internal # :nodoc: all
-    class MainThreadScheduler < ThreadScheduler
+    class MainThreadExecutor < ThreadExecutor
       # Enter the main emulated Ractor without starting another thread.
       def execute(...) = FakeRactor.with_current(Ractor.main) { super }
       def local?(wait: true) = Ractor.main? # rubocop:disable Lint/UnusedMethodArgument
     end
 
-    MainScheduler = MainThreadScheduler.new do |*args, &block|
+    MainScheduler = MainThreadExecutor.new do |*args, &block|
       Thread.new do
         ThreadGroup::Default.add(Thread.current)
         block.call(*args)

data/lib/farce/engine/shared/parallel_scheduler.rb

@@ -4,6 +4,6 @@
 
 module Farce
   module Internal # :nodoc: all
-    ParallelScheduler = ThreadScheduler.new(&Ractor.method(:new))
+    ParallelScheduler = ThreadExecutor.new(&Ractor.method(:new))
   end
 end

data/lib/farce/engine/shared/proxy_owner.rb

@@ -7,7 +7,7 @@ module Farce
     class ProxyOwner
       include ProxyOwnerNotifications
 
-      class OwnerScheduler < Farce::ThreadScheduler
+      class OwnerScheduler < Farce::ThreadExecutor
         def initialize
           @threads = Thread::Queue.new
           super

data/lib/farce/engine/shared/unshared_atom.rb

@@ -17,7 +17,7 @@ module Farce
         @value               = value
         @compare_by_identity = compare_by_identity
         @mutex               = Mutex.new
-        @signal              = ConditionVariable.new
+        @signal              = Signal.new
         @updating            = false
         @updating_fiber      = nil
         @updating_thread     = nil
@@ -224,13 +224,14 @@ module Farce
       end
 
       def wait_for_signal(deadline)
-        return @signal.wait(@mutex) unless deadline
-
-        remaining = deadline - Clock.now
-        return false unless remaining.positive?
-
-        @signal.wait(@mutex, remaining)
-        true
+        # Snapshot while holding the state lock so a change during registration is not missed.
+        generation = @signal.generation
+        begin
+          @mutex.unlock
+          ReservationWaiting.wait(@signal, generation, deadline)
+        ensure
+          @mutex.lock unless @mutex.owned?
+        end
       end
 
       def reject_update_wait!

data/lib/farce/engine/shared/unshared_vector.rb

@@ -252,6 +252,28 @@ module Farce
         finish_update if reservation
       end
 
+      # Yield private storage and publish it only after the block finishes.
+      # The yielded Array is never retained. Callbacks run outside the mutex.
+      def batch_update(timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        check_frozen!
+        completed, values = reserve(timeout_deadline(timeout)) do
+          snapshot = @values.dup
+          @updating = true
+          snapshot
+        end
+        return false unless completed
+        yield values
+        replacement = values.dup
+        @mutex.synchronize do
+          check_frozen_locked!
+          @values = replacement
+        end
+        true
+      ensure
+        finish_update if completed
+      end
+
       def wait_until_changed(index, expected, timeout: nil)
         wait_for_value(convert_index(index), expected, timeout_deadline(timeout), non_nil: false)
       end
@@ -272,11 +294,16 @@ module Farce
 
       def with_available(deadline)
         while true
-          generation        = @signal.generation
-          completed, result = @mutex.synchronize do
-            @updating ? [false, nil] : [true, yield]
+          generation = nil
+          result = @mutex.synchronize do
+            if @updating
+              generation = @signal.generation
+              nil
+            else
+              [true, yield]
+            end
           end
-          return [true, result] if completed
+          return result if result
           return [false, nil] unless wait_for_signal(generation, deadline)
         end
       end

data/lib/farce/engine/shared/vector.rb

@@ -72,6 +72,14 @@ module Farce
         end
       end
 
+      def batch_update(**)
+        raise LocalJumpError, "no block given" unless block_given?
+        super do |values|
+          yield values
+          values.each { check_value(it) }
+        end
+      end
+
       private
 
       def check_value(value)

data/lib/farce/engine/shared/weak_map/index.rb

@@ -184,7 +184,20 @@ module Farce
 
       def data_for(key) = Internal.garbage_collectable?(key) ? @data : @immediate
       def key_reference(key) = UnsharedWeakMapWeakReference.for(key)
-      def registry_enumerator = @entries.to_enum(:each_value)
+
+      def registry_enumerator
+        entries = @entries
+        Enumerator.new do |yielder|
+          # Compaction can rehash a weak registry and repeat earlier entries.
+          # Tokens have no back-reference to cells, keys, or values.
+          seen = {}.compare_by_identity
+          entries.each_value do |entry|
+            next if seen.key?(entry.token)
+            seen[entry.token] = true
+            yielder << entry
+          end
+        end
+      end
 
       def register(entry)
         @registry_mutex.synchronize do

data/lib/farce/engine/shared.rb

@@ -13,6 +13,15 @@ module Farce
   module Internal # :nodoc: all
     include Autoloads["#{__dir__}/shared"]
 
+    # Keep thread-only scheduler workers and their tasks in their emulated Ractor.
+    def with_scheduler_thread_group
+      group = ThreadGroup.new
+      FakeRactor::GROUPS[group] = Ractor.current
+      yield group
+    ensure
+      FakeRactor::GROUPS.delete(group)
+    end
+
     # @api private
     # The shim's shareable? can delegate to a lazy or weak value and change its state.
     # Snapshot metadata uses only structural properties on engines without Ractors.

data/lib/farce/engine/truffleruby/native/flag.rb

@@ -6,23 +6,30 @@ module Farce
   # @!visibility private
   module Internal # :nodoc: all
     class Flag
+      include FlagWaiting
+
       def initialize(value = false) # rubocop:disable Style/OptionalBooleanParameter
         raise "Flag is already initialized" if defined?(@reference)
         check_frozen!
+        @signal = Signal.new
         @reference = TruffleRuby::AtomicReference.new(validate_boolean(value, "initial value"))
       end
 
+      def change_signal = @signal
+
       def value = @reference.get
 
       def set # rubocop:disable Naming/PredicateMethod
         check_frozen!
         @reference.set(true)
+        @signal.broadcast
         true
       end
 
       def unset # rubocop:disable Naming/PredicateMethod
         check_frozen!
         @reference.set(false)
+        @signal.broadcast
         false
       end
 
@@ -30,20 +37,21 @@ module Farce
         check_frozen!
         value = validate_boolean(value, "value")
         @reference.set(value)
+        @signal.broadcast
         value
       end
 
       def swap(value)
         check_frozen!
         value = validate_boolean(value, "value")
-        @reference.get_and_set(value)
+        @reference.get_and_set(value).tap { @signal.broadcast }
       end
 
       def compare_and_set(expected_value, replacement_value)
         check_frozen!
         expected_value    = validate_boolean(expected_value, "expected value")
         replacement_value = validate_boolean(replacement_value, "replacement value")
-        @reference.compare_and_set(expected_value, replacement_value)
+        @reference.compare_and_set(expected_value, replacement_value).tap { |changed| @signal.broadcast if changed }
       end
 
       def toggle
@@ -51,7 +59,10 @@ module Farce
         loop do
           current = @reference.get
           replacement = !current
-          return replacement if @reference.compare_and_set(current, replacement)
+          if @reference.compare_and_set(current, replacement)
+            @signal.broadcast
+            return replacement
+          end
         end
       end
 
@@ -70,6 +81,7 @@ module Farce
       end
 
       def initialize_copy(other)
+        @signal = Signal.new
         @reference = TruffleRuby::AtomicReference.new(other.value)
       end
     end

data/lib/farce/envelope.rb

@@ -5,8 +5,7 @@
 module Farce
   # An envelope can be used to wrap an unshareable value in a shareable object.
   #
-  # Once created, the envelope can be shared between Ractors without any objects being moved or copied until the
-  # envelope is opened.
+  # Once created, the envelope can be shared between Ractors. Its payload is retrieved when the envelope is opened.
   #
   # When a Ractor attempts to open an envelope, it attempts "claim" it. Some envelopes may only be claimed by a single
   # Ractor, others can be claimed by any Ractor. Claims cannot be taken back.
@@ -111,6 +110,53 @@ module Farce
       def vault_key = defined?(@vault_key) ? @vault_key : self
     end
 
+    # An envelope that serializes its contents with Ruby's Marshal protocol.
+    # The snapshot is created immediately and reconstructed once per Ractor that opens it.
+    # Farce containers rebuild their storage from logical snapshots.
+    # Contents must support Marshal. Nested shareable values may be reconstructed too.
+    #
+    # @example Transfer an Unshared map
+    #   source = Farce::Unshared::Map.new({ jobs: [] })
+    #   envelope = Farce::Envelope.new(source, mode: :marshal)
+    #   envelope.value[:jobs] << :ready
+    #   source[:jobs] # => []
+    class Marshal < Farce::Envelope
+      include Copyable
+
+      # @param value [BasicObject] the value to serialize
+      # @param auto_unwrap [ModeManager, nil] the manager that may automatically open this envelope
+      # @raise [TypeError] if the value cannot be marshaled
+      def initialize(value, auto_unwrap = nil)
+        @dump = ::Marshal.dump(value).freeze
+        super
+      end
+
+      # @api private
+      def marshal_dump = [1, value, auto_unwrap]
+
+      # @api private
+      def marshal_load(data)
+        value, manager = Internal::MarshalSupport.payload(data, 2)
+        initialize(value, manager)
+        Internal::Storage.ractor[self] = value
+      end
+
+      # (see Envelope#claim)
+      def claim = self
+
+      # (see Envelope#claimed?)
+      def claimed? = true
+
+      # (see Envelope#owned?)
+      def owned? = true
+
+      protected
+
+      # The bytes are created by this envelope from its caller's value.
+      # rubocop:disable-next Security/MarshalLoad
+      def retrieve = ::Marshal.load(@dump)
+    end
+
     # An envelope that moves its contents. Can only be opened by a single Ractor.
     # The value will be moved once when the envelope is created, and then once when the envelope is opened.
     #
@@ -253,7 +299,7 @@ module Farce
     #
     # @overload new(value, mode:)
     #   @param value [BasicObject] The value to wrap in the envelope.
-    #   @param mode [Symbol, nil] The type of envelope to create. Can be `:move`, `:copy`, or `:local`.
+    #   @param mode [Symbol, nil] The type of envelope to create. Can be `:move`, `:copy`, `:marshal`, or `:local`.
     #   @return [Envelope] A new envelope wrapping the given value.
     #
     # @return [Envelope] A new envelope wrapping the given value.
@@ -265,10 +311,11 @@ module Farce
 
     def self.subclass_for(move: false, local: false, mode: nil)
       case mode
-      when :move  then Move
-      when :copy  then Copy
-      when :local then Local
-      when nil    then local ? Local : (move ? Move : Copy)
+      when :move    then Move
+      when :copy    then Copy
+      when :marshal then Marshal
+      when :local   then Local
+      when nil      then local ? Local : (move ? Move : Copy)
       else raise ArgumentError, "invalid mode: #{mode.inspect}"
       end
     end

data/lib/farce/exchanger.rb

@@ -15,7 +15,7 @@ module Farce
 
     # @!macro modes
     # @param mode [Symbol] the default mode used to transfer values between Ractors
-    def initialize(mode: :copy)
+    def initialize(mode: :smart)
       @manager   = ModeManager.new(mode:)
       @exchanger = Internal::Exchanger.new
       super()

data/lib/farce/flag.rb

@@ -23,5 +23,7 @@ module Farce
   class Flag < Internal::Flag
     include Abstract::Flag
     include Shareable::Native
+
+    private :change_signal
   end
 end

data/lib/farce/integrations/active_support.rb

@@ -2,7 +2,7 @@
 # shareable_constant_value: literal
 # warn_indent: true
 
-require "farce"
+require "farce" unless defined?(Farce::Abstract)
 require "active_support"
 require "active_support/core_ext"
 

data/lib/farce/integrations/bson.rb

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

data/lib/farce/integrations/cbor.rb

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

data/lib/farce/integrations/concurrent.rb

@@ -3,9 +3,9 @@
 # warn_indent: true
 
 # @!group concurrent-ruby Integration
-require "farce"
-require "concurrent/map"
-require "concurrent/tvar"
+require "farce"           unless defined?(Farce::Abstract)
+require "concurrent/map"  unless defined?(Concurrent::Map)
+require "concurrent/tvar" unless defined?(Concurrent::TVar)
 
 module Farce
   module Integrations

data/lib/farce/integrations/date.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+# @!group Date Integration
+require "farce" unless defined?(Farce::ModeManager)
+require "date"  unless defined?(Date)
+Farce::ModeManager::SmartRule.define(Date, :make_shareable)

data/lib/farce/integrations/dry_types.rb

@@ -3,7 +3,7 @@
 # warn_indent: true
 
 # @!group Dry Types Integration
-require "farce"
+require "farce" unless defined?(Farce::Abstract)
 require "dry/types"
 
 module Farce
@@ -70,7 +70,7 @@ module Farce
           when :shared
             return {} unless %i[vector map set atom].include?(kind)
 
-            { mode: UNDEFINED.equal?(mode) ? :copy : mode }
+            { mode: UNDEFINED.equal?(mode) ? :smart : mode }
           when :local then { scope: UNDEFINED.equal?(scope) ? :ractor : scope }
           else {}
           end
@@ -101,8 +101,11 @@ module Farce
 
           if variant == :shared
             raise ArgumentError, "scope is only supported by the local variant" unless UNDEFINED.equal?(scope)
-            raise ArgumentError, "mode :move is not supported by dry-types constructors" if mode == :move
-            return if UNDEFINED.equal?(mode) || %i[copy local make_shareable raise shareable_copy].include?(mode)
+            if %i[move smart_move].include?(mode)
+              raise ArgumentError, "mode #{mode.inspect} is not supported by dry-types constructors"
+            end
+            allowed = %i[smart smart_raise smart_copy copy local make_shareable raise shareable_copy]
+            return if UNDEFINED.equal?(mode) || allowed.include?(mode)
 
             raise ArgumentError, "invalid mode: #{mode.inspect}"
           end

data/lib/farce/integrations/json.rb

@@ -2,6 +2,6 @@
 # shareable_constant_value: literal
 # warn_indent: true
 
-require "farce"
-require "json" unless defined?(JSON::State)
+require "farce" unless defined?(Farce::Abstract)
+require "json"  unless defined?(JSON::State)
 require_relative "shared/to_json"

data/lib/farce/integrations/msgpack.rb

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

data/lib/farce/integrations/oj.rb

@@ -3,10 +3,9 @@
 # warn_indent: true
 
 # @!group Oj Integration
-require "farce"
-require "oj" unless defined?(Oj::VERSION)
-
-require "json" unless [].respond_to?(:to_json)
+require "farce" unless defined?(Farce::Abstract)
+require "oj"    unless defined?(Oj::VERSION)
+require "json"  unless [].respond_to?(:to_json)
 require_relative "shared/to_json"
 
 module Farce

data/lib/farce/integrations/psych.rb

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

data/lib/farce/integrations/ractor_sharing.rb

@@ -3,7 +3,7 @@
 # warn_indent: true
 
 # @!group ractor-sharing Integration
-require "farce"
+require "farce" unless defined?(Farce::Abstract)
 require "ractor/tvar"
 require "ractor/lockvar"
 require "ractor/lockhash"