farce 0 → 0.1.0

data/lib/farce/molecule.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable record with independently atomic fields.
+  # Values use the selected transfer mode, just like {Farce::Atom}.
+  # An explicitly supplied atom keeps its own settings.
+  #
+  # This class is an alternative to Ruby's Struct or Data classes.
+  #
+  # @example Updating a named field atomically
+  #   Job = Farce::Molecule.define(:status, :attempts)
+  #   job = Job.new(status: :pending, attempts: 0)
+  #   job.attempts_atom.update { |count| count + 1 }
+  #   job.status = :running
+  #   job.to_h # => { status: :running, attempts: 1 }
+  class Molecule < Farce::Abstract::Molecule
+    include Shareable
+
+    # Create a record class with defaults for newly created atoms.
+    # @!macro modes
+    # @param fields [Array<Symbol, String>] the field names
+    # @param mode [Symbol, nil] the default transfer mode, or nil for :copy
+    # @param compare_by_identity [Boolean, nil] the default comparison policy
+    # @return [Class<Molecule>]
+    def self.define(*fields, mode: nil, **, &)
+      subclass = super(*fields, **)
+      subclass.class_eval "def self.default_mode = #{mode.to_sym.inspect}", __FILE__, __LINE__ unless nil.equal?(mode)
+      subclass.class_eval(&) if block_given?
+      subclass
+    end
+
+    # @return [Symbol] the default transfer mode for new records
+    def self.default_mode = :copy
+
+    # @!visibility private
+    def self.define_member(field)
+      return super unless field == :mode
+      raise ArgumentError, "#{field.inspect} is not a valid field name"
+    end
+    private_class_method :define_member
+
+    # Initialize fields and optionally override the record class defaults.
+    # @!macro modes
+    # @param mode [Symbol, nil] the transfer mode, or nil for the class default
+    # @param compare_by_identity [Boolean, nil] the comparison policy, or nil for the class default
+    # @see Abstract::Molecule#initialize
+    def initialize(*, mode: nil, **)
+      @mode = mode&.to_sym || self.class.default_mode
+      super(*, **)
+    end
+
+    # The default mode used to transfer values between Ractors.
+    # @return [Symbol]
+    attr_reader :mode
+
+    private def create_atom(_, value) = Atom.new(value, mode:, compare_by_identity: compare_by_identity?)
+  end
+end

