polyphony 0.99 → 0.99.1

data/lib/polyphony/extensions/openssl.rb

@@ -5,30 +5,40 @@ require_relative './socket'
 
 # OpenSSL socket helper methods (to make it compatible with Socket API) and overrides
 class ::OpenSSL::SSL::SSLSocket
+  # @!visibility private
   def __read_method__
     :readpartial
   end
 
+  # @!visibility private
   alias_method :orig_initialize, :initialize
 
-  # TODO: add docs to all methods in this file
+  # Initializese a new SSL socket
+  #
+  # @param socket [TCPSocket] socket to wrap
+  # @param context [OpenSSL::SSL::SSLContext] optional SSL context
+  # @return [void]
   def initialize(socket, context = nil)
     socket = socket.respond_to?(:io) ? socket.io || socket : socket
     context ? orig_initialize(socket, context) : orig_initialize(socket)
   end
 
+  # Sets DONT_LINGER option
   def dont_linger
     io.dont_linger
   end
 
+  # Sets NO_DELAY option
   def no_delay
     io.no_delay
   end
 
+  # Sets REUSE_ADDR option
   def reuse_addr
     io.reuse_addr
   end
 
+  # @!visibility private
   def fill_rbuff
     data = self.sysread(BLOCK_SIZE)
     if data
@@ -38,7 +48,10 @@ class ::OpenSSL::SSL::SSLSocket
     end
   end
 
+  # @!visibility private
   alias_method :orig_sysread, :sysread
+
+  # @!visibility private
   def sysread(maxlen, buf = +'')
     # ensure socket is non blocking
     Polyphony.backend_verify_blocking_mode(io, false)
@@ -51,7 +64,10 @@ class ::OpenSSL::SSL::SSLSocket
     end
   end
 
+  # @!visibility private
   alias_method :orig_syswrite, :syswrite
+
+  # @!visibility private
   def syswrite(buf)
     # ensure socket is non blocking
     Polyphony.backend_verify_blocking_mode(io, false)
@@ -65,16 +81,35 @@ class ::OpenSSL::SSL::SSLSocket
     end
   end
 
+  # @!visibility private
   def flush
-    # osync = @sync
-    # @sync = true
-    # do_write ""
-    # return self
-    # ensure
-    # @sync = osync
+    # warn "SSLSocket#flush is not yet implemented in Polyphony"
   end
 
+  # @!visibility private
   alias_method :orig_read, :read
+
+  # call-seq:
+  #   socket.read -> string
+  #   socket.read(maxlen) -> string
+  #   socket.read(maxlen, buf) -> buf
+  #   socket.read(maxlen, buf, buf_pos) -> buf
+  #
+  # Reads from the socket. If `maxlen` is given, reads up to `maxlen` bytes from
+  # the socket, otherwise reads to `EOF`. If `buf` is given, it is used as the
+  # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
+  # given, reads into the given offset (in bytes) in the given buffer. If the
+  # given buffer offset is negative, it is calculated from the current end of
+  # the buffer (`-1` means the read data will be appended to the end of the
+  # buffer).
+  #
+  # If no bytes are available and `EOF` is not hit, this method will block until
+  # the socket is ready to read from.
+  #
+  # @param maxlen [Integer, nil] maximum bytes to read from socket
+  # @param buf [String, nil] buffer to read into
+  # @param buf_pos [Number] buffer position to read into
+  # @return [String] buffer used for reading
   def read(maxlen = nil, buf = nil, buf_pos = 0)
     return readpartial(maxlen, buf, buf_pos) if buf
 
@@ -88,13 +123,35 @@ class ::OpenSSL::SSL::SSLSocket
     buf
   end
 
