ractor-shim 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bb91e5a7525967249c155d6193ebacf3b261d6db8c93c06e904aabc11810c79
-  data.tar.gz: 81882745a9a7393a06a1916c19b5324272ff5001a9883c61ea4d7d2fadb032c2
+  metadata.gz: ba3ed0a7cfb270c23651d31c50286068defa1b0492459286cabc055da64ae2c8
+  data.tar.gz: 98ed41fb52ac1676960b4d6a49d49e66920c4465a779da9b1e5f12073427cee6
 SHA512:
-  metadata.gz: 80866fae0411eb23c5e1900430763c7d1ce552f0704c911e9c65a7a7b518959f3ee85d2ce0836f4ea33291c37e0061ffa8266086ad2f78d1fc5509991729690a
-  data.tar.gz: 42fae31b67236b12e74f84b4d4942e34fe7a4f73fa9280fa971733e30c16edef9a60a8a29312aca99fcac9374050a328d86c0148121c1fffe0b9a5dfd0249477
+  metadata.gz: 55647c412c0fdecac6feb0b7fcf353c86d2114979eb6aa9ee8c1c0521c3a05e35123ea9db82ba2d808f483bfe244add8b2140cad1267121d8f1cfdeb329250c9
+  data.tar.gz: 10dd59ab7425af30137bb2fa0edf416447cdd01a16aa6601d3df57a396b1833638e78197ca4e827169223ab23d9a94fe48f7ef6ff9f8e85522303a6cd8e9dc6a

data/README.md

@@ -1,13 +1,34 @@
 # ractor-shim
 
-A shim to define `Ractor` by using `Thread`, if `Ractor` is not already defined.
+A shim to define `Ractor` by using `Thread`, `Queue`, etc if `Ractor` is not already defined.
 
-This is notably useful to run programs needing `Ractor` on Ruby implementations which don't define `Ractor.
+This is notably useful to run programs relying on `Ractor` on Ruby implementations which don't define `Ractor` such as TruffleRuby and JRuby.
+
+Note that TruffleRuby and JRuby both run Ruby code in threads in parallel, so this gem enables using the Ractor API on these Rubies and run Ractors in parallel.
+
+The gem also provides the Ruby 3.5 Ractor API  (`Ractor::Port`, `Ractor#{join,value,monitor}`, etc) for CRuby 2.7 to 3.4.
+
+When `Ractor` is not already defined, this gem implements `Ractor.make_shareable(object)` by just returning `object` to avoid unnecessary overhead.
+The main reason is that the CRuby implementation of `Ractor.make_shareable` returns an immutable object, so it won't be mutated by the program anyway and there is no need to deep freeze.
+Another reason is many gems do `Ractor.make_shareable(object) if defined?(Ractor)` and so that becomes dependent on whether `Ractor` is defined before that gem loads. That problem disappears if `Ractor.make_shareable(object)` is noop.
+
+## Installation
+
+```bash
+$ gem install ractor-shim
+```
+or
+```ruby
+# In Gemfile
+gem "ractor-shim"
+```
 
 ## Usage
 
 ```ruby
 require 'ractor/shim'
+
+Ractor.new { ... }
 ```
 
 ## Development

data/lib/ractor/shim.rb

@@ -6,6 +6,83 @@ end
 Ractor.define_singleton_method(:builtin?) { builtin_ractor }
 Ractor.define_singleton_method(:shim?) { !builtin_ractor }
 
