julewire-ractor 1.0.0

data/lib/julewire/ractor/remote_runtime.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Ractor
+    class RemoteRuntime
+      DEFAULT_REQUEST_TIMEOUT = 1
+      REQUEST_TIMEOUT = ::Ractor.make_shareable(Object.new)
+
+      def initialize(port:, emit_non_standard_exception_summaries: false)
+        @port = port
+        @child_stats = ChildStats.new
+        @emit_non_standard_exception_summaries = emit_non_standard_exception_summaries
+        @request_mutex = Mutex.new
+        @timeout_scheduler = ReplyTimeoutScheduler.new(timeout_value: REQUEST_TIMEOUT)
+        @execution_boundary = build_execution_boundary
+      end
+
+      def config = raise Core::Error, "Julewire.config is not available inside Julewire.ractor"
+
+      def configure = raise Core::Error, "Julewire.configure is not available inside Julewire.ractor"
+
+      def context = Core::ContextStore.current.context_proxy
+
+      def attributes = Core::ContextStore.current.attributes_proxy
+
+      def carry = Core::ContextStore.current.carry_proxy
+
+      def summary = Core::ContextStore.current.summary_proxy
+
+      def current_execution = current_scope && Core::Execution::View.new(current_scope)
+
+      def current_execution? = !!current_scope
+
+      def with_execution(...) = @execution_boundary.with_execution(...)
+
+      def start_execution(...) = @execution_boundary.start_execution(...)
+
+      def child_stats = @child_stats.to_h
+
+      def reset_child_stats! = @child_stats.reset!
+
+      def emit(record = Core::UNSET, **fields, &)
+        remote_emit(:emit, record, fields, &)
+      end
+
+      def emit_without_level(record = Core::UNSET, **fields, &)
+        remote_emit(:emit_without_level, record, fields, &)
+      end
+
+      def remote_emit(command, record, fields, &)
+        record = Core.emit_input(record, fields)
+        record = Core::Records::LazyEmitInput.call(record, &) if block_given?
+        record = record.to_h if Core::Records::LazyEmitInput.input?(record)
+        notify(command, payload: remote_emit_payload(record))
+      end
+      private :remote_emit
+
+      def flush(timeout: Core::UNSET)
+        timeout = effective_timeout(timeout)
+        Core::Validation.validate_timeout!(timeout, name: :timeout)
+        request(:flush, timeout: timeout)
+      end
+
+      def after_fork!(**)
+        raise Core::Error, "Julewire.after_fork! is not available inside Julewire.ractor"
+      end
+
+      def health
+        raise Core::Error, "Julewire.health is not available inside Julewire.ractor"
+      end
+
+      def close(**)
+        raise Core::Error, "Julewire.close is not available inside Julewire.ractor; use Julewire.flush instead"
+      end
+
+      def labels
+        raise Core::Error, "Julewire.labels is not available inside Julewire.ractor"
+      end
+
+      def reset!
+        Core::ContextStore.reset_current!
+      end
+
+      def emit_summary_record(scope)
+        notify(:emit_record, payload: Core::Serialization::Serializer.call(summary_record_input(scope)))
+      end
+
+      private
+
+      def emit_non_standard_exception_summaries? = @emit_non_standard_exception_summaries
+
+      def summary_finalizer_failure
+        @summary_finalizer_failure ||= ->(_error) {}
+      end
+
+      def build_execution_boundary
+        Core::Execution::Boundary.new(
+          emit_summary_record: ->(scope) { emit_summary_record(scope) },
+          summary_finalizer_failure: summary_finalizer_failure,
+          emit_non_standard_exception_summaries: -> { emit_non_standard_exception_summaries? }
+        )
+      end
+
+      def current_scope = Core::ContextStore.current.current_scope
+
+      def summary_record_input(scope)
+        scope.summary_record_input
+      end
+
+      def remote_emit_payload(record)
+        {
+          input: Core::Serialization::Serializer.call(record),
+          context: Core::Serialization::Serializer.call(Core::ContextStore.current.context_hash),
+          neutral: Core::Serialization::Serializer.call(Core::ContextStore.current.neutral_hash),
+          attributes: Core::Serialization::Serializer.call(Core::ContextStore.current.attributes_hash),
+          carry: Core::Serialization::Serializer.call(Core::ContextStore.current.carry_hash),
+          scope: Core::Serialization::Serializer.call(scope_payload)
+        }
+      end
+
+      def scope_payload
+        scope = Core::ContextStore.current.current_scope_or_snapshot
+        return {} unless scope
+
+        {
+          execution: scope.execution_hash,
+          neutral: scope.neutral_hash,
+          attributes: scope.attributes_hash,
+          carry: scope.carry_hash,
+          labels: scope.labels_hash
+        }
+      end
+
+      def notify(command, payload:)
+        @request_mutex.synchronize do
+          @port.send({ command: command, payload: payload })
+        end
+        @child_stats.message_sent
+        nil
+      rescue StandardError => e
+        @child_stats.message_dropped(e)
+        nil
+      end
+
+      def request(command, timeout:)
+        reply = ::Ractor::Port.new
+        waiting_for_reply = false
+        @request_mutex.synchronize do
+          @port.send({ command: command, payload: { timeout: timeout }, reply: reply })
+        end
+        @child_stats.request_sent
+        waiting_for_reply = true
+        wait_for_reply(reply, timeout)
+      rescue StandardError => e
+        @child_stats.request_failed(e)
+        nil
+      ensure
+        close_reply(reply) if reply && !waiting_for_reply
+      end
+
+      def effective_timeout(timeout)
+        timeout.equal?(Core::UNSET) ? DEFAULT_REQUEST_TIMEOUT : timeout
+      end
+
+      def wait_for_reply(reply, timeout)
+        timeout_token = @timeout_scheduler.schedule(reply, timeout: timeout) if timeout
+        response = reply.receive
+
+        if response.equal?(REQUEST_TIMEOUT)
+          @child_stats.request_timed_out
+          nil
+        else
+          response
+        end
+      rescue StandardError
+        nil
+      ensure
+        @timeout_scheduler.cancel(timeout_token)
+        close_reply(reply)
+      end
+
+      def close_reply(reply)
+        PortLifecycle.close(reply)
+      end
+    end
+  end
+end