-  def readpartial(maxlen, buf = +'', buffer_pos = 0, raise_on_eof = true)
-    if buffer_pos != 0
+  # call-seq:
+  #   socket.readpartial(maxlen) -> string
+  #   socket.readpartial(maxlen, buf) -> buf
+  #   socket.readpartial(maxlen, buf, buf_pos) -> buf
+  #   socket.readpartial(maxlen, buf, buf_pos, raise_on_eof) -> buf
+  #
+  # Reads up to `maxlen` from the socket. If `buf` is given, it is used as the
+  # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
+  # given, reads into the given offset (in bytes) in the given buffer. If the
+  # given buffer offset is negative, it is calculated from the current end of
+  # the buffer (`-1` means the read data will be appended to the end of the
+  # buffer). If `raise_on_eof` is `true` (the default,) an `EOFError` will be
+  # raised on `EOF`, otherwise `nil` will be returned.
+  #
+  # If no bytes are available and `EOF` is not hit, this method will block until
+  # the socket is ready to read from.
+  #
+  # @param maxlen [Integer, nil] maximum bytes to read from socket
+  # @param buf [String, nil] buffer to read into
+  # @param buf_pos [Number] buffer position to read into
+  # @param raise_on_eof [bool] whether to raise an exception on `EOF`
+  # @return [String, nil] buffer used for reading or nil on `EOF`
+  def readpartial(maxlen, buf = +'', buf_pos = 0, raise_on_eof = true)
+    if buf_pos != 0
       if (result = sysread(maxlen, +''))
-        if buffer_pos == -1
+        if buf_pos == -1
           result = buf + result
         else
-          result = buf[0...buffer_pos] + result
+          result = buf[0...buf_pos] + result
         end
       end
     else
@@ -105,6 +162,18 @@ class ::OpenSSL::SSL::SSLSocket
     result
   end
 
+  # call-seq:
+  #   socket.recv_loop { |data| ... }
+  #   socket.recv_loop(maxlen) { |data| ... }
+  #   socket.read_loop { |data| ... }
+  #   socket.read_loop(maxlen) { |data| ... }
+  #
+  # Receives up to `maxlen` bytes at a time in an infinite loop. Read buffers
+  # will be passed to the given block.
+  #
+  # @param maxlen [Integer] maximum bytes to receive
+  # @yield [String] handler block
+  # @return [void]
   def read_loop(maxlen = 8192)
     while (data = sysread(maxlen))
       yield data
@@ -112,7 +181,10 @@ class ::OpenSSL::SSL::SSLSocket
   end
   alias_method :recv_loop, :read_loop
 
+  # @!visibility private
   alias_method :orig_peeraddr, :peeraddr
+
+  # @!visibility private
   def peeraddr(_ = nil)
     orig_peeraddr
   end
@@ -122,7 +194,12 @@ end
 class ::OpenSSL::SSL::SSLServer
   attr_reader :ctx
 
+  # @!visibility private
   alias_method :orig_accept, :accept
+
+  # Accepts a new connection and performs SSL handshake.
+  #
+  # @return [OpenSSL::SSL::SSLSocket] accepted SSL connection
   def accept
     # when @ctx.servername_cb is set, we use a worker thread to run the
     # ssl.accept call. We need to do this because:
@@ -165,6 +242,7 @@ class ::OpenSSL::SSL::SSLServer
     end
   end
 
+  # @!visibility private
   def start_accept_worker_thread
     fiber = Fiber.current
     @accept_worker_thread = Thread.new do
@@ -187,16 +265,27 @@ class ::OpenSSL::SSL::SSLServer
     @accept_worker_fiber = receive
   end
 
+  # @!visibility private
   def use_accept_worker_thread?
     !!@ctx.servername_cb
   end
 
+  # @!visibility private
   alias_method :orig_close, :close
+
+  # @!visibility private
   def close
     @accept_worker_thread&.kill
     orig_close
   end
 
+  # call-seq:
+  #   socket.accept_loop { |conn| ... }
+  #
+  # Accepts incoming connections in an infinite loop.
+  #
+  # @yield [OpenSSL::SSL::SSLSocket] block receiving accepted sockets
+  # @return [void]
   def accept_loop(ignore_errors = true)
     loop do
       yield accept