+# Ractor::Port
+
+if Ractor.builtin?
+  class Ractor::Port
+    QUIT = Object.new.freeze
+
+    def initialize
+      @pipe = Ractor.new do
+        while true
+          msg = Ractor.receive
+          break if QUIT.equal?(msg)
+          Ractor.yield msg
+        end
+      end
+    end
+
+    def send(message)
+      @pipe.send(message)
+    end
+    alias_method :<<, :send
+
+    def receive
+      @pipe.take
+    end
+
+    def close
+      @pipe.send(QUIT)
+    end
+
+    def closed?
+      @pipe.inspect.end_with?(' terminated>')
+    end
+
+    def inspect
+      super
+    end
+  end unless defined?(Ractor::Port)
+else
+  class Ractor::Port
+    attr_reader :queue
+    private :queue
+
+    def initialize
+      @queue = Queue.new
+    end
+
+    def send(message, move: false)
+      Ractor::SELECT_MUTEX.synchronize {
+        @queue << message
+        Ractor::SELECT_CV.broadcast
+      }
+      self
+    end
+    alias_method :<<, :send
+
+    def receive
+      @queue.pop
+    end
+
+    def close
+      Ractor::SELECT_MUTEX.synchronize {
+        @queue.close
+        Ractor::SELECT_CV.broadcast
+      }
+      self
+    end
+
+    def closed?
+      @queue.closed?
+    end
+
+    def inspect
+      super
+    end
+  end
+end
+
 if Ractor.shim?
   class Ractor
     class Error < RuntimeError
@@ -56,6 +133,14 @@ if Ractor.shim?
       Ractor.current.__send__(:receive)
     end
 
+    class << self
+      alias_method :recv, :receive
+
+      def new(...)
+        super(...)
+      end
+    end
+
     # def self.select_simple_spinning(*ractors)
     #   raise ArgumentError, "specify at least one ractor or `yield_value`" if ractors.empty?
     #   while true
@@ -85,9 +170,9 @@ if Ractor.shim?
         while true
           ractors.each do |ractor_or_port|
             if Ractor === ractor_or_port
-              queue = ractor_or_port.out_queue
+              queue = ractor_or_port.__send__(:out_queue)
             elsif Ractor::Port === ractor_or_port
-              queue = ractor_or_port.queue
+              queue = ractor_or_port.__send__(:queue)
             else
               raise ArgumentError, "Unexpected argument for Ractor.select: #{ractor_or_port}"
             end
@@ -115,6 +200,14 @@ if Ractor.shim?
       true
     end
 
+    def self.[](var)
+      Ractor.current[var]
+    end
+
+    def self.[]=(var, value)
+      Ractor.current[var] = value
+    end
+
     def self.store_if_absent(var, &block)
       Ractor.current.__send__(:store_if_absent, var, &block)
     end
@@ -123,17 +216,18 @@ if Ractor.shim?
       Kernel.require(feature)
     end
 
-    attr_reader :name
+    attr_reader :name, :default_port
 
-    attr_reader :in_queue, :out_queue
+    attr_reader :out_queue
+    private :out_queue
 
     def initialize(*args, name: nil, &block)
       raise ArgumentError, "must be called with a block" unless block
       initialize_common(name, block)
