shadowlink 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e8bd23384ce00d9ad3fd1569c81ec058e7524af4690757092b0468eb81ad5f7
+  data.tar.gz: c0afe6c5a5bd2542dd030af24496c04b6711846351c0f5bb9f12ba90eab3de2a
+SHA512:
+  metadata.gz: 56ad8994440d44294b8667a98099de9521fd2b4976a204b31bf403a6150284692cb08ad6a1190984bf1b699dd18d2ea89c625f3436e4573ba928183a524754e3
+  data.tar.gz: d87e979252dcbe48228219a1ca13a989b966989ad1d7943a8b7db8dee1d01c9889e4e3267481aca1c325b103bdda28bfea6ad75a4db096c3a06dfdfb779fef75

data/.ruby-version

@@ -0,0 +1 @@
+4.0.5

data/README.md

@@ -0,0 +1,323 @@
+# ShadowLink
+
+ShadowLink is a Ruby gem that enables the exchange of objects which typically cannot be shared between Ractors by emulating them via proxies and converting them into a shareable data format.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add shadowlink
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install shadowlink
+```
+
+## Usage
+
+Objects such as ActiveRecord typically cannot be used within a Ractor.
+
+```ruby
+Ractor.new(Monster.all) do |monsters|
+  monsters.first.id # An error occurs.
+end
+```
+
+Passing an object that cannot be shared to ShadowLink converts it into a shareable proxy object.
+
+```ruby
+ShadowLink.lurk(Monster.all) do |shadow_monsters|
+  Ractor.new(shadow_monsters) do |monsters|
+    monsters.first.id
+  end.value
+end
+```
+
+You can pass multiple objects.
+
+```ruby
+ShadowLink.lurk(Fairy.new, [Octorok.new, Keese.new]) do |shadow_fairy, shadow_monsters|
+  Ractor.new(shadow_fairy, shadow_monsters) do |fairy, monsters|
+    # anything
+  end.value
+end
+```
+
+The last argument of the `ShadowLink.lurk` block is a Shadow object.
+By using the Shadow object's `#sink` method, you can shadow an object even after `ShadowLink.lurk` has executed.
+
+```ruby
+ShadowLink.lurk(Fairy.new) do |shadow_fairy, shadow|
+  shadow_octorok = shadow.sink(Octorok.new)
+  Ractor.new(shadow_fairy, shadow_octorok, shadow.sink(Keese.all)) do |fairy, octorok, keese|
+    # anything
+  end.value
+end
+```
+
+Exiting `ShadowLink.lurk` before the processing inside the Ractor completes causes the port to close, resulting in an error.
+Be sure to wait for the operation to complete using `Ractor#join` or `Ractor#value`.
+
+```ruby
+ShadowLink.lurk(Fairy.new) do |shadow_fairy|
+  Ractor.new(shadow_fairy) do |fairy|
+    sleep 1
+    fairy.id # raise 'Ractor::Port#send': The port was already closed (Ractor::ClosedError)
+  end # non wait
+end
+```
+
+If the result of the ShadowLink.lurk block is a shadowed object, the result of ShadowLink.lurk is converted to the original object and returned.
+
+```ruby
+ShadowLink.lurk(Fairy.new) do |shadow_fairy|
+  Ractor.new(shadow_fairy) do |fairy|
+    fairy # ShadowLink<Fairy> Object
+  end.value # ShadowLink<Fairy> Object
+end # Fairy Object
+```
+
+You can also retrieve the original object by using `#seek`.
+
+```ruby
+ShadowLink.lurk(Fairy.new) do |shadow_fairy, shadow|
+  result_fairy = Ractor.new(shadow_fairy) do |fairy|
+    fairy # ShadowLink<Fairy> Object
+  end.value # ShadowLink<Fairy> Object
+  shadow.seek(result_fairy) # Fairy Object
+end
+```
+
+When using ShadowLink, an error occurring at the source becomes a `Ractor::RuntimeError` within `ShadowLink.lurk`, but upon exiting `ShadowLink.lurk`, it is converted back into the original error and raised as an exception.
+
+```ruby
+begin
+  ShadowLink.lurk(-> { raise 'Gameover' }) do |shadow_process|
+    Ractor.new(shadow_process) do |process|
+      process.call
+    end.value
+  rescue
+    raise # raise Ractor::RuntimeError
+  end
+rescue
+  raise # raise Gameover (RuntimeError)
+end
+```
+
+Typically, the main process runs on a single thread, but you can increase the number of processing threads by specifying the thread count via a keyword argument.
+If you run multiple Ractors within `ShadowLink.lurk` and share tasks that involve significant I/O waiting, increasing the number of threads should improve processing efficiency.
+
+```ruby
+ShadowLink.lurk(Fairy.new, thread: 5) do |shadow_fairy|
+  5.times.map do
+    Ractor.new(shadow_fairy) do |fairy|
+      # anything
+    end
+  end.each(:join)
+end
+```
+
+ShadowLink does not convert shareable objects; it passes the data through as-is.
+Objects that cannot be shared directly are shared via proxy objects.
+As an exception, String objects are by default converted into shareable objects via `Ractor.make_shareable`.
+If there are objects other than Strings that you wish to make shareable using `Ractor.make_shareable`, you can specify them using keyword arguments.
+
+```ruby
+ShadowLink.lurk(any, make_shareables: [String, Array, Hash]) do |shadow_any|
+  Ractor.new(shadow_any) do |obj|
+    obj.to_s # Frozen original String object
+    obj.to_a # Frozen original Array object
+    obj.to_h # Frozen original Hash object
+  end.value
+end
+```
+
+If you do not want a String to be converted into a shareable object, you can prevent the conversion by specifying an array that does not contain the String.
+I wouldn't recommend it, as it causes various things to stop working.
+
+```ruby
+string = 'zelda'.dup
+ShadowLink.lurk(string, make_shareables: []) do |shadow_string|
+  Ractor.new(shadow_string) do |str|
+    str.gsub!('zelda', 'sheik')
+    # However, you cannot do `puts str`
+    puts str == 'sheik' # false
+  end.join
+end
+puts string == 'sheik' # true
+```
+
+## Performance
+
+Performance verification is conducted in the following environment.
+
+```zsh
+% system_profiler SPHardwareDataType
+Hardware:
+
+    Hardware Overview:
+
+      Model Name: MacBook Pro
+      Model Identifier: Mac16,8
+      Model Number: Z1FE000FHJ/A
+      Chip: Apple M4 Pro
+      Total Number of Cores: 12 (8 Performance and 4 Efficiency)
+      Memory: 48 GB
+      System Firmware Version: 18000.120.36
+      OS Loader Version: 18000.120.36
+
+% ruby -v 
+ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [arm64-darwin25]
+```
+
+For method calls without arguments, execution is possible with the following performance difference.
+
+```ruby
+require 'benchmark'
+
+Benchmark.bm do |x|
+  array = (1..10000).to_a
+  x.report('non ractor') do
+    array.each { array.sum }
+  end
+  x.report('use frozen object') do
+    frozen_array = array.dup.freeze
+    array.each do 
+      Ractor.new(frozen_array) { |arr| arr.sum }.join
+    end
+  end
+  x.report('use shadowlink') do
+    ShadowLink.lurk(array) do |shadow_array|
+      array.each do 
+        Ractor.new(shadow_array) { |arr| arr.sum }.join
+      end
+    end
+  end
+end
+```
+
+```
+                       user     system      total        real
+non ractor         0.084500   0.000373   0.084873 (  0.085017)
+use frozen object  0.131565   0.071487   0.203052 (  0.203015)
+use shadowlink     0.224832   0.189211   0.414043 (  0.379295)
+```
+
+Methods that accept only shareable objects as arguments can be called with the following performance differences.
+
+```ruby
+require 'benchmark'
+
+Benchmark.bm do |x|
+  array = (1..10000).to_a
+  x.report('non ractor') do
+    array.each { array.sum(0) }
+  end
+  x.report('use frozen object') do
+    frozen_array = array.dup.freeze
+    array.each do 
+      Ractor.new(frozen_array) { |arr| arr.sum(0) }.join
+    end
+  end
+  x.report('use shadowlink') do
+    ShadowLink.lurk(array) do |shadow_array|
+      array.each do 
+        Ractor.new(shadow_array) { |arr| arr.sum(0) }.join
+      end
+    end
+  end
+end
+```
+
+```
+                       user     system      total        real
+non ractor         0.082363   0.000367   0.082730 (  0.082839)
+use frozen object  0.128988   0.073280   0.202268 (  0.202182)
+use shadowlink     0.229528   0.192023   0.421551 (  0.385374)
+```
+
+Methods containing objects that cannot be shared can be called with the following performance differences.
+
+```ruby
+require 'benchmark'
+
+Benchmark.bm do |x|
+  array = (1..100).to_a
+  x.report('non ractor') do
+    array.each { array.sum { |i| i * 2 } }
+  end
+  x.report('use frozen object') do
+    frozen_array = array.dup.freeze
+    array.each do 
+      Ractor.new(frozen_array) { |arr| arr.sum { |i| i * 2 } }.join
+    end
+  end
+  x.report('use shadowlink') do
+    ShadowLink.lurk(array) do |shadow_array|
+      array.each do 
+        Ractor.new(shadow_array) { |arr| arr.sum { |i| i * 2 } }.join
+      end
+    end
+  end
+end
+```
+
+```
+                       user     system      total        real
+non ractor         0.000415   0.000014   0.000429 (  0.000426)
+use frozen object  0.002826   0.002211   0.005037 (  0.004948)
+use shadowlink     0.079253   0.076243   0.155496 (  0.149635)
+```
+
+In practice, parallelization can reduce processing time.
+For example, if you need to read characters 1,000 times with each read taking 0.001 seconds processing them in 10 parallel threads can reduce the execution time to nearly one-tenth of the original.
+
+```ruby
+require 'benchmark'
+
+Benchmark.bm do |x|
+  process = -> { sleep 0.001; 'result' }
+  x.report('non ractor') do
+    1000.times.each { process.call }
+  end
+  x.report('use thread') do
+    10.times.map do
+      Thread.new do
+        100.times.each { process.call }
+      end
+    end.each(&:join)
+  end
+  x.report('use shadowlink') do
+    ShadowLink.lurk(process, threads: 10) do |shadow_process|
+      10.times.map do
+        Ractor.new(shadow_process) do |p|
+          100.times.map { p.call }
+        end
+      end.each(&:join)
+    end
+  end
+end
+```
+
+```
+                    user     system      total        real
+non ractor      0.003898   0.010412   0.014310 (  1.269621)
+use thread      0.003713   0.013605   0.017318 (  0.127920)
+use shadowlink  0.026961   0.033084   0.060045 (  0.140258)
+```
+
+In this example, threads are faster; however, the difference lies in the ability to process conditional branching and basic arithmetic operations in parallel.
+In cases where calculations are performed simultaneously with data input and output, extremely high-speed data processing becomes possible.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ucks/shadowlink-rb.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/shadow_link/error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class ShadowLink
+  # Error is a custom error class that wraps an error raised in a shadow.
+  # It provides access to the error's shadow object.
+  class Error < StandardError
+    attr_reader :shadow
+
+    def initialize(error)
+      @shadow = error
+      super(error.message)
+      freeze
+    end
+  end
+end