data/lib/polyphony/extensions/pipe.rb

@@ -1,20 +1,32 @@
 # frozen_string_literal: true
 
-# Pipe instance methods
+# A Pipe instance represents a UNIX pipe that can be read and written to. This
+# API is an alternative to the `IO.pipe` API, that returns two separate fds, one
+# for reading and one for writing. Instead, `Polyphony::Pipe` encapsulates the
+# two fds in a single object, providing methods that enable us to treat the pipe
+# as a normal IO object.
 class Polyphony::Pipe
+  # @!visibility private
   def __read_method__
     :backend_read
   end
 
+  # @!visibility private
   def __write_method__
     :backend_write
   end
 
+  # Reads a single byte from the pipe.
+  #
+  # @return [Integer, nil] byte value
   def getbyte
     char = getc
     char ? char.getbyte(0) : nil
   end
 
+  # Reads a single character from the pipe.
+  #
+  # @return |String, nil] read character
   def getc
     return @read_buffer.slice!(0) if @read_buffer && !@read_buffer.empty?
 
@@ -25,6 +37,12 @@ class Polyphony::Pipe
     nil
   end
 
+  # Reads from the pipe.
+  #
+  # @param len [Integer, nil] maximum bytes to read
+  # @param buf [String, nil] buffer to read into
+  # @param buf_pos [Integer] buffer position to read into
+  # @return [String] read data
   def read(len = nil, buf = nil, buf_pos = 0)
     if buf
       return Polyphony.backend_read(self, buf, len, true, buf_pos)
@@ -39,22 +57,48 @@ class Polyphony::Pipe
     already_read
   end
 
-  def readpartial(len, str = +'', buffer_pos = 0, raise_on_eof = true)
-    result = Polyphony.backend_read(self, str, len, false, buffer_pos)
+  # Reads from the pipe.
+  #
+  # @param len [Integer, nil] maximum bytes to read
+  # @param buf [String, nil] buffer to read into
+  # @param buf_pos [Integer] buffer position to read into
+  # @param raise_on_eof [boolean] whether to raise an error if EOF is detected
+  # @return [String] read data
+  def readpartial(len, buf = +'', buf_pos = 0, raise_on_eof = true)
+    result = Polyphony.backend_read(self, buf, len, false, buf_pos)
     raise EOFError if !result && raise_on_eof
 
     result
   end
 
-  def write(str, *args)
-    Polyphony.backend_write(self, str, *args)
+  # Writes to the pipe.
+  
+  # @param buf [String] data to write
+  # @param args [any] further arguments to pass to Polyphony.backend_write
+  # @return [Integer] bytes written
+  def write(buf, *args)
+    Polyphony.backend_write(self, buf, *args)
   end
 
-  def <<(str)
-    Polyphony.backend_write(self, str)
+  # Writes to the pipe.
+  
+  # @param buf [String] data to write
+  # @return [Integer] bytes written
+  def <<(buf)
+    Polyphony.backend_write(self, buf)
     self
   end
 
+  # call-seq:
+  #   pipe.gets(limit, chomp)
+  #   pipe.gets(separator, limit, chomp)
+  #
+  # Reads a single line from the pipe.
+  #
+  # @param sep [String] line separator
+  # @param _limit [Integer, nil] line length limit
+  # @param _chomp [boolean, nil] whether to chomp the read line
+  # @return [String, nil] read line
   def gets(sep = $/, _limit = nil, _chomp: nil)
     if sep.is_a?(Integer)
       sep = $/
@@ -84,9 +128,14 @@ class Polyphony::Pipe
   # def putc(obj)
   # end
 
+  # @!visibility private
   LINEFEED = "\n"
+  # @!visibility private
   LINEFEED_RE = /\n$/.freeze
 
+  # Writes a line with line feed to the pipe.
+  # 
+  # @param args [Array] zero or more lines
   def puts(*args)
     if args.empty?
       write LINEFEED
