farce 0 → 0.1.0

data/lib/farce/internal/fake_ractor.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    module FakeRactor
+      State = Struct.new(:id, :name, :main_thread, :default_port, :status, :mutex, :monitors, :source_location)
+
+      GROUPS         = {}.compare_by_identity
+      RACTOR_MAPPING = ObjectSpace::WeakKeyMap.new
+      STATES         = ObjectSpace::WeakKeyMap.new
+
+      class Main
+        include Farce::Ractor
+        include Freeze::Unfreezable
+        extend RactorMethods
+
+        private_class_method :new
+        INSTANCE     = Freeze.publish(new)
+        DEFAULT_PORT = BasePort.new
+
+        def default_port = DEFAULT_PORT
+        def inspect      = "#<Farce::Ractor#1 running>"
+        def join         = sleep
+        def main?        = true
+        def monitor(_)   = true # rubocop:disable Naming/PredicateMethod
+        def name         = nil
+        def receive(...) = DEFAULT_PORT.receive(...)
+        def send(...)    = DEFAULT_PORT.send(...)
+        def unmonitor(_) = self
+        def value        = sleep
+
+        alias << send
+        alias recv receive
+      end
+
+      class NotMain
+        include Farce::Ractor
+        include Freeze::Unfreezable
+        extend RactorMethods
+
+        @@ractor_counter = 1
+        @@ractor_counter_mutex = Mutex.new
+
+        def initialize(*, name: nil, &block)
+          raise ArgumentError, "must be called with a block" unless block_given?
+          group = ThreadGroup.new
+          state = State.new(
+            default_port:    BasePort.new,
+            id:              @@ractor_counter_mutex.synchronize { @@ractor_counter += 1 },
+            monitors:        ::Set.new,
+            mutex:           Mutex.new,
+            name:            name,
+            source_location: -(block.source_location&.join(":") || "(unknown)"),
+            status:          :running,
+          )
+
+          STATES[self] = state
+          GROUPS[group] = self
+
+          state.main_thread = Thread.new do # rubocop:disable Lint/UselessSetterCall
+            current = Thread.current
+            group.add(current)
+            current.freeze
+
+            RACTOR_MAPPING[current] = self
+            result = instance_exec(*, &block)
+
+            # this will trigger a fiber scheduler main loop if one is set
+            Fiber.set_scheduler(nil) if Fiber.respond_to?(:set_scheduler)
+            state.status = :exited
+            result
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            state.status = :aborted
+            raise e
+          ensure
+            state.mutex.synchronize do
+              state.monitors.each do |monitor|
+                monitor << state.status
+              end
+              state.monitors = nil
+            end
+            group.list.each { it.kill unless it == current }
+            GROUPS.delete(group)
+          end
+        end
+
+        def [](key)
+          raise "Cannot get ractor local storage for non-current ractor" unless self == FakeRactor.current
+          Farce::Ractor[key]
+        end
+
+        def []=(key, value)
+          raise "Cannot set ractor local storage for non-current ractor" unless self == FakeRactor.current
+          Farce::Ractor[key] = value
+        end
+
+        def monitor(port) # rubocop:disable Naming/PredicateMethod
+          state = STATES[self]
+
+          if state.status == :running
+            state.mutex.synchronize do
+              next if state.status != :running
+              state.monitors << port
+              return true
+            end
+          end
+
+          port << state.status
+          false
+        end
+
+        def unmonitor(port)
+          state = STATES[self]
+          state.mutex.synchronize { state.monitors&.delete(port) }
+          self
+        end
+
+        def inspect
+          return super unless state = STATES[self]
+          status = state.status == :running ? "running" : "terminated"
+          "#<Farce::Ractor##{state.id}#{" #{state.name}" if state.name} #{state.source_location} #{status}>"
+        end
+
+        def join
+          STATES[self].main_thread.join
+          self
+        end
+
+        def send(...)
+          default_port.send(...)
+          self
+        end
+
+        def default_port = STATES[self].default_port
+        def main?        = false
+        def name         = STATES[self].name
+        def receive(...) = default_port.receive(...)
+        def value        = STATES[self].main_thread.value
+
+        alias << send
+        alias recv receive
+        alias to_s inspect
+
+        undef dup
+        undef clone
+      end
+
+      def self.current
+        # JRuby fibers expose a backing thread with a different thread group.
+        thread   = Internal.storage_thread(Thread.current)
+        override = Storage.thread(thread)[:current_ractor]
+        override || GROUPS.fetch(thread.group) { Main::INSTANCE }
+      end
+
+      def self.main_thread = STATES[current]&.main_thread || Thread.main
+
+      # Fibers on this Ruby thread share the override. New threads do not inherit it.
+      def self.with_current(ractor)
+        storage  = Storage.thread
+        previous = storage[:current_ractor]
+        storage[:current_ractor] = ractor
+        yield
+      ensure
+        storage[:current_ractor] = previous
+      end
+
+      def self.threads
+        group = Internal.storage_thread(Thread.current).group
+        return group.list if GROUPS.key?(group)
+        list = ThreadGroup::Default.list
+        list += group.list if group != ThreadGroup::Default
+        list
+      end
+    end
+  end
+end