data/lib/shadow_link/mirror.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class ShadowLink
+  # Mirror is a simple data structure that holds a reference to the original object and its corresponding shadow.
+  # It is used internally by the Shadow class to manage the mapping between original objects and their shadows.
+  Mirror = Struct.new(:original, :shadow)
+
+  private_constant :Mirror
+end

data/lib/shadow_link/shadow.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+class ShadowLink
+  # Shadow is a class that manages the resources required to use ShadowLink from other Ractors.
+  # It provides methods to shadowing processes and manage objects between original and shadow.
+  # ShadowLink manages resources in units of the Shadow.
+  class Shadow
+    def initialize(threads:, make_shareables:)
+      @threads = threads
+      @make_shareables = make_shareables.freeze
+    end
+
+    def start
+      raise 'Shadow is already illuminated' if @port
+
+      @port = Ractor::Port.new
+      @object_map = {}
+      @thread_pool = @threads.times.map { Thread.new { observe } }
+
+      self
+    end
+
+    def close
+      raise 'Shadow is not illuminated' unless @port
+
+      @port.close
+      @thread_pool.each(&:exit)
+      @object_map = nil
+
+      self
+    end
+
+    def sink(original)
+      raise 'Shadow is not illuminated' unless @port
+
+      return original if Ractor.shareable?(original)
+      return Ractor.make_shareable(original) if ShadowLink.make_shareable?(original, make_shareables: @make_shareables)
+
+      object_id = original.object_id
+      mirror = @object_map[object_id] ||= Mirror.new(original, ShadowLink.new(@port, object_id, make_shareables: @make_shareables))
+      mirror.shadow
+    end
+
+    def seek(shadow)
+      scoop(shadow.instance_variable_get(:@object_id))
+    end
+
+    def scoop(object_id)
+      @object_map[object_id].original
+    end
+
+    private
+
+    def observe
+      loop do
+        message = @port.receive
+        begin
+          block = ->(*args) { message[:block].call(*args.map { |arg| sink(arg) }) } if message[:block]
+          value = sink(scoop(message[:object_id])
+            .public_send(message[:name], *message[:args], **message[:kwargs], &block))
+          message[:port].send({ type: :success, value: })
+        rescue StandardError => e
+          value = sink(e)
+          message[:port].send({ type: :error, value: })
+        end
+      end
+    end
+  end
+end

