farce 0.1.0-aarch64-linux-gnu → 0.2.0-aarch64-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/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/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/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"

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"