ractorize 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4125b52255fca881ea212e46e55e4c795e79b39f8d8369580022e67db2eb9a8
-  data.tar.gz: 91f58df84879ac297d0111f5880faf8ea95804fdb4ae17345f7702e579fbfb42
+  metadata.gz: 717f8ece3185d394b66aade1e78947eb5bb859535a8fa4afdaa88e33ad821cc9
+  data.tar.gz: af1aeaf9cc3c4b76625ba228ed5ed60cd77afde597cbcafd4ca059ca2ec52488
 SHA512:
-  metadata.gz: 691e4eb2b5a1d436b366e93256e7af917308ea3ca3292205791023f92948202464279d4e11e3251c9d842ac63e79a1d5e1a3c377747e07ced9956722a67e2d68
-  data.tar.gz: ef0e4f07687797d2036f326674150ba9ff1e5e07a604936109f4ff0e0811bb19de85d22a5834c8684ed49860cc4f27943d3a292960378c46a2c661f561e91b05
+  metadata.gz: 188fa21adfbdeff96e906f1c38ed41beeab1f4e41d6581a4494cd3245611ae457848b8f0571cd04a83ba453a539073ff4152c2ac5b72ea395d40ed4ada0df4f4
+  data.tar.gz: 2c5ffbd40dbc7f2399eed5a8350eaa86a372e2cdc2efec07389c4a16be9deeeba9c9dea1490784306126629682b4444a8b0ffc6b321469b647e71a45c2c5db16

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.0.5] - 2026-05-30
+
+- Support auto-freezing certain method-arguments
+- Support moving method arguments if they are not shareable
+- Give ractors a name to help with debugging
+
+## [0.0.4] - 2026-05-23
+
+- Prevent thunks from crossing ractor boundaries
+- Create instances of ractorized classes inside the ractor instead of moving them
+- Add support for methods that take blocks
+- Add #to_s/#inspect to RactorizedObject to help with debugging
+- Use #__send__ instead of #send to work with BasicObject
+
 ## [0.0.3] - 2026-05-21
 
 - Treat ==, !=, and ! as predicates and delegate them to the ractor (as well as #equal?)

data/README.md

@@ -68,9 +68,160 @@ took 0.195 seconds
 $
 ```
 
+## Advanced usage/some niceties
+
+### Auto-freeze non-shareable stuff passed to ractorized objects/methods
+
+Not really in the mood to track down all the strings you're sending to your ractorized objects
+that happen to be non-shareable due to not being frozen? Or maybe you're in the mood
+but don't control the code where they are being initialized? You can just auto-freeze them!
+
+You can use `Ractorize.auto_freeze` for that.
+
+A few flavors:
+
+#### Auto-freezing any instance of a class
+
+Let's just freeze all strings sent to any ractorized object.
+
+```ruby
+Ractorize.auto_freeze(String)
+
+h = Ractorize[{}]
+
+key = "foo"
+value = "bar"
+
+puts "value frozen? #{value.frozen?}"
+h[key] = value
+puts "value frozen? #{value.frozen?}"
+```
+
+This results in:
+
+```
+key frozen? false value frozen? false
+key frozen? true value frozen? true
+```
+
+#### Only auto-freezing stuff passed to a specific type of ractorized object
+
+You can specify that auto-freezing should only apply to ractorized objects of a specific class.
+
+Let's say you want to freeze stuff passed to ractorized instances of Array but not interfere with
+anything ractorized instances of Hash might be doing. You can do this like so:
+
+```ruby
+Ractorize.auto_freeze(Array, String)
+
+h = Ractorize[{}]
+
+key = "foo"
+value = "bar"
+
+puts "Before Hash#[]= value frozen? #{value.frozen?}"
+h[key] = value
+puts "After Hash#[]= value frozen? #{value.frozen?}"
+
+a = Ractorize[[]]
+
+a.push(value)
+puts "After Array#push value frozen? #{value.frozen?}"
+```
+
+This prints out:
+
+```
+Before Hash#[]= value frozen? false
+After Hash#[]= value frozen? false
+After Array#push value frozen? true
+```
+
+So only sending the string to an Array resulted in auto-freezing it.
+
+#### programmatically expressing when to auto-freeze
+
+You can also pass a proc to express whether or not to autofreeze an object:
+
+```ruby
+Ractorize.auto_freeze(Ractor.shareable_proc { it.is_a?(String) && it =~ /baz/ })
+
+a = Ractorize[[]]
+
+strings = ["foo", "bar", "baz"]
+
+strings.each { a.push(it) }
+
+puts strings.map(&:frozen?).inspect
+```
+
+This outputs:
+
+```
+[false, false, true]
+```
+
+Notice that only the last string, which meets the criteria, was frozen.
+
+### How to move arguments to the receiving ractorized object
+
+You can express that you'd like an argument to be moved to the receiving ractorized object.
+
+This allows you to not have to worry about if the argument is shareable or not.
+
+You will get errors, though, when trying to make use of the moved argument in the calling
+code, just like when using ractors directly and moving objects between them.
+
+The interface is identical to `.auto_feeze` but through the method `.move_arg`:
+
+```ruby
+class Foo
+  def object_id_of(s) = s.object_id
+end
+
+foo = Ractorize[Foo.new]
+s = "asdf"
+
+puts "calling ractor s.object_id before #push: #{s.object_id}"
+puts "object_id in receiving ractor Foo#object_id_of: #{foo.object_id_of(s)}"
+puts "s.length in calling ractor: #{s.length}"
+puts
+
+puts "Configuring all String instances to be moved to receiving ractor"
+puts
+Ractorize.move_arg(String)
+
+puts "calling ractor s.object_id before #push: #{s.object_id}"
+puts "object_id in receiving ractor Foo#object_id_of: #{foo.object_id_of(s)}"
+puts "s.length in calling ractor: #{s.length}"
+```
+
+this outputs:
+
+```
+calling ractor s.object_id before #push: 896
+object_id in receiving ractor Foo#object_id_of: 904
+s.length in calling ractor: 4
+
+Configuring all String instances to be moved to receiving ractor
+
+calling ractor s.object_id before #push: 896
+object_id in receiving ractor Foo#object_id_of: 896
+example_scripts/auto_freeze/move-arg:25:in 'Ractor::MovedObject#method_missing': can not send any methods to a moved object (Ractor::MovedError)
+```
+
+Notice that before we configure String to be moved, `foo` receives a copy of `s`, hence the different
+object_id.
+
+But once we configure String to be moved, now `foo` receives `s` instead of a copy, hence the object_id
+being the same.
+
+However, then when we try to print out the length of `s` in the calling ractor, we get a `Ractor::MovedError`.
+
 ## Gotchas
 
-### Predicate methods not ending in "?" will always return truthy values!
+### Predicate methods not ending in "?" in `if/unless/until/while/case/when/in` statements will always return truthy values!
+
 If you try to use the return value of a ractorized object (or any instance of a ractorized class)
 in a boolean expression, it will always be truthy!!
 
@@ -108,6 +259,13 @@ end
 
 This will correctly print out `It's not empty!`.
 
+Note that this isn't necessary with methods ending in "?" as this will automatically block
+and return the boolean value.
+
+Also, the predicate methods `==`, `!=` and `!` also will automatically block and return the boolean
+value, just like methods ending in "?". So you can freely do `if Ractorize["asdf"] == "asdf"` works
+perfectly fine just like predicate methods ending in "?".
+
 ### Calling a method on a closed ractorized object might result in a deadlock!
 
 It will usually raise a `Ractor::CloseError` but once in a while it can deadlock.

data/src/ractorize/ractorized_class.rb

@@ -1,16 +1,14 @@
 module Ractorize
   class RactorizedClass
     class << self
-      attr_accessor :target_class
-
       def [](klass)
         ractorized_class = Class.new(RactorizedClass)
-        ractorized_class.target_class = klass
+        ractorized_class.define_singleton_method(:target_class, Ractor.shareable_proc { klass })
         ractorized_class
       end
 
       def new(...)
-        Ractorize.ractorize_object(target_class.new(...))
+        RactorizedObject.new(:class, target_class, ...)
       end
 
       def method_missing(method_name, ...)

data/src/ractorize/ractorized_object.rb

@@ -3,18 +3,61 @@ require_relative "thunk"
 
 module Ractorize
   class RactorizedObject < BasicObject
-    def initialize(outside_object)
-      @ractor = ::Ractor.new(&RACTOR_PROC)
+    def initialize(mode, *args, **opts, &block)
+      @ractor = ::Ractor.new(name: "#{args.first}<#{args.first.object_id}>", &RACTOR_PROC)
 
-      # It doesn't seem like we have a way to move the object into the ractor via its constructor so do
-      # it with #<< instead.
-      if ::Ractor.shareable?(outside_object)
-        @ractor << outside_object
+      case mode
+      when :object
+        @ractor << :object
+
+        outside_object = args.first
+
+        @__target_class__ = outside_object.class
+
+        if ::Ractor.shareable?(outside_object)
+          @ractor << outside_object
+        else
+          ::Ractorize.resolve_all_thunks(outside_object)
+          @ractor.send(outside_object, move: true)
+        end
+      when :class
+        klass, *args = args
+
+        @__target_class__ = klass
+
+        to_move = ::Ractorize.prepare_args(@__target_class__, args, opts)
+
+        if to_move&.any?
+          @ractor << :class_arg_by_arg
+          @ractor << klass
+
+          args.each do |arg|
+            @ractor << :arg
+            @ractor.send(arg, move: to_move.include?(arg))
+          end
+
+          opts.each_pair do |name, value|
+            @ractor << :kwarg
+            @ractor << name
+            @ractor.send(value, move: to_move.include?(value))
+          end
+
+          if block
+            @ractor << :block
+            @ractor << block
+          end
+
+          @ractor << :done
+        else
+          @ractor << :class
+          @ractor << [klass, args.freeze, opts.dup.freeze, block].freeze
+        end
       else
-        @ractor.send(outside_object, move: true)
+        # :nocov:
+        ::Kernel.raise "Invalid mode #{mode}"
+        # :nocov:
       end
 
-      # Wow, this works! Scary?
       ::Object.instance_method(:freeze).bind(self).call
     end
 
@@ -26,7 +69,7 @@ module Ractorize
       self
     end
 
-    def method_missing(method_name, *args, **opts)
+    def method_missing(method_name, *args, **opts, &block)
       if @ractor.default_port.closed?
         ::Kernel.raise ::Ractor::ClosedError,
                        "You already closed this Ractorized object! No more methods can be sent to it."
@@ -34,12 +77,69 @@ module Ractorize
 
       return_port = ::Ractor::Port.new
 
-      @ractor << [method_name, args.dup.freeze, opts.dup.freeze, return_port].freeze
+      to_move = ::Ractorize.prepare_args(@__target_class__, args, opts)
+
+      if to_move&.any?
+        @ractor << [:__invoke_arg_by_arg__, [].freeze, {}.freeze, return_port, !!block]
+
+        args_port = return_port.receive
+        args_port << method_name
 
+        args.each do |arg|
+          args_port << :arg
+          args_port.send(arg, move: to_move.include?(arg))
+        end
+
+        opts.each_pair do |name, value|
+          args_port << :kwarg
+          args_port << name
+          args_port.send(value, move: to_move.include?(value))
+        end
+
+        args_port << :done
+      else
+        @ractor << [method_name, args.dup.freeze, opts.dup.freeze, return_port, !!block].freeze
+      end
+
+      if block
+        stop = false
+        value = nil
+
+        until stop
+          data = return_port.receive
+
+          # Seems SimpleCov branch coverage doesn't like that we don't test the non-exhaustive
+          # pattern path, but since that's purely defensive I have no interest in testing it.
+
+          # :nocov:
+          case data
+          # :nocov:
+          in :return, value
+            stop = true
+          in :yield, [yielded_args, yielded_opts, yielded_block], block_result_port
+            # TODO: yielded_block likely won't work when actually used
+            # so we should probably instead just raise an exception
+            # TODO: handle break and also raise in the block
+            block_result = block.call(*yielded_args.freeze, **yielded_opts.freeze, &yielded_block)
+
+            block_result = block_result.__value__ while ::Ractorize::Thunk === block_result
+
+            block_result_port << [:normal, block_result].freeze
+          end
+        end
+
+        value
       # Let's assume the user would rather block on all predicate methods than
       # incorrectly get a non-truthy value (thunk is always truthy even if it evaluates as nil/false)
-      if method_name == :== || method_name == :! || method_name == :!= || method_name.end_with?("?")
-        return_port.receive
+      elsif method_name == :== || method_name == :! || method_name == :!= ||
+            method_name == :inspect || method_name == :to_s || method_name.end_with?("?")
+        value = return_port.receive
+
+        # :nocov:
+        ::Kernel.raise ::Ractorize::Thunk::EscapingRactorError if ::Ractorize::Thunk === value
+        # :nocov:
+
+        value
       else
         Thunk.new(return_port)
       end
@@ -62,5 +162,14 @@ module Ractorize
     def !=(other) = method_missing(:==, other)
     def ! = method_missing(:!)
     def equal?(other) = method_missing(:equal?, other)
+
+    def to_s = inspect
+
+    def inspect
+      object_id = ::Object.instance_method(:object_id).bind(self).call
+      moved_object_inspect = method_missing(:inspect)
+
+      "RactorizedObject<#{object_id}>[#{moved_object_inspect}]".freeze
+    end
   end
 end

data/src/ractorize/thunk.rb

@@ -1,8 +1,11 @@
 module Ractorize
   class Thunk < BasicObject
-    attr_accessor :__return_value_port__
+    class EscapingRactorError < ::StandardError; end
+
+    attr_accessor :__return_value_port__, :__ractor__
 
     def initialize(return_value_port)
+      self.__ractor__ = ::Ractor.current
       self.__return_value_port__ = return_value_port
     end
 
@@ -10,8 +13,8 @@ module Ractorize
       # is this actually necessary?? Seems so?
     end
 
-    def method_missing(method_name, *)
-      __value__.send(method_name, *)
+    def method_missing(...)
+      __value__.__send__(...)
     end
 
     def respond_to_missing?(method_name, include_all = false)
@@ -21,15 +24,29 @@ module Ractorize
     def __value__
       return @__value__ if defined?(@__value__)
 
-      @__value__ = __return_value_port__.receive
-    end
+      value = if ::Ractor.current == __ractor__
+                __return_value_port__.receive
+              else
+                # :nocov:
+                ::Kernel.raise EscapingRactorError,
+                               "Somehow this thunk was passed between ractors but wasn't resolved first."
+                # :nocov:
+              end
 
-    def !
-      !__value__
-    end
+      # :nocov:
+      ::Kernel.raise EscapingRactorError if ::Ractorize::Thunk === value
+      # :nocov:
 
-    def ==(other)
-      __value__ == other || super
+      @__value__ = value
+
+      ::Object.instance_method(:freeze).bind(self).call
+
+      value
     end
+
+    def ! = !__value__
+    def ==(other) = __value__ == other || super
+    def !=(other) = __value__ != other || super
+    def equal?(other) = __value__.equal?(other) || super
   end
 end

data/src/ractorize.rb

@@ -3,13 +3,234 @@ require_relative "ractorize/ractorized_object"
 require_relative "ractorize/ractorized_class"
 
 module Ractorize
+  class << self
+    # TODO: figure out a way to magically get a ractor-shareable proc from a non-ractor-shareable proc
+    def auto_freeze(target, class_or_proc = nil)
+      @auto_freeze = @auto_freeze ? @auto_freeze.dup : []
+
+      unless Ractor.shareable?(target)
+        # :nocov:
+        raise "#{target} isn't shareable so can't use it to auto-freeze"
+        # :nocov:
+      end
+
+      @auto_freeze << if class_or_proc
+                        unless Ractor.shareable?(class_or_proc)
+                          # :nocov:
+                          raise "#{class_or_proc} isn't shareable so can't use it to auto-freeze"
+                          # :nocov:
+                        end
+
+                        [target, class_or_proc]
+                      else
+                        target
+                      end
+
+      @auto_freeze.freeze
+    end
+
+    def move_arg(target, class_or_proc = nil)
+      @move_arg = @move_arg ? @move_arg.dup : []
+
+      unless Ractor.shareable?(target)
+        # :nocov:
+        raise "#{target} isn't shareable so can't use it to auto-freeze"
+        # :nocov:
+      end
+
+      @move_arg << if class_or_proc
+                     unless Ractor.shareable?(class_or_proc)
+                       # :nocov:
+                       raise "#{class_or_proc} isn't shareable so can't use it to auto-freeze"
+                       # :nocov:
+                     end
+
+                     [target, class_or_proc]
+                   else
+                     target
+                   end
+
+      @move_arg.freeze
+    end
+
+    def any_thunks?(structure)
+      # rubocop:disable Lint/UnreachableLoop
+      each_thunk(structure) { return true }
+      # rubocop:enable Lint/UnreachableLoop
+      false
+    end
+
+    # Unfortunately, can't read from a port that a different ractor made.
+    # Not sure why that is but we need to handle that case.
+    def resolve_all_thunks(structure)
+      each_thunk(structure, &:__value__)
+    end
+
+    def to_move(target_class, args)
+      return unless @move_arg
+
+      move_set = nil
+
+      args.each do |arg|
+        next if Ractor.shareable?(arg)
+
+        @move_arg.each do |rule|
+          if rule.is_a?(::Array)
+            target, rule = rule
+            next unless target == target_class
+          end
+
+          move_it = if rule.is_a?(::Proc)
+                      rule.call(arg)
+                    else
+                      rule === arg
+                    end
+
+          if move_it
+            move_set ||= Set.new
+            move_set << arg
+            break
+          end
+        end
+      end
+
+      move_set
+    end
+
+    def apply_auto_freeze(target_class, arg)
+      return unless @auto_freeze
+      return if Ractor.shareable?(arg)
+
+      # TODO: should we handle instance variables like we do with thunks?
+      case arg
+      when ::Hash
+        arg.each_pair do |key, value|
+          apply_auto_freeze(target_class, key)
+          apply_auto_freeze(target_class, value)
+        end
+      when ::Array
+        arg.each { apply_auto_freeze(target_class, it) }
+      end
+
+      return if Ractor.shareable?(arg)
+
+      @auto_freeze.each do |rule|
+        if rule.is_a?(::Array)
+          target, rule = rule
+          next unless target == target_class
+        end
+
+        freeze_it = if rule.is_a?(::Proc)
+                      rule.call(arg)
+                    else
+                      rule === arg
+                    end
+
+        if freeze_it
+          arg.freeze
+          break
+        end
+      end
+    end
+
+    def prepare_args(target_class, args, opts, skip_move: false)
+      unless opts.empty?
+        args = [*args, *opts.values]
+      end
+
+      args.each { apply_auto_freeze(target_class, it) }
+
+      ::Ractorize.resolve_all_thunks(args)
+
+      return nil if skip_move
+
+      to_move(target_class, args)
+    end
+
+    def each_thunk(structure, seen = Set.new, &block)
+      return block.call(structure) if Thunk === structure
+      return if seen.include?(structure)
+
+      seen << structure
+
+      case structure
+      when Array
+        structure.each { each_thunk(it, seen, &block) }
+      when Hash
+        each_thunk(structure.keys, seen, &block)
+        each_thunk(structure.values, seen, &block)
+      when Struct
+        each_thunk(structure.values, seen, &block)
+      else
+        ivarsget = ::Object.instance_method(:instance_variables)
+        iget = ::Object.instance_method(:instance_variable_get)
+
+        ivarsget.bind(structure).call.each do |var|
+          each_thunk(iget.bind(structure).call(var), seen, &block)
+        end
+      end
+    end
+
+    def extract_args(port_like)
+      args = []
+      opts = {}
+      block = nil
+
+      loop do
+        arg_type = port_like.__send__(:receive)
+
+        case arg_type
+        when :arg
+          args << port_like.__send__(:receive)
+        when :kwarg
+          name = port_like.__send__(:receive)
+          value = port_like.__send__(:receive)
+
+          opts[name] = value
+        when :block
+          block = port_like.__send__(:receive)
+        when :done
+          break
+        else
+          # :nocov:
+          ::Kernel.raise "Unknown class_by_arg arg type #{arg_type}"
+          # :nocov:
+        end
+      end
+
+      [args, opts, block]
+    end
+  end
+
   # Putting this in a constant so we can get test coverage on it since not sure how to get coverage
   # on something inside a ractor.
   RACTOR_PROC = proc do
-    object = receive
+    mode = receive
+
+    object = case mode
+             when :class
+               klass, args, opts, block = receive
+               target_class = klass
+               klass.new(*args.freeze, **opts.freeze, &block)
+             when :object
+               o = receive
+               target_class = o.class
+               o
+             when :class_arg_by_arg
+               klass = receive
+               target_class = klass
+
+               args, opts, block = ::Ractorize.extract_args(self)
+
+               klass.new(*args.freeze, **opts.freeze, &block)
+             else
+               # :nocov:
+               ::Kernel.raise "Invalid mode #{mode}"
+               # :nocov:
+             end
 
     loop do
-      method_name, method_args, opts, return_port = receive
+      method_name, method_args, opts, return_port, block_given = receive
 
       case method_name
       when :__close__
@@ -17,20 +238,62 @@ module Ractorize
         close
         break
       else
-        value = object.__send__(method_name, *method_args, **opts)
+        if method_name == :__invoke_arg_by_arg__
+          args_port = Ractor::Port.new
+          return_port << args_port
 
-        value = value.__value__ while Thunk === value
+          method_name = args_port.receive
+          method_args, opts = ::Ractorize.extract_args(args_port)
+        end
 
-        return_port << value
+        if block_given
+          block_result_port = ::Ractor::Port.new
+
+          value = object.__send__(method_name, *method_args, **opts) do |*args, **opts, &b|
+            ::Ractorize.prepare_args(target_class, args, opts, skip_move: true)
+
+            return_port << [:yield, [args.dup.freeze, opts.dup.freeze, b].freeze, block_result_port].freeze
+
+            outcome_type, return_value = block_result_port.receive
+
+            case outcome_type
+            when :normal
+              return_value
+            when :break
+              break return_value
+            else
+              # :nocov:
+              ::Kernel.raise "Not sure how to handle outcome_type #{outcome_type}"
+              # :nocov:
+            end
+          end
+
+          return_port << [:return, value].freeze
+        else
+          value = object.__send__(method_name, *method_args, **opts)
+
+          value = value.__value__ while ::Ractorize::Thunk === value
+
+          return_port << value
+        end
       end
     end
 
     object
+  rescue => e
+    # :nocov:
+    ::Kernel.puts
+    ::Kernel.puts "an error!!! #{e.class} #{e.message} #{e}"
+    ::Kernel.puts e.backtrace
+    ::Kernel.puts
+
+    raise
+    # :nocov:
   end
 
   class << self
     def ractorize_object(object)
-      RactorizedObject.new(object)
+      RactorizedObject.new(:object, object)
     end
 
     def ractorize_class(klass)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ractorize
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
 platform: ruby
 authors:
 - Miles Georgi