+      CHANGE_COUNT.call(1)
 
       @thread = Thread.new {
         Thread.current.thread_variable_set(:current_ractor, self)
-        CHANGE_COUNT.call(1)
         begin
           result = self.instance_exec(*args, &block)
           SELECT_MUTEX.synchronize {
@@ -171,7 +265,7 @@ if Ractor.shim?
       @id = GET_ID.call
       @status = :running
       @from = block ? block.source_location.join(":") : nil
-      @in_queue = Queue.new
+      @default_port = Ractor::Port.new
       @out_queue = Queue.new
       @storage = {}
       @exception = nil
@@ -199,27 +293,27 @@ if Ractor.shim?
       end
     end
 
-    def send(message, move: false)
-      raise Ractor::ClosedError, "The port was already closed" if @status == :terminated || @in_queue.closed?
-      @in_queue << message
+    def send(message, ...)
+      raise Ractor::ClosedError, "The port was already closed" if @status == :terminated || @default_port.closed?
+      @default_port.send(message, ...)
       self
     end
     alias_method :<<, :send
 
     private def receive
-      @in_queue.pop
+      @default_port.receive
     end
 
     # def take
     #   @out_queue.pop
     # end
 
-    def close_incoming
-      @in_queue.close
+    private def close_incoming
+      @default_port.close
       self
     end
 
-    def close_outgoing
+    private def close_outgoing
       SELECT_MUTEX.synchronize {
         @out_queue.close
         SELECT_CV.broadcast
@@ -227,6 +321,11 @@ if Ractor.shim?
       self
     end
 
+    def close
+      close_incoming
+      close_outgoing
+    end
+
     def monitor(port)
       @termination_mutex.synchronize {
         if @status == :terminated
@@ -263,6 +362,7 @@ if Ractor.shim?
     def inspect
       ["#<Ractor:##{@id}", @name, @from, "#{@status}>"].compact.join(' ')
     end
+    alias_method :to_s, :inspect
 
     MAIN_RACTOR = Ractor.allocate
     MAIN_RACTOR.__send__(:initialize_main)
@@ -285,15 +385,12 @@ if Ractor.builtin?
         self == Ractor.main
       end
     end
-  end
-end
 
-# common
-class Ractor
-  unless method_defined?(:close)
-    def close
-      close_incoming
-      close_outgoing
+    unless method_defined?(:close)
+      def close
+        close_incoming
+        close_outgoing
+      end
     end
   end
 end
@@ -325,61 +422,3 @@ class << Ractor
     end
   end
 end
-
-# Ractor::Port
-
-if Ractor.builtin?
-  class Ractor::Port
-    QUIT = Object.new.freeze
-
-    def initialize
-      @pipe = Ractor.new do
-        while true
-          msg = Ractor.receive
-          break if QUIT.equal?(msg)
-          Ractor.yield msg
-        end
-      end
-    end
-
-    def <<(message)
-      @pipe.send(message)
-    end
-
-    def receive
-      @pipe.take
-    end
-
-    def close
-      @pipe.send(QUIT)
-    end
-  end unless defined?(Ractor::Port)
-else
-  class Ractor::Port
-    attr_reader :queue
-
-    def initialize
-      @queue = Queue.new
-    end
-
-    def <<(message)
-      Ractor::SELECT_MUTEX.synchronize {
-        @queue << message
-        Ractor::SELECT_CV.broadcast
-      }
-      self
-    end
-
-    def receive
-      @queue.pop
-    end
-
-    def close
-      Ractor::SELECT_MUTEX.synchronize {
-        @queue.close
-        Ractor::SELECT_CV.broadcast
-      }
-      self
-    end
-  end
-end

data/test/methods/Ractor.singleton_class.txt

@@ -0,0 +1,16 @@
+[]
+[]=
+_require
+count
+current
+main
+main?
+make_shareable
+new
+receive
+recv
+select
+shareable?
+shareable_lambda
+shareable_proc
+store_if_absent

data/test/methods/Ractor.txt

@@ -0,0 +1,13 @@
+<<
+[]
+[]=
+close
+default_port
+inspect
+join
+monitor
+name
+send
+to_s
+unmonitor
+value

data/test/methods/Ractor::Port.txt

@@ -0,0 +1,6 @@
+<<
+close
+closed?
+inspect
+receive
+send

data/test/ractor_methods_test.rb

@@ -0,0 +1,83 @@
+# Based on https://github.com/truffleruby/truffleruby/blob/master/spec/truffle/methods_spec.rb
+
+# How to regenerate files:
+#
+# - switch to MRI, the version we are compatible with
+# - run `jt -u ruby test spec/truffle/methods_spec.rb`
+
+# jt test and jt tag can be used as normal,
+# but instead of jt untag, jt purge must be used to remove tags:
+# $ jt purge spec/truffle/methods_spec.rb
+
+# socket modules are found with:
+# m1=ObjectSpace.each_object(Module).to_a; require "socket"; m2=ObjectSpace.each_object(Module).to_a; p m2-m1
+
+modules = %w[
+  Ractor Ractor.singleton_class
+  Ractor::Port Ractor::Port.singleton_class
+]
+
+def ruby(code, *flags)
+  IO.popen([RbConfig.ruby, *flags], "r+") { |pipe|
+    pipe.write code
+    pipe.close_write
+    pipe.read
+  }
+end
+
+if RUBY_ENGINE == "ruby" && RUBY_VERSION >= "3.5"
+  modules.each do |mod|
+    file = "#{__dir__}/methods/#{mod}.txt"
+    code = "puts #{mod}.public_instance_methods(false).sort"
+    methods = ruby(code)
+    methods = methods.lines.map { |line| line.chomp.to_sym }
+    contents = methods.map { |meth| "#{meth}\n" }.join
+    File.write file, contents
+  end
+end
+
+code = <<-RUBY
+require "ractor/shim"
+#{modules.inspect}.each { |m|
+  puts m
+  puts eval(m).public_instance_methods(false).sort
+  puts
+}
+RUBY
+all_methods = {}
+ruby(code, "-I#{File.dirname(__dir__)}/lib").rstrip.split("\n\n").each do |group|
+  mod, *methods = group.lines.map(&:chomp)
+  all_methods[mod] = methods.map(&:to_sym)
+end
+
+modules.each do |mod|
+  file = "#{__dir__}/methods/#{mod}.txt"
+  expected = File.readlines(file).map { |line| line.chomp.to_sym }
+  methods = all_methods[mod]
+
+  if methods != expected
+    extras = methods - expected
+    missing = expected - methods
+
+    if mod == "Ractor.singleton_class"
+      extras -= %i[builtin? shim?] # intended extras
+    end
+
+    if RUBY_ENGINE == "ruby" and RUBY_VERSION < "3.5"
+      if mod == "Ractor"
+        extras -= %i[take close_incoming close_outgoing] # expected extra on those versions
+        missing -= %i[default_port monitor unmonitor] # hard to implement on those versions
+      elsif mod == "Ractor.singleton_class"
+        extras -= %i[yield receive_if] # expected extra on those versions
+        if RUBY_VERSION < "3.4"
+          missing -= %i[[] []= store_if_absent _require] # hard to implement on those versions
+        end
+      end
+    end
+
+    raise "#{mod} methods should not include #{extras}" unless extras.empty?
+    raise "#{mod} methods should include #{missing}" unless missing.empty?
+  end
+end
+
+puts "#{__FILE__}: OK"

data/test/run_tests.rb

@@ -10,7 +10,6 @@ BUILTIN_SKIPS = [
   "SystemExit from a Thread inside a Ractor is re-raised", # Ractor::ClosedError on 3.4 instead of Ractor::RemoteError
   "Access to global-variables are prohibited (read)", # different error message on 3.4
   "Access to global-variables are prohibited (write)", # different error message on 3.4
-  "Ractor.make_shareable(a_proc) is not supported now.", # no error on 3.4
   "Ractor-local storage", # more permissive on 3.4
   "Now NoMethodError is copyable", # fails on 3.4
   "bind_call in Ractor [Bug #20934]", # SEGV on 3.4
@@ -31,6 +30,7 @@ BUILTIN_SKIPS = [
   "monitor returns false if the monitoring Ractor was terminated.", # Ractor#monitor
   "monitor port returns `:aborted` when the monitering Ractor is aborted.", # Ractor#monitor
   "monitor port returns `:aborted` even if the monitoring Ractor was aborted.", # Ractor#monitor
+  "eval with outer locals in a Ractor raises SyntaxError", # can't check
 ]
 
 SHIM_SKIPS = [
@@ -61,7 +61,6 @@ SHIM_SKIPS = [
   "ObjectSpace._id2ref can not handle unshareable objects with Ractors", # can't check
   "Ractor.make_shareable(obj)", # expected due to no freeze
   "Ractor.make_shareable(obj) doesn't freeze shareable objects", # expected due to no freeze
-  "Ractor.make_shareable(a_proc) is not supported now.", # can't check
   "Ractor.shareable?(recursive_objects)", # expected, due to all are shareable
   "Ractor.make_shareable(recursive_objects)", # expected, due to all are shareable
   "Ractor.make_shareable(obj, copy: true) makes copied shareable object.", # expected, due to all are shareable
@@ -73,9 +72,11 @@ SHIM_SKIPS = [
   "moved hashes can't be used", # expected due to no move
   "moved composite types move their non-shareable parts properly", # expected due to no move
   "Only one Ractor can call Ractor#value", # could be implemented
+  "eval with outer locals in a Ractor raises SyntaxError", # can't check
 ]
 
 GLOBAL_SKIPS = [
+  "Ractor.make_shareable(a_proc) requires a shareable receiver", # because this harness uses Object as outer self
   "threads in a ractor will killed", # leaks Ractors
   "TracePoint with normal Proc should be Ractor local", # line numbers differ due to test harness
   "Can yield back values while GC is sweeping [Bug #18117]", # too slow and leaks
@@ -90,6 +91,15 @@ GLOBAL_SKIPS = [
 skips = GLOBAL_SKIPS
 skips += BUILTIN_SKIPS if Ractor.builtin? && RUBY_VERSION < "3.5"
 skips += SHIM_SKIPS if Ractor.shim?
+if Ractor.builtin? && RUBY_VERSION >= "3.5"
+  # fails on 3.5+
+  skips += [
+    "move object with generic ivar", # SEGV
+    "move object with many generic ivars", # SEGV
+    "move object with complex generic ivars", # SEGV
+    "moved composite types move their non-shareable parts properly", # SEGV
+  ]
+end
 if Ractor.builtin? && RUBY_VERSION < "3.4"
   # fails on 3.3
   skips += [
@@ -97,7 +107,7 @@ if Ractor.builtin? && RUBY_VERSION < "3.4"
     "ivar in shareable-objects are not allowed to access from non-main Ractor",
     "ivar in shareable-objects are not allowed to access from non-main Ractor, by @iv (get)",
     "ivar in shareable-objects are not allowed to access from non-main Ractor, by @iv (set)",
-    900,
+    "defined? on ivar of module",
     "moved objects have their shape properly set to original object's shape",
     "Ractor-local storage with Thread inheritance of current Ractor",
     "require in Ractor",
@@ -112,6 +122,7 @@ if Ractor.builtin? && RUBY_VERSION < "3.3"
   # fails on 3.2
   skips += [
     "check moved object", # SEGV
+    "fstring pool 2", # spurious, probably a fstring table bug
   ]
 end
 if Ractor.builtin? && RUBY_VERSION < "3.1"
@@ -125,14 +136,11 @@ end
 if Ractor.shim? && RUBY_ENGINE == "ruby" && RUBY_VERSION < "3.0"
   # fails on 2.7
   skips += [
-    "Ractor.count",
-    "fstring pool 2", # spurious, probably a fstring table bug
     "check method cache invalidation", # syntax
   ]
 end
 if Ractor.shim? && RUBY_ENGINE == "jruby"
   skips += [
-    "Ractor.count",
     "ObjectSpace.each_object can not handle unshareable objects with Ractors",
     "fstring pool 2", # spurious, probably a fstring table bug
   ]
@@ -204,6 +212,10 @@ def generic_assert(expected, code, check, &error_message)
 
   # cleanup global state
   Object.send(:remove_const, :A) if Object.const_defined?(:A)
+
+  unless Ractor::RemoteError.is_a? Class
+    raise "Ractor::RemoteError is no longer a Class!: #{Ractor::RemoteError.inspect}"
+  end
 end
 
 def assert_equal(expected, code, frozen_string_literal: nil)
@@ -233,3 +245,5 @@ end
 Warning[:experimental] = false
 
 require_relative 'test_ractor'
+
+require_relative 'ractor_methods_test'

data/test/test_ractor.rb

@@ -1,4 +1,4 @@
-# From https://github.com/ruby/ruby/blob/master/bootstraptest/test_ractor.rb
+# From https://github.com/ruby/ruby/blob/390d77ba00f9e8f18a5408b404365db0b25fbf37/bootstraptest/test_ractor.rb
 
 # Ractor.current returns a current ractor
 assert_equal 'Ractor', %q{
@@ -255,7 +255,7 @@ assert_equal 30.times.map { 'ok' }.to_s, %q{
   30.times.map{|i|
     test i
   }
-} unless (ENV.key?('TRAVIS') && ENV['TRAVIS_CPU_ARCH'] == 'arm64') # https://bugs.ruby-lang.org/issues/17878
+} # unless (ENV.key?('TRAVIS') && ENV['TRAVIS_CPU_ARCH'] == 'arm64') # https://bugs.ruby-lang.org/issues/17878
 
 # Exception for empty select
 assert_match /specify at least one ractor/, %q{
@@ -468,6 +468,7 @@ assert_equal "ok", <<~'RUBY', frozen_string_literal: false
   echo_ractor = Ractor.new port do |port|
     loop do
       v = Ractor.receive
+      break if v == :stop
       port << v
     end
   end
@@ -527,7 +528,7 @@ assert_equal "ok", <<~'RUBY', frozen_string_literal: false
   }
 
   if results.empty?
-    port.close; echo_ractor.close; :ok
+    port.close; echo_ractor << :stop; echo_ractor.join; :ok
   else
     results.inspect
   end
@@ -756,6 +757,37 @@ assert_equal 'ArgumentError', %q{
   end
 }
 
+# eval with outer locals in a Ractor raises SyntaxError
+# [Bug #21522]
+assert_equal 'SyntaxError', %q{
+  outer = 42
+  r = Ractor.new do
+    eval("outer")
+  end
+  begin
+    r.value
+  rescue Ractor::RemoteError => e
+    e.cause.class
+  end
+}
+
+# eval of an undefined name in a Ractor raises NameError
+assert_equal 'NameError', %q{
+  r = Ractor.new do
+    eval("totally_undefined_name")
+  end
+  begin
+    r.value
+  rescue Ractor::RemoteError => e
+    e.cause.class
+  end
+}
+
+# eval of a local defined inside the Ractor works
+assert_equal '99', %q{
+  Ractor.new { inner = 99; eval("inner").to_s }.value
+}
+
 # ivar in shareable-objects are not allowed to access from non-main Ractor
 assert_equal "can not get unshareable values from instance variables of classes/modules from non-main Ractors", <<~'RUBY', frozen_string_literal: false
   class C
@@ -897,6 +929,7 @@ assert_equal '333', %q{
   a + b + c + d + e + f
 }
 
+# defined? on ivar of module
 assert_equal '["instance-variable", "instance-variable", nil]', %q{
   class C
     @iv1 = ""
@@ -1158,16 +1191,19 @@ assert_equal 'true', %q{
   [a.frozen?, a[0].frozen?] == [true, false]
 }
 
-# Ractor.make_shareable(a_proc) is not supported now.
-assert_equal 'true', %q{
-  pr = Proc.new{}
+# Ractor.make_shareable(a_proc) requires a shareable receiver
+assert_equal '[:ok, "Proc\'s self is not shareable:"]', %q{
+  pr1 = nil.instance_exec { Proc.new{} }
+  pr2 = Proc.new{}
 
-  begin
-    Ractor.make_shareable(pr)
-  rescue Ractor::Error
-    true
-  else
-    false
+  [pr1, pr2].map do |pr|
+    begin
+      Ractor.make_shareable(pr)
+    rescue Ractor::Error => e
+      e.message[/^.+?:/]
+    else
+      :ok
+    end
   end
 }
 
@@ -1265,7 +1301,7 @@ assert_equal '[:ok, :ok]', %q{
       s = 'str'
       trap(:INT){p s}
     }.join
-  rescue => Ractor::RemoteError
+  rescue Ractor::RemoteError
     a << :ok
   end
 }

metadata

@@ -1,16 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ractor-shim
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Benoit Daloze
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description:
 email:
 - eregontp@gmail.com
 executables: []
@@ -21,6 +19,11 @@ files:
 - README.md
 - Rakefile
 - lib/ractor/shim.rb
+- test/methods/Ractor.singleton_class.txt
+- test/methods/Ractor.txt
+- test/methods/Ractor::Port.singleton_class.txt
+- test/methods/Ractor::Port.txt
+- test/ractor_methods_test.rb
 - test/run_tests.rb
 - test/test_ractor.rb
 homepage: https://github.com/eregon/ractor-shim
@@ -29,7 +32,6 @@ licenses:
 metadata:
   homepage_uri: https://github.com/eregon/ractor-shim
   source_code_uri: https://github.com/eregon/ractor-shim
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -44,8 +46,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A shim to define Ractor by using Thread, if not already defined.
 test_files: []