Class: Farce::Port

Inherits:
Ractor::Port show all
Includes:
Abstract::Port
Defined in:
lib/farce/port.rb,
lib/farce/port.rb

Overview

Ractor::Port subclass with additional features, namely ownership tracking and mode based sending.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Abstract::Port

#<<, #close, #closed?, #owned?, #pop, #push

Methods included from Shareable

#ractor_shareable?

Methods included from Internal::Noncopyable

#duplicable?

Methods inherited from Ractor::Port

#close, #closed?

Constructor Details

#initialize(mode: :copy, auto_local: false) ⇒ BasicObject

Creates a new port with the given default mode.

Valid modes are:

  • :copy - The value will be copied between Ractors. This is the default mode.
  • :make_shareable - The value will be made Ractor-shareable using Ractor.make_shareable.
  • :move - The value will be moved between Ractors. This saves memory compared to copying, and supports values that can't be copied but moved (like IO objects). However, the value will no longer be accessible on the Ractor that pushed it.
  • :mutable - A Mutable instance will be created for the value. This isn't done recursively and thus will fail for nested unshareable values.
  • :local - The value will be kept local to the Ractor that pushed it. Another ractor trying to receive it will get an error. Useful for usage contained within a single Ractor.
  • :proxy - The value will be wrapped in a Farce::Proxy that executes calls in the original Ractor.
  • :raise - An error will be raised if the value is not Ractor-shareable. Useful for enforcing shareability.
  • :dedup - The value will be deduplicated using Farce.dedup, then made Ractor-shareable. This may update and freeze the original. Already-shareable values pass through unchanged.
  • :shareable_copy - The value will be copied and the copy will be made Ractor-shareable.

Parameters:

  • mode (Symbol) (defaults to: :copy) —

    The default mode to use when sending values through this port.

  • auto_local (Boolean) (defaults to: false) —

    Whether to automatically use :local mode when sending values from the owning ractor.




# File 'lib/farce/port.rb', line 57

Instance Attribute Details

#mode ⇒ Symbol (readonly)

The port's default mode. Set via #initialize.

Returns:

  • (Symbol) —

    The default mode of this port.

See Also:



72
 
# File 'lib/farce/port.rb', line 72

def mode = self.class.mode

Instance Method Details

#auto_local? ⇒ Boolean

Whether or not auto_local is enabled by default. Set via #initialize.

Returns:

  • (Boolean) —

    true if auto_local is enabled, false otherwise.

See Also:



77
 
# File 'lib/farce/port.rb', line 77

def auto_local? = self.class.auto_local?

#inspect ⇒ String

Returns A string representation of the port, including its class name and mode.

Returns:

  • (String) —

    A string representation of the port, including its class name and mode.



132
 
# File 'lib/farce/port.rb', line 132

def inspect = super.sub(/\A#<.+? (?=(?:to|id):#?\d+)/, "#<Farce::Port mode:#{mode} ")

#receive(timeout: nil) ⇒ BasicObject?

Waits for a message or the timeout. Only the owning Ractor can receive. Automatically opens envelopes created by this port's mode manager.

Parameters:

  • timeout (Numeric, nil) (defaults to: nil) —

    the maximum seconds to wait, or nil to wait indefinitely

Returns:

  • (BasicObject, nil) —

    the received message, or nil on timeout

Raises:



125
126
127
128
129
 
# File 'lib/farce/port.rb', line 125

def receive(timeout: nil)
  # Omit the absent keyword instead of allocating arguments for super.
  result = timeout.nil? ? super() : super
  MANAGER.unwrap(result)
end

#send(message, move: nil, mode: nil, auto_local: nil) ⇒ self

Sends a message through the port.

Parameters:

  • message (BasicObject) —

    The message to send.

  • move (Boolean, nil) (defaults to: 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.

  • mode (Symbol, nil) (defaults to: 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.

  • auto_local (Boolean, nil) (defaults to: 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.

Returns:

  • (self)

Raises:



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/farce/port.rb', line 99

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