@@ -121,22 +170,55 @@ class Polyphony::Pipe
   # def readlines(sep = $/, limit = nil, chomp: nil)
   # end
 
+  # @!visibility private
   def write_nonblock(string, _options = {})
     write(string)
   end
 
+  # @!visibility private
   def read_nonblock(maxlen, buf = nil, _options = nil)
     buf ? readpartial(maxlen, buf) : readpartial(maxlen)
   end
 
+  # Runs a read loop.
+  #
+  # @param maxlen [Integer] maximum bytes to read
+  # @yield [String] read block
+  # @return [void]
   def read_loop(maxlen = 8192, &block)
     Polyphony.backend_read_loop(self, maxlen, &block)
   end
 
+  # call-seq:
+  #   pipe.feed_loop(receiver, method)
+  #   pipe.feed_loop(receiver, method) { |result| ... }
+  #
+  # Receives data from the pipe in an infinite loop, passing the data to the
+  # given receiver using the given method. If a block is given, the result of
+  # the method call to the receiver is passed to the block.
+  #
+  # This method can be used to feed data into parser objects. The following
+  # example shows how to feed data from a pipe directly into a MessagePack
+  # unpacker:
+  #
+  #   unpacker = MessagePack::Unpacker.new
+  #   buffer = []
+  #   reader = spin do
+  #     pipe.feed_loop(unpacker, :feed_each) { |msg| handle_msg(msg) }
+  #   end
+  #
+  # @param receiver [any] receiver object
+  # @param method [Symbol] method to call
+  # @yield [any] block to handle result of method call to receiver
+  # @return [void]
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_feed_loop(self, receiver, method, &block)
   end
 
+  # Waits for pipe to become readable.
+  #
+  # @param timeout [Number, nil] optional timeout in seconds
+  # @return [Polyphony::Pipe] self
   def wait_readable(timeout = nil)
     if timeout
       move_on_after(timeout) do
@@ -149,6 +231,10 @@ class Polyphony::Pipe
     end
   end
 
+  # Waits for pipe to become writeable.
+  #
+  # @param timeout [Number, nil] optional timeout in seconds
+  # @return [Polyphony::Pipe] self
   def wait_writable(timeout = nil)
     if timeout
       move_on_after(timeout) do
@@ -161,11 +247,21 @@ class Polyphony::Pipe
     end
   end
 
+  # Splices to the pipe from the given source.
+  #
+  # @param src [IO] source to splice from
+  # @param maxlen [Integer] maximum bytes to splice
+  # @return [Integer] bytes spliced
   def splice_from(src, maxlen)
     Polyphony.backend_splice(src, self, maxlen)
   end
 
   if RUBY_PLATFORM =~ /linux/
+    # Tees to the pipe from the given source.
+    #
+    # @param src [IO] source to tee from
+    # @param maxlen [Integer] maximum bytes to tee
+    # @return [Integer] bytes teed
     def tee_from(src, maxlen)
       Polyphony.backend_tee(src, self, maxlen)
     end

data/lib/polyphony/extensions/process.rb

@@ -1,16 +1,28 @@
 # frozen_string_literal: true
 
-# Overrides for Process
+# Overrides for Process module
 module ::Process
   class << self
+    # @!visibility private
     alias_method :orig_detach, :detach
+
+    # Detaches the given pid and returns a fiber waiting on it.
+    #
+    # @param pid [Integer] child pid
+    # @return [Fiber] new fiber waiting on pid
     def detach(pid)
       fiber = spin { Polyphony.backend_waitpid(pid) }
       fiber.define_singleton_method(:pid) { pid }
       fiber
     end
 
+    # @!visibility private
     alias_method :orig_daemon, :daemon
+
+    # Starts a daemon with the given arguments.
+    #
+    # @param args [any] arguments to pass to daemon
+    # @return [Integer] daemon pid
     def daemon(*args)
       orig_daemon(*args)
       Polyphony.original_pid = Process.pid