Add Ractor::Port (without test)

Author: soutaro

core/ractor.rbs

@@ -621,6 +621,166 @@ class Ractor
     def method_missing: (*untyped) -> untyped
   end
 
+  # <!-- rdoc-file=ractor.rb -->
+  # Port objects transmit messages between Ractors.
+  #
+  class Port[T = untyped]
+    # <!--
+    #   rdoc-file=ractor.rb
+    #   - <<(obj, move: false)
+    # -->
+    #
+    alias << send
+
+    # <!--
+    #   rdoc-file=ractor.rb
+    #   - port.close
+    # -->
+    # Close the port. On the closed port, sending is not prohibited. Receiving is
+    # also not allowed if there is no sent messages arrived before closing.
+    #
+    #     port = Ractor::Port.new
+    #     Ractor.new port do |port|
+    #       port.send 1 # OK
+    #       port.send 2 # OK
+    #       port.close
+    #       port.send 3 # raise Ractor::ClosedError
+    #     end
+    #
+    #     port.receive #=> 1
+    #     port.receive #=> 2
+    #     port.receive #=> raise Ractor::ClosedError
+    #
+    # Now, only a Ractor which creates the port is allowed to close ports.
+    #
+    #     port = Ractor::Port.new
+    #     Ractor.new port do |port|
+    #       port.close #=> closing port by other ractors is not allowed (Ractor::Error)
+    #     end.join
+    #
+    def close: () -> void
+
+    # <!--
+    #   rdoc-file=ractor.rb
+    #   - port.closed? -> true/false
+    # -->
+    # Return the port is closed or not.
+    #
+    def closed?: () -> bool
+
+    # <!--
+    #   rdoc-file=ractor.rb
+    #   - port.inspect -> string
+    # -->
+    #
+    def inspect: () -> String
+
+    # <!--
+    #   rdoc-file=ractor.rb
+    #   - port.receive -> msg
+    # -->
+    # Receive a message to the port (which was sent there by Port#send).
+    #
+    #     port = Ractor::Port.new
+    #     r = Ractor.new port do |port|
+    #       port.send('message1')
+    #     end
+    #
+    #     v1 = port.receive
+    #     puts "Received: #{v1}"
+    #     r.join
+    #     # Here will be printed: "Received: message1"
+    #
+    # The method blocks 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 close_incoming was called on the ractor, the method raises
+    # Ractor::ClosedError if there are no more messages in the message queue:
+    #
+    #     port = Ractor::Port.new
+    #     port.close
+    #     port.receive #=> raise Ractor::ClosedError
+    #
+    def receive: () -> T
+
+    # <!--
+    #   rdoc-file=ractor.rb
+    #   - port.send(msg, move: false) -> self
+    # -->
+    # Send a message to a port to be accepted by port.receive.
+    #
+    #     port = Ractor::Port.new
+    #     r = Ractor.new do
+    #       r.send 'message'
+    #     end
+    #     value = port.receive
+    #     puts "Received #{value}"
+    #     # Prints: "Received: message"
+    #
+    # The method is non-blocking (will return immediately even if the ractor 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 port which already closed its execution 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, it only send a reference to the object without
+    # cloning.
+    #
+    def send: (T obj, ?move: boolish) -> self
+
+    private
+
+    # <!--
+    #   rdoc-file=ractor_sync.c
+    #   - Ractor::Port.new  -> new_port
+    # -->
+    # Returns a new Ractor::Port object.
+    #
+    def initialize: () -> void
+
+    def initialize_copy: (untyped) -> untyped
+  end
+
   # <!-- rdoc-file=ractor.c -->
   # Raised on attempt to Ractor#take if there was an uncaught exception in the
   # Ractor. Its `cause` will contain the original exception, and `ractor` is the