ractor-sharing 0.1.0

data/lib/ractor/active_object/future.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+class Ractor
+  class ActiveObject
+    # Result handle returned by +future+ invocations.
+    #
+    # Only the Ractor that issued the invocation may call #value / #wait,
+    # because the underlying reply port belongs to that Ractor.
+    class Future
+      def initialize(port)
+        @port = port
+        @mutex = Mutex.new
+        @state = :pending # :pending | :fulfilled | :rejected
+        @result = nil
+      end
+
+      # Pre-resolved futures, used when the caller is already the owner.
+      def self.__ao_fulfilled__(value) = new(nil).tap { |f| f.__ao_settle__(:fulfilled, value) }
+      def self.__ao_rejected__(exc)    = new(nil).tap { |f| f.__ao_settle__(:rejected, exc) }
+
+      # Waits for completion. Returns self; never raises for a rejected future.
+      def wait
+        @mutex.synchronize do
+          if @state == :pending
+            status, payload, backtrace = @port.receive
+            @port = nil
+            if status == :ok
+              __ao_settle__(:fulfilled, payload)
+            else
+              __ao_settle__(:rejected, ActiveObject.__ao_restore_exception__(payload, backtrace))
+            end
+          end
+        end
+        self
+      end
+
+      # Waits for completion and returns the method's return value, or
+      # re-raises the exception the method raised on the owner Ractor.
+      def value
+        wait
+        raise @result if @state == :rejected
+        @result
+      end
+
+      # True once #wait / #value has observed the result. Does not poll.
+      def resolved? = @state != :pending
+
+      def rejected? = @state == :rejected
+
+      def __ao_settle__(state, result)
+        @state = state
+        @result = result
+      end
+
+      def inspect = "#<#{self.class} #{@state}>"
+    end
+  end
+end