data/lib/shadow_link/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ShadowLink
+  VERSION = '0.1.0'
+end

data/lib/shadow_link.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative 'shadow_link/error'
+require_relative 'shadow_link/mirror'
+require_relative 'shadow_link/shadow'
+require_relative 'shadow_link/version'
+
+# ShadowLink is a library that allows you to create a "shadow" of an object in a separate Ractor, enabling concurrent processing and communication between the original object and its shadow. It provides a way to offload work to a separate thread while maintaining a reference to the original object.
+class ShadowLink
+  DEFAULT_MAKE_SHAREABLES = [String].freeze
+
+  def initialize(port, object_id, make_shareables:)
+    @port = port
+    @object_id = object_id
+    @make_shareables = make_shareables
+    freeze
+  end
+
+  %i[to_s inspect respond_to_missing?].each do |method_name|
+    define_method(method_name) do |*args, **kwargs, &block|
+      method_missing(method_name, *args, **kwargs, &block)
+    end
+  end
+
+  def method_missing(name, *args, **kwargs, &block) # rubocop:disable Style/MissingRespondToMissing
+    process = lambda do |shadow = nil|
+      if shadow
+        args = args.map { |arg| shadow.sink(arg) }
+        kwargs = kwargs.transform_values { |value| shadow.sink(value) }
+        block = shadow.sink(block) if block
+      end
+
+      port = Ractor::Port.new
+      @port.send({ object_id: @object_id, port:, name:, args:, kwargs:, block: })
+
+      case port.receive
+      in { type: :success, value: }
+        value
+      in { type: :error, value: }
+        raise ShadowLink::Error, value
+      in message
+        raise "Unexpected message: #{message.inspect}"
+      end
+    ensure
+      port.close
+    end
+
+    convert = ->(value) { ShadowLink.make_shareable?(value, make_shareables: @make_shareables) ? Ractor.make_shareable(value) : value }
+    args = args.map(&convert)
+    kwargs = kwargs.transform_values(&convert)
+
+    has_unshareable_args = [*args, *kwargs.values, block].any? { |arg| !Ractor.shareable?(arg) }
+    has_unshareable_args ? ShadowLink.lurk(&process) : process.call
+  end
+
+  class << self
+    def lurk(*objects, threads: 1, make_shareables: DEFAULT_MAKE_SHAREABLES, &block)
+      shadow = ShadowLink::Shadow.new(threads:, make_shareables:).start
+
+      begin
+        result = yield(*objects.map { |object| shadow.sink(object) }, shadow)
+        result.is_a?(ShadowLink) ? shadow.seek(result) : result
+      rescue Ractor::RemoteError => e
+        raise (shadow.seek(e.cause.shadow) if e.cause.is_a?(ShadowLink::Error)) || e
+      rescue ShadowLink::Error => e
+        raise shadow.seek(e.shadow) || e
+      ensure
+        shadow.close
+      end
+    end
+
+    def make_shareable?(object, make_shareables: DEFAULT_MAKE_SHAREABLES)
+      return false if Ractor.shareable?(object)
+
+      case object
+      when *make_shareables
+        true
+      else
+        false
+      end
+    end
+  end
+end