data/lib/farce/mutable.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A wrapper making generic Ruby objects shareable while preserving mutability.
+  #
+  # It achieves this by keeping an immutable copy of the object,
+  # and performing an atomic update of this reference for mutating method calls.
+  #
+  # This means the entire object is copied whenever it is being mutated.
+  #
+  # You should therefore favor dedicated data structures whenever possible,
+  # like using a {Map} instead of wrapping a Hash in a {Mutable}, or a {Vector}
+  # instead of doing the same with an Array.
+  #
+  # Non-mutating calls do not incur this cost.
+  #
+  # Use a transaction view to stage mutations alongside changes to other participants.
+  # The original value changes only when the transaction commits.
+  #
+  # @example Updating two strings together
+  #   first  = Farce::Mutable.new("queued")
+  #   second = Farce::Mutable.new("waiting")
+  #   Farce.transaction(first, second) do |_, first_view, second_view|
+  #     first_view.replace("running")
+  #     second_view << " for worker"
+  #   end
+  #
+  # @example
+  #   shareable_string = Farce::Mutable.new("foo")
+  #   Ractor.new(shareable_string) { it << "bar" }.join
+  #   shareable_string.to_s # => "foobar"
+  class Mutable < BasicObject
+    module Inherited
+      include ::Farce.const_get(:Internal)::Delegation
+      include ::Farce.const_get(:Internal)::Inspect
+
+      define_method(:dup,              ::Kernel.instance_method(:dup))
+      define_method(:clone,            ::Kernel.instance_method(:clone))
+      define_method(:is_a?,            ::Kernel.instance_method(:is_a?))
+      define_method(:initialize_copy,  ::Kernel.instance_method(:initialize_copy))
+      define_method(:initialize_dup,   ::Kernel.instance_method(:initialize_dup))
+      define_method(:initialize_clone, ::Kernel.instance_method(:initialize_clone))
+
+      private :initialize_copy, :initialize_dup, :initialize_clone
+    end
+
+    module Mutator
+      extend self
+
+      def prepare(value, in_place: false)
+        return -value if value.is_a? String
+        return value if value.frozen? || (Internal.native_ractors? && Ractor.shareable?(value))
+        in_place ? value.freeze : value.dup.freeze
+      end
+
+      def deref(mutable) = ::Kernel.instance_method(:instance_variable_get).bind_call(mutable, :@atom).value
+    end
+
+    private_constant :Mutator, :Inherited
+    include ::Farce::Shareable::Delegated
+    include Inherited
+
+    # Turns the given {Mutable} into a frozen copy of the underlying object.
+    # @param mutable [Mutable] the mutable
+    # @return [BasicObject] current snapshot of the object it is wrapping
+    def self.deref(mutable) = Mutable === mutable ? Mutator.deref(mutable) : mutable
+
+    # Creates a subclass of {Mutable} that automatically generates values based on the given factory (usually a class),
+    # by invoking `new` on it with any arguments being passed on.
+    #
+    # @example
+    #   # You should probably use Farce::Vector instead.
+    #   MutableArray = Farce::Mutable[Array]
+    #   MutableArray.new(2) # => #<MutableArray [nil, nil]>
+    #
+    # @param factory [#new] The factory to create a subclass for. Typically a class. Must be shareable.
+    # @return [Class] The subclass of {Mutable}.
+    def self.[](factory)
+      raise ::Farce::Ractor::IsolationError, "factory is not shareable" unless ::Farce::Ractor.shareable?(factory)
+
+      klass = ::Class.new(self)
+      klass.set_temporary_name("#{name}[#{factory.name}]")
+      klass.instance_variable_set(:@value_factory, factory)
+
+      klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def self.new(...) = super(value_factory.new(...))
+        def self.value_factory
+          return @value_factory if defined?(@value_factory) && @value_factory
+          superclass.value_factory
+        end
+      RUBY
+
+      klass.singleton_class.class_eval "undef []", __FILE__, __LINE__
+      klass
+    end
+
+    # Creates a new mutable version of the given object.
+    # The object will be copied on initialization if it isn't frozen.
+    # A frozen version of the object must be Ractor-shareable.
+    # @param object [BasicObject] The object to wrap. Must implement `dup`, `freeze`, and `frozen?`.
+    def initialize(object)
+      @atom = Internal::Atom.new Mutator.prepare(object)
+      super()
+    end
+
+    # @api private
+    def transaction_wrapper(transaction) = Transaction::Mutable.new(transaction, self, @atom)
+
+    # @api private
+    def marshal_dump = ::Kernel.raise(::TypeError, "Farce::Mutable cannot be marshaled")
+
+    # Marshal hook discovery must inspect the wrapper without delegating to its snapshot.
+    def respond_to?(name, include_private = false) # rubocop:disable Style/OptionalBooleanParameter
+      return true if name == :marshal_dump || name == :transaction_wrapper
+      return false if Internal.marshal_protocol_method?(name)
+      method_missing(:respond_to?, name, include_private)
+    end
+
+    # @api private
+    def is_a?(...) = super || @atom.value.is_a?(...)
+
+    # @api private
+    def inspect_with(inspector)
+      value = @atom.value
+      klass = ::Kernel.instance_method(:class).bind_call(self)
+      name  = klass.name
+      name += "[#{value.class.name}]" if klass == ::Farce::Mutable
+      inspector.group("#<#{name}", ">") do
+        inspector.breakable
+        inspector.object(value)
+      end
+    end
+
+    private
+
+    # Delegates all methods to the frozen copy of the current value.
+    # If it throws a `FrozenError` it reruns the method against an unfrozen duplicate of the value,
+    # freezes it, and uses that as internal value.
+    def method_missing(...) # rubocop:disable Style/MissingRespondToMissing
+      @atom.value.__send__(...)
+    rescue ::FrozenError
+      result = nil
+      @atom.update do |current|
+        copy   = current.dup
+        result = copy.__send__(...)
+        result = self if result.equal?(copy)
+        Mutator.prepare(copy, in_place: true)
+      end
+      result
+    end
+
+    def freeze_backend = @atom
+
+    def initialize_copy(other)
+      super
+      @atom = Internal::Atom.new(Mutator.deref(other))
+    end
+
+    def initialize_dup(other)
+      super
+      publish_shareable_copy(other, operation: :dup)
+    end
+
+    def initialize_clone(other, freeze: nil)
+      super
+      publish_shareable_copy(other, operation: :clone, freeze:)
+    end
+  end
+end