data/lib/farce/internal/freeze.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal
+    # Shared implementation for the explicit frozen-state policies in {Shareable}.
+    module Freeze
+      # Structurally freeze a Ruby facade, then validate and publish its object graph.
+      # This deliberately bypasses an override that controls logical frozen state.
+      def self.publish(object)
+        Object.instance_method(:freeze).bind_call(object)
+        ::Ractor.make_shareable(object) if Internal.native_ractors?
+        object
+      end
+
+      def self.check(object)
+        return object unless object.frozen?
+
+        raise FrozenError.new("can't modify frozen #{object.class}", receiver: object)
+      end
+
+      # Delegate logical frozen state to storage owned by the wrapper.
+      module Delegated
+        def freeze
+          backend = freeze_backend
+          raise "#{self.class} is not initialized" unless backend
+
+          backend.freeze
+          self
+        end
+
+        def frozen?
+          backend = freeze_backend
+          backend ? backend.frozen? : Object.instance_method(:frozen?).bind_call(self)
+        end
+
+        private
+
+        def check_frozen! = Internal::Freeze.check(self)
+
+        def publish_shareable_copy(other, operation:, freeze: nil)
+          logically_frozen = operation == :clone && (freeze.nil? ? other.frozen? : freeze)
+          self.freeze if logically_frozen
+          publish_shareable
+        end
+      end
+
+      # Track one logical frozen state shared by all storage resolved through a facade.
+      module Tracked
+        def initialize(...)
+          @farce_freeze_state = Internal::Flag.new(false)
+          super
+        end
+
+        def freeze
+          @farce_freeze_state.set
+          self
+        end
+
+        def frozen?
+          state = @farce_freeze_state
+          state ? state.value : Object.instance_method(:frozen?).bind_call(self)
+        end
+
+        private
+
+        def check_frozen! = Internal::Freeze.check(self)
+
+        def initialize_copy(other, **)
+          super
+          state = other.instance_variable_get(:@farce_freeze_state)
+          guard = state.respond_to?(:native_flag) ? state.class : Internal::Flag
+          @farce_freeze_state = guard.new(false)
+        end
+
+        def publish_shareable_copy(other, operation:, freeze: nil)
+          logically_frozen = operation == :clone && (freeze.nil? ? other.frozen? : freeze)
+          self.freeze if logically_frozen
+          publish_shareable
+        end
+      end
+
+      # Keep a live service structurally published while rejecting logical freezing.
+      module Unfreezable
+        def freeze = raise(TypeError, "#{self.class} cannot be frozen")
+        def frozen? = false
+
+        private
+
+        def publish_shareable_copy(_other, operation:, freeze: nil)
+          self.freeze if operation == :clone && freeze == true
+          publish_shareable
+        end
+      end
+
+      # Let a purpose-built native object publish itself after payload initialization.
+      module Native
+        private
+
+        def publish_shareable = self
+
+        def publish_shareable_copy(other, operation:, freeze: nil)
+          logically_frozen = operation == :clone && (freeze.nil? ? other.frozen? : freeze)
+          self.freeze if logically_frozen
+          publish_shareable
+        end
+      end
+
+      # Keep ordinary Ruby frozen state as the public state.
+      module Immutable
+        private
+
+        def publish_shareable_copy(*) = publish_shareable
+      end
+    end
+  end
+end

