Ractor::Port

Port objects transmit messages between Ractors.

Class Methods

Ractor::Port.new → new_port

          static VALUE
ractor_port_initialize(VALUE self)
{
    return ractor_port_init(self, GET_RACTOR());
}

Returns a new Ractor::Port object.

Instance Methods

<<(obj, move: false)

4.0 View on GitHub

An alias for

port.close

4.0 View on GitHub

          # File tmp/rubies/ruby-4.0.0/ractor.rb, line 806
def close
  __builtin_cexpr! %q{
    ractor_port_close(ec, self)
  }
end

Closes the port. Sending to a closed port is prohibited. Receiving is also prohibited if there are no messages in its message queue.

Only the Ractor which created the port is allowed to close it.

port = Ractor::Port.new
Ractor.new port do |port|
  port.close #=> closing port by other ractors is not allowed (Ractor::Error)
end.join

port.closed? → true/false

4.0 View on GitHub

          # File tmp/rubies/ruby-4.0.0/ractor.rb, line 817
def closed?
  __builtin_cexpr! %q{
    ractor_port_closed_p(ec, self);
  }
end

Returns whether or not the port is closed.

port.inspect → string

4.0 View on GitHub

          # File tmp/rubies/ruby-4.0.0/ractor.rb, line 826
def inspect
  "#<Ractor::Port to:\##{
    __builtin_cexpr! "SIZET2NUM(rb_ractor_id((RACTOR_PORT_PTR(self)->r)))"
  } id:#{
    __builtin_cexpr! "SIZET2NUM(ractor_port_id(RACTOR_PORT_PTR(self)))"
  }>"
end

No documentation available

port.receive → msg

4.0 View on GitHub

          # File tmp/rubies/ruby-4.0.0/ractor.rb, line 741
def receive
  __builtin_cexpr! %q{
    ractor_port_receive(ec, self)
  }
end

Receives a message from the port (which was sent there by Port#send). Only the ractor that created the port can receive messages this way.

port = Ractor::Port.new
r = Ractor.new port do |port|
  port.send('message1')
end

v1 = port.receive
puts "Received: #{v1}"
r.join
# This will print: "Received: message1"

The method blocks the current Thread if the message queue is empty.

port = Ractor::Port.new
r = Ractor.new port do |port|
  wait
  puts "Still not received"
  port.send('message1')
  wait
  puts "Still received only one"
  port.send('message2')
end
puts "Before first receive"
v1 = port.receive
puts "Received: #{v1}"
v2 = port.receive
puts "Received: #{v2}"
r.join

Output:

Before first receive
Still not received
Received: message1
Still received only one
Received: message2

If the port is closed and there are no more messages in the message queue, the method raises Ractor::ClosedError.

port = Ractor::Port.new
port.close
port.receive #=> raise Ractor::ClosedError

port.send(msg, move: false) → self

4.0 View on GitHub

          # File tmp/rubies/ruby-4.0.0/ractor.rb, line 784
def send obj, move: false
  __builtin_cexpr! %q{
    ractor_port_send(ec, self, obj, move)
  }
end

Sends a message to the port to be accepted by port.receive.

port = Ractor::Port.new
r = Ractor.new(port) do |port|
  port.send 'message'
end
value = port.receive
puts "Received #{value}"
# Prints: "Received: message"

The method is non-blocking (it will return immediately even if the ractor that created the port is not ready to receive anything):

port = Ractor::Port.new
r = Ractor.new(port) do |port|
  port.send 'test'
  puts "Sent successfully"
  # Prints: "Sent successfully" immediately
end

An attempt to send to a closed port will raise Ractor::ClosedError.

r = Ractor.new {Ractor::Port.new}
r.join
p r
# "#<Ractor:#6 (irb):23 terminated>"
port = r.value
port.send('test') # raise Ractor::ClosedError

If the obj is unshareable, by default it will be copied into the receiving ractor by deep cloning.

If the object is shareable, a reference to the object will be sent to the receiving ractor.