data/lib/farce/pool.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A dynamically sized pool of Ractor schedulers.
+  #
+  # Tasks wait in one shared queue. An empty pool starts its first worker immediately
+  # when work arrives. A task that remains queued for `grow_after`
+  # causes the pool to add a worker until `max_size` is reached. Workers above
+  # `min_size` retire after `shrink_after` without queued or running work.
+  # By default, the pool starts with no workers and can shrink back to zero.
+  #
+  # Most importantly, it exposes a {#schedule} method compatible with {Scheduler#schedule}.
+  #
+  # @example
+  #   # Create a new pool
+  #   pool = Farce::Pool.new
+  #
+  #   # Schedule some work on the pool.
+  #   pool.schedule do
+  #     # The work runs in a non-blocking fiber, multiple tasks can run concurrently even on the same worker.
+  #     loop do
+  #       sleep 5
+  #       MyClass.recurring_work
+  #     end
+  #   end
+  #
+  # @example Custom Fiber scheduler
+  #   require "farce"
+  #   require "carbon_fiber"
+  #
+  #   # At least two Ractors, up to four. Launch a new one if a task waits longer than 100 milliseconds.
+  #   # Use the fiber scheduler from the carbon_fiber gem.
+  #   pool = Farce::Pool.new(min_size: 2, max_size: 4, grow_after: 0.1) { CarbonFiber::Scheduler.new }
+  #
+  #   # Schedule some work
+  #   pool.schedule { MyClass.do_something }
+  class Pool < Farce::Abstract::Scheduler
+    include Internal::MarshalSupport::Reject
+    include Shareable::Unfreezable
+    include Internal::Inspect
+
+    # @return [Float] Maximum queue wait before adding a worker.
+    attr_reader :grow_after
+
+    # @return [Integer, nil] Soft task limit for each worker.
+    attr_reader :max_inflight
+
+    # @return [Integer] Maximum worker count.
+    attr_reader :max_size
+
+    # @return [Integer] Minimum worker count.
+    attr_reader :min_size
+
+    # @return [Float, nil] Idle time before an extra worker retires.
+    attr_reader :shrink_after
+
+    # Create and start an elastic pool using the configured fiber scheduler.
+    # An explicit constructor block overrides the configured default.
+    #
+    # `max_inflight` is a soft limit. A worker may exceed it when its scheduler
+    # has no runnable fibers or when the pool has reached `max_size`.
+    #
+    # @param min_size [Integer] Workers started immediately and retained while open.
+    # @param max_size [Integer] Maximum workers allowed.
+    # @param max_inflight [Integer, nil] Soft task limit for each worker.
+    # @param grow_after [Numeric] Queue wait before adding another worker.
+    # @param shrink_after [Numeric, nil] Idle time before an extra worker retires.
+    # @param capacity [Integer, nil] Pending-task capacity.
+    # @param backend [Symbol] IO backend for the built-in scheduler.
+    # @yieldreturn [Object] Fiber scheduler constructed in each worker.
+    def initialize(min_size: 0, max_size: 4, max_inflight: 64,
+                   grow_after: 0.005, shrink_after: 30, capacity: 1024,
+                   backend: Internal::FROZEN_CONFIG.io_backend, &constructor)
+      constructor ||= Internal::FROZEN_CONFIG.fiber_scheduler_constructor
+      @min_size     = Integer(min_size)
+      @max_size     = Integer(max_size)
+      @max_inflight = max_inflight && Integer(max_inflight)
+      @grow_after   = duration(grow_after, :grow_after)
+      @shrink_after = duration(shrink_after, :shrink_after, nil_allowed: true)
+      validate_sizes
+
+      @backend      = backend
+      @constructor  = constructor
+      @constructor  = Ractor.shareable_proc(&constructor) if constructor && !Ractor.shareable?(constructor)
+      @queue        = Internal::Queue.new(capacity: capacity && Integer(capacity), track_age: true)
+      @state        = Internal::Atom.new(:running)
+      @error        = Internal::Atom.new
+      @worker_count = Internal::Atom.new(0)
+      @pressure     = Internal::Atom.new
+      @admission    = Internal::Signal.new
+      super()
+      begin
+        @min_size.times { start_worker }
+      rescue Exception # rubocop:disable Lint/RescueException
+        close
+        raise
+      end
+    end
+
+    # Enqueue a task for any worker in the pool.
+    #
+    # Pools have no single owner, so `auto_local` does not select local transfer.
+    # Explicit local transfer is rejected because another Ractor may run the task.
+    #
+    # @!macro modes
+    # @param args [Array<Object>] Positional arguments passed to the task block.
+    # @param mode [Symbol] Argument transfer mode.
+    # @param auto_local [Boolean] Accepted for compatibility with {Scheduler#schedule}.
+    # @yield [*args] Task to execute.
+    # @return [Pool] self.
+    # @raise [PoolClosedError] If the pool is closing or closed.
+    def schedule(*args, mode: :copy, auto_local: true, &block) # rubocop:disable Lint/UnusedMethodArgument
+      raise PoolClosedError, "cannot schedule task on a closed pool" if closed?
+      raise ArgumentError, "local transfer is not supported by a pool" if mode == :local
+
+      task = Internal::ScheduledTask.new(args, block, mode)
+      @queue.push(task)
+      arm_scaler
+      self
+    rescue ClosedQueueError
+      raise unless closed?
+      raise PoolClosedError, "cannot schedule task on a closed pool"
+    end
+
+    # Stop accepting tasks and drain queued work.
+    #
+    # @return [Pool] self.
+    def close
+      return self if closed?
+      @state.compare_and_set(:running, :closing)
+      @queue.seal
+      admission_changed
+      if size.zero?
+        @queue.closed? ? finish_close : start_worker(drain: true)
+      end
+      self
+    end
+
+    # Return the first worker error, if any.
+    def error
+      value = @error.value
+      value.is_a?(Envelope) ? value.value : value
+    end
+
+    # Return the current number of running and starting workers.
+    def size = @worker_count.value
+
+    # Return the current pool state.
+    def state = @state.value
+
+    # Return whether the pool rejects new tasks.
+    def closed? = state != :running
+
+    # Return whether the pool is draining queued work.
+    def closing? = state == :closing
+
+    # Return whether closing workers have drained all admitted submissions.
+    # @api private
+    def drained? = closing? && @queue.closed?
+
+    # Return whether all configured workers have been started.
+    def at_max_size? = size >= @max_size
+
+    # Return the generation used by workers waiting for admission.
+    # @api private
+    def admission_generation = @admission.generation
+
+    # Wait for worker capacity or a pool state change.
+    # @api private
+    def wait_for_admission(generation) = @admission.wait(generation)
+
+    # Wake workers waiting at their soft admission limit.
+    # @api private
+    def admission_changed = @admission.broadcast
+
+    # Record that a task left the shared queue.
+    # @api private
+    def task_taken
+      return if @pressure.value.nil? || at_max_size?
+      return unless queue_empty?
+      @pressure.value = nil
+      arm_scaler if @queue.size.positive?
+    end
+
+    # Reserve a worker retirement above the minimum size.
+    # @api private
+    def retire_worker
+      retired = false
+      @worker_count.update do |count|
+        if state == :running && count > @min_size && queue_empty?
+          retired = true
+          count - 1
+        else
+          count
+        end
+      end
+      retired
+    end
+
+    # Remove a stopped worker and preserve its failure.
+    # @api private
+    def worker_stopped(error, replace: true)
+      @worker_count.update { |count| count - 1 }
+      @error.compare_and_set(nil, Envelope.new(error)) if error
+      if closing?
+        if size.zero?
+          error && !drained? ? start_worker(drain: true) : finish_close
+        end
+      elsif state == :running && replace
+        begin
+          start_worker while size < @min_size
+        rescue Exception # rubocop:disable Lint/RescueException
+          nil
+        end
+        arm_scaler if @queue.size.positive?
+      end
+      admission_changed
+    end
+
+    # Recheck delayed queue pressure and grow by one worker.
+    # @api private
+    def scale_if_needed(started)
+      return unless state == :running && @pressure.value == started
+      age = @queue.oldest_age
+      return clear_pressure(started) unless age
+      return reschedule_scaler(started, @grow_after - age) if age < @grow_after
+
+      start_worker unless at_max_size?
+      return clear_pressure(started) if queue_empty? || at_max_size?
+
+      next_started = @queue.generation
+      schedule_scaler(next_started) if @pressure.compare_and_set(started, next_started)
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      @error.compare_and_set(nil, Envelope.new(e))
+    end
+
+    # @api private
+    def inspect_with(inspector)
+      super do
+        inspector.attribute(:state,        state)
+        inspector.attribute(:backend,      @backend)
+        inspector.attribute(:size,         size)
+        inspector.attribute(:min_size,     @min_size)
+        inspector.attribute(:max_size,     @max_size)
+        inspector.attribute(:max_inflight, @max_inflight) if @max_inflight
+        yield if block_given?
+      end
+    end
+
+    private
+
+    def validate_sizes
+      raise ArgumentError, "min_size must be non-negative" if @min_size.negative?
+      raise ArgumentError, "max_size must be positive" unless @max_size.positive?
+      raise ArgumentError, "min_size must not exceed max_size" if @min_size > @max_size
+      raise ArgumentError, "max_inflight must be positive" if @max_inflight && !@max_inflight.positive?
+    end
+
+    def duration(value, name, nil_allowed: false)
+      return if value.nil? && nil_allowed
+      value = Float(value)
+      raise ArgumentError, "#{name} must be finite and non-negative" if !value.finite? || value.negative?
+      value
+    end
+
+    def start_worker(drain: false, only_if_empty: false)
+      reserved = false
+      @worker_count.update do |count|
+        can_start = state == :running || (drain && closing? && !queue_empty?)
+        if can_start && count < @max_size && (!only_if_empty || count.zero?)
+          reserved = true
+          count + 1
+        else
+          count
+        end
+      end
+      return false unless reserved
+
+      worker = Internal::PoolWorker.new(self)
+      scheduler = Scheduler.new(
+        backend:     @backend,
+        queue:       @queue,
+        pool_worker: worker,
+        queue_owner: false,
+        &@constructor
+      )
+      scheduler.launch_ractor
+      admission_changed if at_max_size?
+      true
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      worker ? worker.stopped(e, replace: false) : @worker_count.update { |count| count - 1 }
+      raise
+    end
+
+    def arm_scaler
+      return if at_max_size? || queue_empty? || state != :running
+      start_worker(only_if_empty: true) if size.zero?
+      return if at_max_size?
+
+      started = @queue.generation
+      age     = @queue.oldest_age
+
+      return unless age
+      return unless @pressure.compare_and_set(nil, started)
+
+      remaining = @grow_after - age
+      remaining = 0 if remaining.negative?
+
+      schedule_scaler(started, remaining)
+    end
+
+    def schedule_scaler(started, delay = @grow_after)
+      Internal::PoolSupervisor.schedule(self, started, delay)
+    end
+
+    def reschedule_scaler(started, delay)
+      next_started = @queue.generation
+      schedule_scaler(next_started, delay) if @pressure.compare_and_set(started, next_started)
+    end
+
+    def clear_pressure(started)
+      return unless @pressure.compare_and_set(started, nil)
+      arm_scaler if @queue.size.positive?
+    end
+
+    def queue_empty? = @queue.size.zero? # rubocop:disable Style/ZeroLengthPredicate
+
+    def finish_close = @state.compare_and_set(:closing, :closed)
+  end
+end