data/sig/shadow_link.rbs

@@ -0,0 +1,20 @@
+# ShadowLink is a library that allows you to create a "shadow" of an object in a separate Ractor, enabling concurrent processing and communication between the original object and its shadow. It provides a way to offload work to a separate thread while maintaining a reference to the original object.
+class ShadowLink
+  @port: ::Ractor::Port?
+
+  @object_id: ::Integer
+
+  @make_shareables: ::Array[Class]
+
+  DEFAULT_MAKE_SHAREABLES: ::Array[Class]
+
+  VERSION: String
+
+  def initialize: (::Ractor::Port port, ::Integer object_id, make_shareables: ::Array[Class]) -> void
+
+  def method_missing: (::Symbol name, *untyped args, **untyped kwargs) { (?) -> untyped } -> untyped
+
+  def self.lurk: (*untyped objects, ?threads: ::Integer, ?make_shareables: ::Array[Class]) { (untyped, untyped) -> untyped } -> untyped
+
+  def self.make_shareable?: (untyped object, ?make_shareables: ::Array[Class]) -> (false | untyped)
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: shadowlink
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ucks
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: ShadowLink is a Ruby gem that enables the exchange of objects which typically
+  cannot be shared between Ractors by emulating them via proxies and converting them
+  into a shareable data format.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ruby-version"
+- README.md
+- Rakefile
+- lib/shadow_link.rb
+- lib/shadow_link/error.rb
+- lib/shadow_link/mirror.rb
+- lib/shadow_link/shadow.rb
+- lib/shadow_link/version.rb
+- sig/shadow_link.rbs
+homepage: https://github.com/ucks/shadowlink-rb
+licenses: []
+metadata:
+  homepage_uri: https://github.com/ucks/shadowlink-rb
+  source_code_uri: https://github.com/ucks/shadowlink-rb
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: This gem simplifies object sharing between Ractors.
+test_files: []