class Ractor::Port - Documentation for Ruby 4.1
Description: class Ractor::Port: Port objects transmit messages between Ractors.
Keywords: ruby,class,Ractor::Port

🔍

No recent searches

# class Ractor::Port

Port objects transmit messages between Ractors.

### Public Class Methods

Ractor::Port.new → new_port
Source

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

Returns a new `Ractor::Port` object.

### Public Instance Methods

<<
Alias for: send
close
Source

    # File 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

closed? → true/false
Source

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

Returns whether or not the port is closed.

inspect → string
Source

    # File 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

receive → msg
Source

    # File 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

send(msg, move: false) → self
Source

    # File 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.

Also aliased as: <<