ractorize 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65a392a1b2b1f65b1886a6650dd712848aa8707f4ab76617e14ba614684660cc
-  data.tar.gz: 330eca315af85099f83374687a8526a60a239f9c84e0908b7a77a33b69130722
+  metadata.gz: 717f8ece3185d394b66aade1e78947eb5bb859535a8fa4afdaa88e33ad821cc9
+  data.tar.gz: af1aeaf9cc3c4b76625ba228ed5ed60cd77afde597cbcafd4ca059ca2ec52488
 SHA512:
-  metadata.gz: ec5f2a85e7efcc3c045051cb7a45b83900c82bbc1830deb744fed115c63acf0850067ea03e1b6a18198f19a927a6240ae09999c2fdbf9b316f924eb6fdc48557
-  data.tar.gz: c2840a3f37c61353ff66f70996043b78d997cfb969fd6946fc549aa6f572f9257d207e043fe63a388ef486ca58cd21021909b1755c5c06973cecc4d5490b6a56
+  metadata.gz: 188fa21adfbdeff96e906f1c38ed41beeab1f4e41d6581a4494cd3245611ae457848b8f0571cd04a83ba453a539073ff4152c2ac5b72ea395d40ed4ada0df4f4
+  data.tar.gz: 2c5ffbd40dbc7f2399eed5a8350eaa86a372e2cdc2efec07389c4a16be9deeeba9c9dea1490784306126629682b4444a8b0ffc6b321469b647e71a45c2c5db16

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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

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_object.rb

@@ -4,7 +4,7 @@ require_relative "thunk"
 module Ractorize
   class RactorizedObject < BasicObject
     def initialize(mode, *args, **opts, &block)
-      @ractor = ::Ractor.new(&RACTOR_PROC)
+      @ractor = ::Ractor.new(name: "#{args.first}<#{args.first.object_id}>", &RACTOR_PROC)
 
       case mode
       when :object
@@ -12,22 +12,46 @@ module Ractorize
 
         outside_object = args.first
 
-        ::Ractorize.resolve_all_thunks(outside_object)
+        @__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
-        @ractor << :class
-
         klass, *args = args
 
-        ::Ractorize.resolve_all_thunks(args)
-        ::Ractorize.resolve_all_thunks(opts)
+        @__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
 
-        @ractor << [klass, args.freeze, opts.dup.freeze, block].freeze
+          if block
+            @ractor << :block
+            @ractor << block
+          end
+
+          @ractor << :done
+        else
+          @ractor << :class
+          @ractor << [klass, args.freeze, opts.dup.freeze, block].freeze
+        end
       else
         # :nocov:
         ::Kernel.raise "Invalid mode #{mode}"
@@ -53,10 +77,29 @@ module Ractorize
 
       return_port = ::Ractor::Port.new
 
-      ::Ractorize.resolve_all_thunks(args)
-      ::Ractorize.resolve_all_thunks(opts)
+      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
 
-      @ractor << [method_name, args.dup.freeze, opts.dup.freeze, return_port, !!block].freeze
+        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

data/src/ractorize/thunk.rb

@@ -28,7 +28,8 @@ module Ractorize
                 __return_value_port__.receive
               else
                 # :nocov:
-                raise "Somehow this thunk was passed between ractors but wasn't resolved first."
+                ::Kernel.raise EscapingRactorError,
+                               "Somehow this thunk was passed between ractors but wasn't resolved first."
                 # :nocov:
               end
 
@@ -43,12 +44,9 @@ module Ractorize
       value
     end
 
-    def !
-      !__value__
-    end
-
-    def ==(other)
-      __value__ == other || super
-    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

@@ -4,6 +4,55 @@ 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 }
@@ -17,6 +66,87 @@ module Ractorize
       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)
@@ -40,6 +170,36 @@ module Ractorize
         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
@@ -50,9 +210,19 @@ module Ractorize
     object = case mode
              when :class
                klass, args, opts, block = receive
-               klass.new(*args, **opts, &block)
+               target_class = klass
+               klass.new(*args.freeze, **opts.freeze, &block)
              when :object
-               receive
+               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}"
@@ -68,12 +238,19 @@ module Ractorize
         close
         break
       else
+        if method_name == :__invoke_arg_by_arg__
+          args_port = Ractor::Port.new
+          return_port << args_port
+
+          method_name = args_port.receive
+          method_args, opts = ::Ractorize.extract_args(args_port)
+        end
+
         if block_given
-          block_result_port = Ractor::Port.new
+          block_result_port = ::Ractor::Port.new
 
           value = object.__send__(method_name, *method_args, **opts) do |*args, **opts, &b|
-            ::Ractorize.resolve_all_thunks(args)
-            ::Ractorize.resolve_all_thunks(opts)
+            ::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
 
@@ -95,7 +272,7 @@ module Ractorize
         else
           value = object.__send__(method_name, *method_args, **opts)
 
-          value = value.__value__ while Thunk === value
+          value = value.__value__ while ::Ractorize::Thunk === value
 
           return_port << value
         end

metadata

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