data/lib/farce/port.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!parse
+  #   class Port < Farce::Ractor::Port
+  #   end
+  #
+  # `Ractor::Port` subclass with additional features, namely {#owned? ownership tracking} and
+  # {#send mode based sending}.
+  class Port < Internal::Port
+    include Abstract::Port
+
+    MANAGER    = ModeManager.new
+    SUBCLASSES = Farce::MODES.to_h do |mode|
+      if mode == :copy
+        normal = self
+      else
+        normal = Class.new(self)
+        normal.set_temporary_name("#{name}[#{mode.inspect}]")
+        normal.class_eval "def self.mode = #{mode.inspect}", __FILE__, __LINE__
+      end
+
+      auto_local = Class.new(normal)
+      auto_local.set_temporary_name("#{name}[#{mode.inspect}, auto_local: true]")
+      auto_local.class_eval "def self.auto_local? = true", __FILE__, __LINE__
+      [mode, [normal, auto_local].freeze]
+    end.freeze
+
+    private_constant :MANAGER, :SUBCLASSES
+
+    # @api private
+    def self.[](mode, auto_local: false)
+      if self == Port
+        return SUBCLASSES.dig(mode, auto_local ? 1 : 0) || raise(ArgumentError, "invalid mode: #{mode.inspect}")
+      end
+      raise ArgumentError, "mode mismatch: #{mode.inspect} vs #{self.mode.inspect}" if mode != self.mode
+      return self if auto_local? == auto_local
+      raise ArgumentError, "auto_local mismatch: #{auto_local.inspect} vs #{auto_local?.inspect}"
+    end
+
+    # @api private
+    def self.mode = :copy
+
+    # @api private
+    def self.auto_local? = false
+
+    # @!visibility private
+    # (see #initialize)
+    def self.new(mode: nil, auto_local: nil)
+      return super() if mode.nil? && auto_local.nil?
+      auto_local = auto_local? if auto_local.nil?
+      self[mode || self.mode, auto_local: auto_local].new
+    end
+
+    # @!method initialize(mode: :copy, auto_local: false)
+    #   Creates a new port with the given default mode.
+    #
+    #   @!macro modes
+    #
+    #   @param mode [Symbol]
+    #     The default mode to use when sending values through this port.
+    #
+    #   @param auto_local [Boolean]
+    #     Whether to automatically use `:local` mode when sending values from the owning ractor.
+
+    # @attribute [r] mode
+    # The port's default mode. Set via {#initialize}.
+    # @return [Symbol] The default mode of this port.
+    # @see #send
+    def mode = self.class.mode
+
+    # Whether or not auto_local is enabled by default. Set via {#initialize}.
+    # @return [Boolean] `true` if auto_local is enabled, `false` otherwise.
+    # @see #send
+    def auto_local? = self.class.auto_local?
+
+    # Sends a message through the port.
+    #
+    # @param message [BasicObject] The message to send.
+    #
+    # @param move [Boolean, nil]
+    #   Used to determine `mode` if it is not explicitly specified.
+    #   If true, the message will be sent in `:move` mode.
+    #   If false, the message will be sent in the port's default mode, unless that mode is `:move`, in which case it
+    #   will be sent in `:copy` mode.
+    #
+    # @param mode [Symbol, nil]
+    #   The mode to use when sending the message. If nil, the mode will be determined by the `move` parameter and the
+    #   port's default mode.
+    #
+    # @param auto_local [Boolean, nil]
+    #   If `true`, or `nil` and {#auto_local?} is `true`, and send is called from the owning ractor, then the message
+    #   will be sent in `:local` mode regardless of the specified mode or move flag.
+    #
+    # @raise [Farce::Ractor::ClosedError] if the port is closed.
+    # @return [self]
+    def send(message, move: nil, mode: nil, auto_local: nil)
+      return super(message) if Ractor.shareable?(message)
+      raise Ractor::ClosedError, "port is closed" if closed?
+      auto_local = auto_local? if auto_local.nil?
+
+      if auto_local && owned?
+        mode = :local
+      elsif mode.nil?
+        mode = self.mode
+        case move
+        when true  then mode = :move
+        when false then mode = :copy if mode == :move
+        when nil # no-op
+        else raise ArgumentError, "invalid move: #{move.inspect}"
+        end
+      end
+
+      case mode
+      when :copy then super(message)
+      when :move then super(message, move: true)
+      else super(MANAGER.wrap(message, mode:))
+      end
+    end
+
+    # (see Abstract::Port#receive)
+    # Automatically opens envelopes created by this port's mode manager.
+    def receive(timeout: nil)
+      # Omit the absent keyword instead of allocating arguments for super.
+      result = timeout.nil? ? super() : super
+      MANAGER.unwrap(result)
+    end
+
+    # @return [String] A string representation of the port, including its class name and mode.
+    def inspect = super.sub(/\A#<.+? (?=(?:to|id):#?\d+)/, "#<Farce::Port mode:#{mode} ")
+  end
+end