data/lib/farce/internal/inspect.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal
+    module Inspect
+      module Mixin
+        def inspect
+          inspector = StringInspector.create
+          inspector.inspect(self)
+        end
+
+        def pretty_print(pp)
+          inspector = PrettyPrinter.create(pp)
+          inspector.object(self)
+        end
+
+        def pretty_print_cycle(pp)
+          inspector = PrettyPrinter.create(pp)
+          inspector.object_with_address(self)
+        end
+
+        def inspect_with(inspector, &)
+          return inspector.object_group(self, &) if block_given?
+          inspector.object_with_address(self)
+        end
+      end
+
+      class Inspector
+        def self.current                = Storage.fiber[-name]
+        def self.create                 = current || new
+        def initialize                  = @seen = ::Set.new.compare_by_identity
+        def attributes(attributes, ...) = attributes.each { attribute(_1, _2, ...) }
+        def object_group(object, &)     = group("#<#{object.class.name}", ">", &)
+        def object_with_address(object) = text(Kernel.instance_method(:to_s).bind_call(object))
+
+        def activate
+          name = -self.class.name
+          old  = Storage.fiber[name]
+
+          begin
+            Storage.fiber[name] = self
+            yield
+          ensure
+            Storage.fiber[name] = old
+          end
+        end
+
+        def attribute(key, value, mode_manager = nil)
+          breakable
+          text "#{key}="
+          object(value, mode_manager)
+        end
+
+        def from_envelope(envelope, prefix = nil)
+          if envelope.owned?
+            text(prefix) if prefix
+            object(envelope.value)
+          else
+            text(envelope.claimed? ? "claimed" : "unclaimed")
+          end
+          self
+        end
+
+        def object(object, mode_manager = nil)
+          return object_with_address(object) if @seen.include?(object)
+          return from_envelope(object) if mode_manager&.managed_envelope?(object)
+          return foreign_inspect(object) unless object.is_a?(Mixin)
+
+          activate do
+            @seen << object
+            object.inspect_with(self)
+          end
+
+          self
+        end
+
+        def hash_pair(key, ...)
+          if Symbol === key
+            key = key.to_s.inspect if key.inspect.match?(%r{\A:["$@!]|[%&*+\-/<=>@\]^`|~]\z})
+            text("#{key}: ")
+          else
+            text("#{key.inspect} => ")
+          end
+          block_given? ? yield : object(...)
+        end
+      end
+
+      class StringInspector < Inspector
+        def initialize
+          @output = +""
+          super
+        end
+
+        def breakable(str = " ") = text(str)
+        def text(str)            = @output << str
+        def to_s                 = -@output
+
+        def inspect(object)
+          previous_output = @output
+          @output = +""
+          object(object)
+          to_s
+        ensure
+          @output = previous_output
+        end
+
+        def foreign_inspect(object)
+          text(object.inspect)
+        rescue StandardError
+          object_with_address(object)
+        end
+
+        def group(before = nil, after = nil)
+          text(before) if before
+          yield
+          text(after) if after
+        end
+
+        def seplist(list, sep = nil, iter_method = :each)
+          sep ||= -> { text(", ") }
+          first = true
+          list.__send__(iter_method) do |*args|
+            sep.call unless first
+            first = false
+            yield(*args)
+          end
+        end
+      end
+
+      class PrettyPrinter < Inspector
+        def self.create(pp) = current&.pp == pp ? current : new(pp)
+
+        attr_reader :pp
+
+        Internal.delegate(self, :@pp, :text, :object_group, :breakable, :seplist)
+
+        def initialize(pp)
+          @pp = pp
+          super()
+        end
+
+        def foreign_inspect(object)
+          pp.pp(object)
+        rescue StandardError
+          object_with_address(object)
+        end
+
+        def group(...) = @pp.group(1, ...)
+      end
+
+      def self.append_features(base) = base.include(Mixin)
+      private_constant :Mixin, :Inspector, :PrettyPrinter
+    end
+  end
+end

data/lib/farce/internal/key_lock_map.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Coordinate equal keys without retaining entries after an operation finishes.
+    class KeyLockMap
+      include Freeze::Unfreezable
+
+      def initialize(registry_class:, **comparison_options)
+        @registry = registry_class.new(**comparison_options)
+        Freeze.publish(self) if @registry.ractor_shareable?
+      end
+
+      def synchronize(key)
+        raise LocalJumpError, "no block given" unless block_given?
+
+        completed = Object.new
+        catch(completed) do
+          # Nonlocal exit releases the reservation without publishing a value.
+          # The block result stays with the caller, even for shareable registries.
+          @registry.store_if_absent(key) { throw completed, yield }
+        end
+      end
+    end
+  end
+end