data/lib/julewire/ractor/remote_summary_record.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Ractor
+    class RemoteSummaryRecord
+      def initialize(record)
+        @record = record
+      end
+
+      def owned_summary_record_input
+        @owned_summary_record_input ||= Core::Fields::FieldSet.deep_symbolize_keys(@record)
+      end
+    end
+  end
+end

data/lib/julewire/ractor/reply_timeout_scheduler.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Ractor
+    class ReplyTimeoutScheduler
+      THREAD_NAME = "julewire-ractor-reply-timeout"
+
+      # This stays stdlib-only because RemoteRuntime creates it inside a Ractor.
+      # Concurrent::ScheduledTask currently touches non-shareable concurrent-ruby
+      # constants from worker ractors.
+
+      def initialize(timeout_value:)
+        @timeout_value = timeout_value
+        @scheduler = Core::Scheduling::DeadlineScheduler.new(thread_name: THREAD_NAME, idle: :exit)
+      end
+
+      def schedule(reply, timeout:)
+        @scheduler.schedule(timeout) { send_timeout(reply) }
+      end
+
+      def cancel(token)
+        return unless token
+
+        @scheduler.cancel(token)
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def send_timeout(reply)
+        reply.send(@timeout_value)
+        nil
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/julewire/ractor/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Ractor
+    VERSION = "1.0.0"
+  end
+end

data/lib/julewire/ractor.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "julewire/core"
+
+module Julewire
+  module Ractor
+    class << self
+      def health
+        bridge_health
+      end
+
+      def child_stats
+        child_runtime&.child_stats || {}
+      end
+
+      def reset_child_stats!
+        child_runtime&.reset_child_stats!
+      end
+
+      def fanout(destinations:, **)
+        Fanout.new(destinations: destinations, **)
+      end
+
+      def enable_default_destination_workers!
+        Core::Destinations.register(:default) { |name:, **options| Destination.new(name: name, **options) }
+        nil
+      end
+
+      private
+
+      def bridge_health
+        Bridge.health
+      end
+
+      def child_runtime
+        runtime = Core::RuntimeLocator.current
+        runtime if runtime.respond_to?(:child_stats)
+      end
+    end
+  end
+
+  loader = Zeitwerk::Loader.for_gem_extension(self)
+  loader.setup
+  Core::Destinations.register(:ractor) { |name:, **options| Ractor::Destination.new(name: name, **options) }
+  Core::Integration::Lifecycle.register_after_fork(:ractor, component: :bridge) { Ractor::Bridge.after_fork! }
+
+  class << self
+    def enable_experimental_ractor!
+      Ractor::Bridge.opt_in!
+    end
+
+    def ractor(*args, name: nil, &block)
+      raise ArgumentError, "block required" unless block
+
+      Ractor::Bridge.spawn(args: args, name: name, runtime: Core::RuntimeLocator.current, &block)
+    end
+  end
+end

data/lib/julewire-ractor.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "julewire/ractor"

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: julewire-ractor
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Alexander Grebennik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: julewire-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+description: Opt-in Ractor bridge that forwards records from worker ractors to a parent
+  Julewire runtime.
+email:
+- slbug@users.noreply.github.com
+- sl.bug.sl@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- docs/bridge.md
+- docs/development.md
+- julewire-ractor.gemspec
+- lib/julewire-ractor.rb
+- lib/julewire/ractor.rb
+- lib/julewire/ractor/bridge.rb
+- lib/julewire/ractor/bridge/bridge_thread.rb
+- lib/julewire/ractor/bridge/runtime_validation.rb
+- lib/julewire/ractor/bridge/stats.rb
+- lib/julewire/ractor/child_stats.rb
+- lib/julewire/ractor/destination.rb
+- lib/julewire/ractor/destination_worker.rb
+- lib/julewire/ractor/fanout.rb
+- lib/julewire/ractor/port_lifecycle.rb
+- lib/julewire/ractor/remote_payload.rb
+- lib/julewire/ractor/remote_runtime.rb
+- lib/julewire/ractor/remote_summary_record.rb
+- lib/julewire/ractor/reply_timeout_scheduler.rb
+- lib/julewire/ractor/version.rb
+homepage: https://github.com/slbug/julewire
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/slbug/julewire
+  source_code_uri: https://github.com/slbug/julewire/tree/main/gems/ractor
+  changelog_uri: https://github.com/slbug/julewire/blob/main/gems/ractor/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+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.14
+specification_version: 4
+summary: Experimental Ractor bridge for julewire-core.
+test_files: []