data/lib/ractor/active_object.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require_relative "active_object/future"
+
+class Ractor
+  # Active Object pattern on Ractors: each instance's state lives in its own
+  # owner Ractor. `Foo.new` returns a proxy that publishes only the methods
+  # declared with sync/async/future; they are executed on the owner one at a
+  # time. See README.md.
+  class ActiveObject
+    class Error < ::Ractor::Error; end
+
+    POLICIES = %i[sync async future].freeze
+
+    DEF_NAME = /\A(?:[[:alpha:]_][[:alnum:]_]*[?!=]?|[+\-*\/%&|^<>~!`]|\*\*|[=!]=|<=|>=|<=>|===|=~|!~|<<|>>|\[\]=?|[+\-]@)\z/
+    private_constant :DEF_NAME
+
+    # Shared by proxies and servants: explicit *_send and the remote protocol.
+    module Dispatch
+      # The Ractor that owns the object's state.
+      def owner = @__ao_owner__
+
+      # True when called from the owner Ractor.
+      def owner? = Ractor.current.equal?(@__ao_owner__)
+
+      def sync_send(name, *args, **kwargs, &block)   = __ao_call__(:sync, name.to_sym, args, kwargs, block)
+      def async_send(name, *args, **kwargs, &block)  = __ao_call__(:async, name.to_sym, args, kwargs, block)
+      def future_send(name, *args, **kwargs, &block) = __ao_call__(:future, name.to_sym, args, kwargs, block)
+
+      private
+
+      def __ao_call__(policy, name, args, kwargs, block)
+        return __ao_remote__(policy, name, args, kwargs, block) unless Ractor.current.equal?(@__ao_owner__)
+
+        servant = Ractor[:__ao_servant__]
+        case policy
+        when :sync  then servant.__send__(name, *args, **kwargs, &block)
+        when :async then servant.__send__(name, *args, **kwargs, &block); nil
+        when :future
+          begin
+            Future.__ao_fulfilled__(servant.__send__(name, *args, **kwargs, &block))
+          rescue Exception => e
+            Future.__ao_rejected__(e)
+          end
+        end
+      end
+
+      def __ao_remote__(policy, name, args, kwargs, block)
+        port = @__ao_port__
+        raise Error, "#{self.class} instance was not created by .new (no owner Ractor)" unless port
+        raise ArgumentError, "block is not supported for remote invocation (#{name})" if block
+
+        case policy
+        when :sync
+          status, payload, backtrace = ActiveObject.__ao_sync_call__ do |reply|
+            __ao_post__(port, [:sync, reply, name, args, kwargs])
+          end
+          raise ActiveObject.__ao_restore_exception__(payload, backtrace) if status == :raise
+          payload
+        when :async
+          __ao_post__(port, [:async, nil, name, args, kwargs])
+          nil
+        when :future
+          reply = Ractor::Port.new
+          __ao_post__(port, [:future, reply, name, args, kwargs])
+          Future.new(reply)
+        else
+          raise ArgumentError, "unknown invocation policy: #{policy.inspect}"
+        end
+      end
+
+      def __ao_post__(port, request)
+        port << request
+      rescue Ractor::ClosedError
+        raise Error, "owner Ractor #{@__ao_owner__.inspect} terminated"
+      end
+    end
+
+    # Base of the per-class proxy classes (Foo::Proxy). A proxy is frozen and
+    # shareable and has one method per declared (published) method of Foo.
+    class Proxy
+      include Dispatch
+
+      def initialize(owner, port)
+        @__ao_owner__ = owner
+        @__ao_port__ = port
+      end
+
+      # The Ractor::ActiveObject subclass this proxy stands for.
+      def active_object_class = self.class.active_object_class
+
+      def inspect = "#<#{self.class} owner=#{@__ao_owner__.inspect}>"
+
+      class << self
+        attr_reader :active_object_class
+
+        def __ao_bind__(klass)
+          @active_object_class = klass
+          klass.const_set(:Proxy, self) # named Foo::Proxy
+          self
+        end
+      end
+    end
+
+    include Dispatch
+
+    @__ao_policies__ = {}.freeze
+    @__ao_proxy_class__ = Proxy
+
+    class << self
+      # Creates the owner Ractor, runs +initialize+ there and returns a
+      # shareable proxy which forwards declared methods to the owner.
+      def new(*args, **kwargs, &block)
+        raise ArgumentError, "#{self}.new does not accept a block (it cannot be sent to the owner Ractor)" if block
+
+        boot = Ractor::Port.new
+        owner = Ractor.new(self, args, kwargs, boot, name: "ActiveObject(#{self})") do |klass, a, kw, b|
+          Ractor::ActiveObject.__ao_run__(klass, a, kw, b)
+        end
+        # Only here: the owner may die before it can answer (e.g. .allocate fails).
+        src, (status, payload, backtrace) = Ractor.select(boot, owner)
+        raise Error, "owner Ractor #{owner.inspect} terminated during initialization" if src.equal?(owner)
+        raise __ao_restore_exception__(payload, backtrace) if status == :raise
+
+        Ractor.make_shareable(proxy_class.new(owner, payload))
+      end
+
+      # Class of the proxies returned by .new (a subclass of ActiveObject::Proxy).
+      def proxy_class = @__ao_proxy_class__
+
+      # --- policy DSL -------------------------------------------------------
+
+      # Publish already defined methods on the proxy with the given policy:
+      #   sync def foo ... end
+      #   async :bar, :baz
+      def sync(*names)   = __ao_declare__(:sync, names)
+      def async(*names)  = __ao_declare__(:async, names)
+      def future(*names) = __ao_declare__(:future, names)
+
+      # Policy of +name+ (:sync, :async or :future), or nil if not published.
+      def invocation_policy(name)
+        name = name.to_sym
+        klass = self
+        while klass
+          table = klass.instance_variable_get(:@__ao_policies__)
+          return table[name] if table&.key?(name)
+          klass = klass.superclass
+        end
+        nil
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@__ao_policies__, {}.freeze)
+        subclass.instance_variable_set(:@__ao_proxy_class__, Class.new(proxy_class).__ao_bind__(subclass))
+      end
+
+      # --- internals --------------------------------------------------------
+
+      def __ao_declare__(policy, names)
+        raise ArgumentError, "#{policy} requires method name(s), e.g. `#{policy} def foo; end`" if names.empty?
+        raise TypeError, "#{self} is not a subclass of Ractor::ActiveObject" if equal?(Ractor::ActiveObject)
+
+        names = names.flatten.map(&:to_sym)
+        names.each do |n|
+          unless method_defined?(n) || private_method_defined?(n)
+            raise NameError.new("undefined method '#{n}' for class '#{self}'", n)
+          end
+          # The table is read from any Ractor, so replace it by a shareable copy.
+          @__ao_policies__ = Ractor.make_shareable(@__ao_policies__.merge(n => policy))
+          __ao_define_proxy_method__(n, policy)
+        end
+        names.size == 1 ? names[0] : names
+      end
+      private :__ao_declare__
+
+      def __ao_define_proxy_method__(name, policy)
+        proxy = proxy_class
+        sym = name.inspect
+        # A string def has no closure, so the method is callable from any Ractor.
+        body = <<~RUBY
+          if Ractor.current.equal?(@__ao_owner__)
+            Ractor[:__ao_servant__].__send__(#{sym}, *args, **kwargs, &block)
+          else
+            __ao_remote__(#{policy.inspect}, #{sym}, args, kwargs, block)
+          end
+        RUBY
+        proxy.remove_method(name) if proxy.method_defined?(name, false)
+        if name.match?(DEF_NAME)
+          proxy.class_eval("def #{name}(*args, **kwargs, &block)\n#{body}end", __FILE__, __LINE__)
+        else
+          proxy.class_eval("define_method(#{sym}, &Ractor.shareable_proc { |*args, **kwargs, &block|\n#{body}})", __FILE__, __LINE__)
+        end
+      end
+      private :__ao_define_proxy_method__
+
+      # Owner Ractor body: build the servant, run initialize, then serve requests.
+      def __ao_run__(klass, args, kwargs, boot)
+        port = Ractor::Port.new
+        servant = klass.allocate
+        servant.instance_variable_set(:@__ao_owner__, Ractor.current)
+        servant.instance_variable_set(:@__ao_port__, port)
+        Ractor[:__ao_servant__] = servant
+
+        begin
+          servant.__send__(:initialize, *args, **kwargs)
+        rescue Exception => e
+          __ao_reply__(boot, :raise, e)
+          return
+        end
+        boot << [:ok, port]
+
+        proxy = klass.proxy_class.new(Ractor.current, port).freeze
+        pending = pending_name = nil
+        begin
+          loop do
+            kind, reply, name, rargs, rkwargs = port.receive
+            pending, pending_name = (kind == :async ? nil : reply), name
+            begin
+              result = servant.__send__(name, *rargs, **rkwargs)
+            rescue Exception => e
+              if kind == :async
+                pending = nil
+                __ao_async_exception__(servant, e, name)
+              else
+                # Cleared only once the reply is out: killed in between, the
+                # ensure below would find nothing pending and answer nobody.
+                __ao_reply__(reply, :raise, e)
+                pending = nil
+              end
+              next
+            end
+            if kind == :async
+              pending = nil
+              next
+            end
+            result = proxy if result.equal?(servant) # returning self yields the proxy, not a copy
+            __ao_reply__(reply, :ok, result)
+            pending = nil
+          end
+        ensure
+          # Going down (e.g. the method killed this thread) with a request in
+          # flight: its caller waits on the reply port only, so answer it.
+          if pending
+            __ao_reply__(pending, :raise, Error.new("owner Ractor terminated during #{klass}##{pending_name}"))
+          end
+        end
+      end
+
+      def __ao_async_exception__(servant, exc, name)
+        servant.on_async_exception(exc, name)
+      rescue Exception => e
+        warn "#{servant.class}#on_async_exception raised #{e.class}: #{e.message}"
+      end
+      private :__ao_async_exception__
+
+      # Send a result/exception back; values that cannot cross Ractors are
+      # converted into an Error so the caller never hangs.
+      def __ao_reply__(port, status, payload)
+        if status == :raise
+          port << [:raise, payload, payload.backtrace]
+        else
+          port << [:ok, payload]
+        end
+      rescue Ractor::ClosedError
+        nil # caller gave up; nothing to do
+      rescue StandardError => e
+        msg = if status == :raise
+                "#{payload.class}: #{payload.message} (exception could not be transferred: #{e.message})"
+              else
+                "return value could not be transferred: #{e.message}"
+              end
+        port << [:raise, Error.new(msg), (payload.backtrace if status == :raise)]
+      end
+      private :__ao_reply__
+
+      # Round trip on a reply port taken from a Ractor-local pool; the block
+      # sends the request. Waiting on the reply port alone (rather than also
+      # watching the owner Ractor) keeps the call cheap; a dying owner answers
+      # its in-flight request from __ao_run__, and later sends fail with
+      # ClosedError. A port is private to the caller while in use, so
+      # concurrent threads never mix replies; one whose wait was interrupted
+      # may still get a reply later, so it is not returned to the pool.
+      def __ao_sync_call__
+        pool = Ractor.store_if_absent(:__ao_reply_ports__) { [] }
+        reply = pool.pop || Ractor::Port.new # Array#pop/push are atomic under the GVL
+        yield reply
+        msg = reply.receive
+        pool.push(reply)
+        msg
+      end
+
+      # Backtraces are lost when exceptions cross Ractors; rebuild: owner frames, then caller frames.
+      def __ao_restore_exception__(exc, backtrace)
+        exc = exc.dup if exc.frozen?   # a frozen shareable exception crosses by reference
+        exc.set_backtrace(Array(backtrace) + caller(2))
+        exc
+      rescue FrozenError
+        exc                            # un-dupable: better without the backtrace than masked
+      end
+    end
+
+    # Called on the owner Ractor when an +async+ invocation raises.
+    # Override to supervise; the default only reports it.
+    def on_async_exception(exception, method_name)
+      lines = ["#{self.class}##{method_name} (async) raised #{exception.class}: #{exception.message}"]
+      lines.concat(Array(exception.backtrace).map { |l| "\tfrom #{l}" })
+      warn lines.join("\n")
+    end
+  end
+end

data/lib/ractor/actor_hash.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "active_object"
+
+class Ractor
+  # A Hash kept by a Ractor of its own. Reading it is a question you ask; every
+  # change is work you send, and the work runs where the Hash is.
+  #
+  #   h = Ractor::ActorHash.new
+  #   h.increment(:hits)                  # send it and carry on
+  #   h[:hits]                            # ask
+  #   h.async_call {|h| (h[:log] ||= []) << line }
+  #
+  # Because the entries never leave that Ractor except as copies, they do not
+  # have to be shareable the way Ractor::LockHash's do: a value can be an Array
+  # you go on appending to.
+  class ActorHash < ActiveObject
+    def initialize(initial = nil)
+      @h = initial.nil? ? {} : initial.to_hash.dup
+    end
+
+    # Sent and not waited for: the arguments travel as arguments, so unlike a
+    # block they can be anything, reassigned locals included.
+    async def set(key, value)
+      @h[key] = value
+    end
+
+    async def increment(key, by = 1)
+      @h[key] = (@h[key] || 0) + by
+    end
+
+    sync def [](key) = @h[key]
+    sync def key?(key) = @h.key?(key)
+    sync def keys = @h.keys
+    sync def to_h = @h.dup
+
+    # Not published, so they stay off the proxy's API; the proxy reaches them
+    # with sync_send, which gets at any method the way __send__ does.
+
+    # [found, value]; keeps a stored nil apart from a missing key.
+    def __lookup__(key) = @h.key?(key) ? [true, @h[key]] : [false, nil]
+
+    # Runs the block on the owner, handing it the real Hash -- not a copy and
+    # not a proxy. It cannot escape: the block runs here, and a return value is
+    # copied on its way back, so what the caller gets is never this Hash.
+    #
+    # The proc arrives as a plain argument, not as a block: blocks cannot cross
+    # Ractors, isolated procs can.
+    def __call__(prc, args) = prc.call(@h, *args)
+
+    # The caller-side half. These live on the proxy because that is what
+    # ActiveObject hands out.
+    class Proxy
+      # Which Ractor keeps it is nobody's business out here.
+      undef_method :owner, :owner?
+
+      # Sends the block to the owner and carries on. Returns nil. An exception
+      # reaches the owner's #on_async_exception.
+      #
+      #   h.async_call {|h| h[:hits] += 1 }
+      #   h.async_call(line) {|h, line| h[:log] << line }
+      #
+      # The block must be isolatable: it may read outer variables that are never
+      # reassigned, and anything else has to be passed as an argument.
+      def async_call(*args, &block) = async_send(:__call__, isolate(block), args)
+
+      # Sends the block and waits, returning what it returned, copied back.
+      def call(*args, &block) = sync_send(:__call__, isolate(block), args)
+
+      # Sends the block and returns a Future straight away.
+      def future_call(*args, &block) = future_send(:__call__, isolate(block), args)
+
+      def fetch(key, *default, &block)
+        raise ArgumentError, "wrong number of arguments (given #{default.size + 1}, expected 1..2)" if default.size > 1
+
+        found, value = sync_send(:__lookup__, key)
+        return value if found
+        return block.call(key) if block   # Hash#fetch prefers the block too
+        return default.first if default.size == 1
+
+        raise KeyError.new("key not found: #{key.inspect}", key: key, receiver: self)
+      end
+
+      def inspect = "#<#{active_object_class} #{to_h.inspect}>"
+
+      private
+
+      # A block that is already shareable is already isolated; making another one
+      # allocates a Proc on every call, which on a hot path is most of the cost.
+      def isolate(block)
+        raise LocalJumpError, "no block given (yield)" unless block
+        return block if Ractor.shareable?(block)
+
+        Ractor.shareable_proc(&block)
+      end
+    end
+  end
+end

data/lib/ractor/lockhash.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "ractor/lock.so"

data/lib/ractor/lockvar.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "ractor/lock.so"

data/lib/ractor/sharing/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Ractor
+  module Sharing
+    VERSION = "0.1.0"
+  end
+end

data/lib/ractor/sharing.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "sharing/version"
+require_relative "lockvar"
+require_relative "lockhash"
+require_relative "tvar"
+require_relative "active_object"
+require_relative "actor_hash"
+
+class Ractor
+  # Ways for Ractors to share mutable state.  Each one is shareable itself and
+  # keeps state that any Ractor may read and change; they differ in how much
+  # state moves at once:
+  #
+  #   Ractor::TVar          one or more variables, changed together -- start here
+  #   Ractor::LockVar       one variable, and a block that runs exactly once
+  #   Ractor::LockHash      a hash of those, atomic across its own keys
+  #   Ractor::ActiveObject  an object of your own, owned by one Ractor
+  #   Ractor::ActorHash     the same, with the interface already chosen: a hash
+  #
+  # Require this file for all of them, or one at a time:
+  #
+  #   require "ractor/tvar"
+  #   require "ractor/lockvar"
+  #   require "ractor/lockhash"
+  #   require "ractor/active_object"
+  #   require "ractor/actor_hash"
+  module Sharing
+  end
+end

data/lib/ractor/tvar.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'ractor/tvar.so'
+
+class Ractor
+  class TVar
+    def __increment__ inc
+      Ractor::atomically do
+        self.value += inc
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: ractor-sharing
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Koichi Sasada
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Ractor::LockVar, Ractor::TVar and Ractor::ActiveObject: shareable objects
+  that hold state any Ractor may read and change.'
+email:
+- ko1@atdot.net
+executables: []
+extensions:
+- ext/ractor/lock/extconf.rb
+- ext/ractor/tvar/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- docs/active_object.md
+- docs/actor_hash.md
+- docs/lockhash.md
+- docs/lockvar.md
+- docs/tvar.md
+- ext/ractor/lock/extconf.rb
+- ext/ractor/lock/lock.c
+- ext/ractor/lock/lock.h
+- ext/ractor/lock/lockhash.c
+- ext/ractor/lock/lockvar.c
+- ext/ractor/tvar/extconf.rb
+- ext/ractor/tvar/tvar.c
+- lib/ractor/active_object.rb
+- lib/ractor/active_object/future.rb
+- lib/ractor/actor_hash.rb
+- lib/ractor/lockhash.rb
+- lib/ractor/lockvar.rb
+- lib/ractor/sharing.rb
+- lib/ractor/sharing/version.rb
+- lib/ractor/tvar.rb
+homepage: https://github.com/ko1/ractor-sharing
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ko1/ractor-sharing
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ways for Ractors to share mutable state
+test_files: []