polyphony 0.99 → 0.99.1

data/lib/polyphony/extensions/socket.rb

@@ -6,7 +6,7 @@ require_relative './io'
 require_relative '../core/thread_pool'
 
 # BasicSocket extensions
-class BasicSocket
+class BasicSocket < ::IO
   # Returns `:backend_recv`. This method is used to tell parsers which read
   # method to use for this object.
   #
@@ -15,13 +15,17 @@ class BasicSocket
     :backend_recv
   end
 
+  # Returns `:backend_send`. This method is used to tell various libraries which
+  # write method to use for this object.
+  #
+  # @return [:backend_send] use Polyphony.backend_send to send DATA
   def __write_method__
     :backend_send
   end
 end
 
 # Socket extensions # TODO: rewrite in C
-class ::Socket
+class ::Socket < ::BasicSocket
 
   # Accepts an incoming connection.
   
@@ -35,12 +39,13 @@ class ::Socket
   #
   # Accepts incoming connections in an infinite loop.
   #
-  # @param &block [Proc] handler block
+  # @yield [Socket] block receiving accepted sockets
   # @return [void]
   def accept_loop(&block)
     Polyphony.backend_accept_loop(self, TCPSocket, &block)
   end
 
+  # @!visibility private
   NO_EXCEPTION = { exception: false }.freeze
 
   # Connects to the given address
@@ -53,6 +58,7 @@ class ::Socket
     self
   end
 
+  # @!visibility private
   alias_method :orig_read, :read
 
   # call-seq:
@@ -122,7 +128,7 @@ class ::Socket
   # will be passed to the given block.
   #
   # @param maxlen [Integer] maximum bytes to receive
-  # @param &block [Proc] handler block
+  # @yield [String] handler block
   # @return [void]
   def recv_loop(maxlen = 8192, &block)
     Polyphony.backend_recv_loop(self, maxlen, &block)
@@ -149,13 +155,17 @@ class ::Socket
   #
   # @param receiver [any] receiver object
   # @param method [Symbol] method to call
-  # @param &block [Proc] block to handle result of method call to receiver
+  # @yield [any] block to handle result of method call to receiver
   # @return [void]
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_recv_feed_loop(self, receiver, method, &block)
   end
 
-  # :no-doc:
+  # Reimplements #recvfrom.
+  #
+  # @param maxlen [Integer] maximum bytes to receive
+  # @param flags [Integer] optional flags
+  # @return [String] received data
   def recvfrom(maxlen, flags = 0)
     buf = +''
     while true
@@ -198,6 +208,7 @@ class ::Socket
     result
   end
 
+  # @!visibility private
   ZERO_LINGER = [0, 0].pack('ii').freeze
 
   # Sets the linger option to 0.
@@ -233,7 +244,8 @@ class ::Socket
   end
 
   class << self
-    alias_method :orig_getaddrinfo, :getaddrinfo
+  # @!visibility private
+  alias_method :orig_getaddrinfo, :getaddrinfo
     
     # Resolves the given addr using a worker thread from the default thread
     # pool.
@@ -246,9 +258,11 @@ class ::Socket
 end
 
 # Overide stock TCPSocket code by encapsulating a Socket instance
-class ::TCPSocket
+class ::TCPSocket < ::IPSocket
+  # @!visibility private
   NO_EXCEPTION = { exception: false }.freeze
 
+  # @!visibility private
   attr_reader :io
 
   class << self
@@ -275,6 +289,7 @@ class ::TCPSocket
     @io.connect(addr)
   end
 
+  # @!visibility private
   alias_method :orig_close, :close
   
   # Closes the socket.
@@ -285,6 +300,7 @@ class ::TCPSocket
     self
   end
 
+  # @!visibility private
   alias_method :orig_setsockopt, :setsockopt
   
   # Calls `setsockopt` with the given arguments.
@@ -295,6 +311,7 @@ class ::TCPSocket
     self
   end
 
+  # @!visibility private
   alias_method :orig_closed?, :closed?
   
   # Returns true if the socket is closed.
@@ -336,6 +353,7 @@ class ::TCPSocket
     self
   end
 
+  # @!visibility private
   alias_method :orig_read, :read
 
   # call-seq:
@@ -405,7 +423,7 @@ class ::TCPSocket
   # will be passed to the given block.
   #
   # @param maxlen [Integer] maximum bytes to receive
-  # @param &block [Proc] handler block
+  # @yield [String] handler block
   # @return [void]
   def recv_loop(maxlen = 8192, &block)
     Polyphony.backend_recv_loop(self, maxlen, &block)
@@ -432,7 +450,7 @@ class ::TCPSocket
   #
   # @param receiver [any] receiver object
   # @param method [Symbol] method to call
-  # @param &block [Proc] block to handle result of method call to receiver
+  # @yield [any] block to handle result of method call to receiver
   # @return [void]
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_recv_feed_loop(self, receiver, method, &block)
@@ -460,8 +478,8 @@ class ::TCPSocket
   # @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, str = +'', buffer_pos = 0, raise_on_eof = true)
-    result = Polyphony.backend_recv(self, str, maxlen, buffer_pos)
+  def readpartial(maxlen, buf = +'', buf_pos = 0, raise_on_eof = true)
+    result = Polyphony.backend_recv(self, buf, maxlen, buf_pos)
     raise EOFError if !result && raise_on_eof
     result
   end
@@ -476,8 +494,8 @@ class ::TCPSocket
   # @param buf [String, nil] read buffer
   # @param exception [bool] whether to raise an exception if not ready for reading
   # @return [String, :wait_readable] read buffer
-  def read_nonblock(len, buf = nil, exception: true)
-    @io.read_nonblock(len, buf, exception: exception)
+  def read_nonblock(maxlen, buf = nil, exception: true)
+    @io.read_nonblock(maxlen, buf, exception: exception)
   end
 
   # Performs a non-blocking to the socket. If the socket is not ready for
@@ -494,7 +512,7 @@ class ::TCPSocket
 end
 
 # TCPServer extensions
-class ::TCPServer
+class ::TCPServer < ::TCPSocket
 
   # Initializes the TCP server socket.
   #
@@ -503,10 +521,12 @@ class ::TCPServer
   def initialize(hostname = nil, port = 0)
     addr = Addrinfo.tcp(hostname, port)
     @io = Socket.new addr.afamily, Socket::SOCK_STREAM
+    @io.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEADDR, 1)
     @io.bind(addr)
     @io.listen(0)
   end
 
+  # @!visibility private
   alias_method :orig_accept, :accept
 
   # Accepts an incoming connection.
@@ -516,17 +536,33 @@ class ::TCPServer
     Polyphony.backend_accept(@io, TCPSocket)
   end
 
+  if Polyphony.instance_methods(false).include?(:backend_multishot_accept)
+    # Starts a multishot accept operation (only available with io_uring
+    # backend). Example usage:
+    #
+    #   server.multishot_accept do
+    #     server.accept_loop { |c| handle_connection(c) }
+    #   end
+    #
+    # @yield [TCPSocket] code block
+    # @return [any] return value of code block
+    def multishot_accept(&block)
+      Polyphony.backend_multishot_accept(@io, &block)
+    end
+  end
+
   # call-seq:
   #   socket.accept_loop { |conn| ... }
   #
   # Accepts incoming connections in an infinite loop.
   #
-  # @param &block [Proc] handler block
+  # @yield [TCPSocket] handler block
   # @return [void]
   def accept_loop(&block)
     Polyphony.backend_accept_loop(@io, TCPSocket, &block)
   end
 
+  # @!visibility private
   alias_method :orig_close, :close
   
   # Closes the server socket.
@@ -538,7 +574,9 @@ class ::TCPServer
   end
 end
 
-class ::UNIXServer
+# UNIXServer extensions
+class ::UNIXServer < ::UNIXSocket
+  # @!visibility private
   alias_method :orig_accept, :accept
 
   # Accepts an incoming connection.
@@ -553,14 +591,16 @@ class ::UNIXServer
   #
   # Accepts incoming connections in an infinite loop.
   #
-  # @param &block [Proc] handler block
+  # @yield [UNIXSocket] handler block
   # @return [void]
   def accept_loop(&block)
     Polyphony.backend_accept_loop(self, UNIXSocket, &block)
   end
 end
 
-class ::UNIXSocket
+# UNIXSocket extensions
+class ::UNIXSocket < ::BasicSocket
+  # @!visibility private
   alias_method :orig_read, :read
   
   # call-seq:
@@ -630,7 +670,7 @@ class ::UNIXSocket
   # will be passed to the given block.
   #
   # @param maxlen [Integer] maximum bytes to receive
-  # @param &block [Proc] handler block
+  # @yield [String] handler block
   # @return [void]
   def recv_loop(maxlen = 8192, &block)
     Polyphony.backend_recv_loop(self, maxlen, &block)
@@ -657,7 +697,7 @@ class ::UNIXSocket
   #
   # @param receiver [any] receiver object
   # @param method [Symbol] method to call
-  # @param &block [Proc] block to handle result of method call to receiver
+  # @yield [any] block to handle result of method call to receiver
   # @return [void]
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_recv_feed_loop(self, receiver, method, &block)
@@ -675,7 +715,7 @@ class ::UNIXSocket
   # Sends one or more strings on the socket. The strings are guaranteed to be
   # written as a single blocking operation.
   #
-  # @param *args [Array<String>] string buffers to write
+  # @param args [Array<String>] string buffers to write
   # @return [Integer] number of bytes written
   def write(*args)
     Polyphony.backend_sendv(self, args, 0)
@@ -711,8 +751,8 @@ class ::UNIXSocket
   # @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, str = +'', buffer_pos = 0, raise_on_eof = true)
-    result = Polyphony.backend_recv(self, str, maxlen, buffer_pos)
+  def readpartial(maxlen, buf = +'', buf_pos = 0, raise_on_eof = true)
+    result = Polyphony.backend_recv(self, buf, maxlen, buf_pos)
     raise EOFError if !result && raise_on_eof
     result
   end
@@ -727,8 +767,8 @@ class ::UNIXSocket
   # @param buf [String, nil] read buffer
   # @param exception [bool] whether to raise an exception if not ready for reading
   # @return [String, :wait_readable] read buffer
-  def read_nonblock(len, str = nil, exception: true)
-    @io.read_nonblock(len, str, exception: exception)
+  def read_nonblock(maxlen, buf = nil, exception: true)
+    @io.read_nonblock(maxlen, buf, exception: exception)
   end
 
   # Performs a non-blocking to the socket. If the socket is not ready for
@@ -744,21 +784,47 @@ class ::UNIXSocket
   end
 end
 
-class ::UDPSocket
+# UDPSocket extensions
+class ::UDPSocket < ::IPSocket
+  # Reimplements #recvfrom.
+  #
+  # @param maxlen [Integer] maximum bytes to receive
+  # @param flags [Integer] optional flags
+  # @return [String] received data
   def recvfrom(maxlen, flags = 0)
     buf = +''
     Polyphony.backend_recvmsg(self, buf, maxlen, 0, flags, 0, nil)
   end
 
+  # Reimplements #recvmsg.
+  #
+  # @param maxlen [Integer] maximum bytes to receive
+  # @param flags [Integer] optional flags
+  # @param maxcontrollen [Integer] maximum control bytes to receive
+  # @param opts [Hash] options
+  # @return [String] received data
   def recvmsg(maxlen = nil, flags = 0, maxcontrollen = nil, opts = {})
     buf = +''
     Polyphony.backend_recvmsg(self, buf, maxlen || 4096, 0, flags, maxcontrollen, opts)
   end
 
+  # Reimplements #sendmsg.
+  #
+  # @param msg [String] data to send
+  # @param flags [Integer] optional flags
+  # @param dest_sockaddr [Sockaddr, nil] optional destination address
+  # @param controls [Array] optional control data
+  # @return [Integer] bytes sent
   def sendmsg(msg, flags = 0, dest_sockaddr = nil, *controls)
     Polyphony.backend_sendmsg(self, msg, flags, dest_sockaddr, controls)
   end
 
+  # Sends data.
+  #
+  # @param msg [String] data to send
+  # @param flags [Integer] flags
+  # @param addr [Array] addresses to send to
+  # @return [Integer] bytes sent
   def send(msg, flags, *addr)
     sockaddr =  case addr.size
     when 2

data/lib/polyphony/extensions/thread.rb

@@ -7,9 +7,13 @@ class ::Thread
   attr_reader :main_fiber, :result
   attr_accessor :backend
 
+  # @!visibility private
   alias_method :orig_initialize, :initialize
 
   # Initializes the thread.
+  # @param args [Array] arguments to pass to thread block
+  # @yield [any] thread block
+  # @return [void]
   def initialize(*args, &block)
     @join_wait_queue = []
     @finalization_mutex = Mutex.new
@@ -27,6 +31,7 @@ class ::Thread
     setup_fiber_scheduling
   end
 
+  # @!visibility private
   alias_method :orig_join, :join
 
   # call-seq:
@@ -56,6 +61,7 @@ class ::Thread
   end
   alias_method :await, :join
 
+  # @!visibility private
   alias_method :orig_raise, :raise
 
   # call-seq:
@@ -77,6 +83,7 @@ class ::Thread
     main_fiber&.raise(error)
   end
 
+  # @!visibility private
   alias_method :orig_kill, :kill
 
   # Terminates the thread.
@@ -89,6 +96,7 @@ class ::Thread
     self
   end
 
+  # @!visibility private
   alias_method :orig_inspect, :inspect
 
   # Returns a string representation of the thread for debugging purposes.
@@ -128,7 +136,7 @@ class ::Thread
 
   # Sets the idle handler for the thread's backend.
   #
-  # @param &block [Proc] idle handler
+  # @yield [] idle handler
   # @return [Proc] idle handler
   def on_idle(&block)
     backend.idle_proc = block

data/lib/polyphony/extensions/timeout.rb

@@ -13,7 +13,7 @@ module ::Timeout
   # @param sec [Number] timeout period in seconds
   # @param klass [Class] exception class
   # @param message [String] exception message
-  # @param &block [Proc] code to run
+  # @yield [] code to run
   # @return [any] block's return value
   def self.timeout(sec, klass = Timeout::Error, message = 'execution expired', &block)
     cancel_after(sec, with_exception: [klass, message], &block)

data/lib/polyphony/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Polyphony
-  VERSION = '0.99'
+  # @!visibility private
+  VERSION = '0.99.1'
 end

data/lib/polyphony.rb

@@ -18,10 +18,14 @@ require_relative './polyphony/adapters/process'
 # Polyphony API
 module Polyphony
   class << self
+    # Creates a new Polyphony::Pipe instance.
+    #
+    # @return [Polyphony::Pipe] created pipe
     def pipe
       Pipe.new
     end
 
+    # @!visibility private
     def fork(&block)
       Kernel.fork do
         # A race condition can arise if a TERM or INT signal is received before
@@ -39,6 +43,19 @@ module Polyphony
       end
     end
 
+    # call-seq:
+    #   Polyphony.watch_process(cmd)
+    #   Polyphony.watch_process { sleep 1 }
+    # 
+    # Lubnches a process using either a command or a block for a forked process,
+    # waiting for the child process to terminate.
+    def watch_process(cmd = nil, &block)
+      Polyphony::Process.watch(cmd, &block)
+    end
+
+    private
+
+    # @!visibility private
     def spin_forked_block(&block)
       Fiber.new do
         run_forked_block(&block)
@@ -54,6 +71,7 @@ module Polyphony
       end
     end
 
+    # @!visibility private
     def run_forked_block(&block)
       Thread.current.setup
       Thread.current.backend.post_fork
@@ -63,6 +81,7 @@ module Polyphony
       block.()
     end
 
+    # @!visibility private
     def exit_forked_process
       terminate_threads
       Fiber.current.shutdown_all_children
@@ -74,10 +93,7 @@ module Polyphony
       exit
     end
 
-    def watch_process(cmd = nil, &block)
-      Polyphony::Process.watch(cmd, &block)
-    end
-
+    # @!visibility private
     def install_terminating_signal_handlers
       trap('SIGTERM') { raise SystemExit }
       orig_trap('SIGINT') do
@@ -86,6 +102,7 @@ module Polyphony
       end
     end
 
+    # @!visibility private
     def terminate_threads
       threads = Thread.list - [Thread.current]
       return if threads.empty?
@@ -94,8 +111,10 @@ module Polyphony
       threads.each(&:join)
     end
 
+    # @!visibility private
     attr_accessor :original_pid
 
+    # @!visibility private
     def install_at_exit_handler
       @original_pid = ::Process.pid
 
@@ -106,7 +125,7 @@ module Polyphony
       at_exit do
         next unless @original_pid == ::Process.pid
 
-        Polyphony.terminate_threads
+        terminate_threads
         Fiber.current.shutdown_all_children
       end
     end
@@ -123,10 +142,11 @@ module Polyphony
 
   Object.const_set(:ConditionVariable, Polyphony::ConditionVariable)
   $VERBOSE = verbose
+
+  install_terminating_signal_handlers
+  install_at_exit_handler
 end
 
-Polyphony.install_terminating_signal_handlers
-Polyphony.install_at_exit_handler
 
 if (debug_socket_path = ENV['POLYPHONY_DEBUG_SOCKET_PATH'])
   puts "Starting debug server on #{debug_socket_path}"

data/polyphony.gemspec

@@ -11,9 +11,7 @@ Gem::Specification.new do |s|
   s.homepage    = 'https://digital-fabric.github.io/polyphony'
   s.metadata    = {
     "source_code_uri" => "https://github.com/digital-fabric/polyphony",
-    # "documentation_uri" => "https://www.rubydoc.info/gems/polyphony",
-    "documentation_uri" => "https://digital-fabric.github.io/polyphony/",
-    "homepage_uri" => "https://digital-fabric.github.io/polyphony/",
+    "documentation_uri" => "https://www.rubydoc.info/gems/polyphony",
     "changelog_uri" => "https://github.com/digital-fabric/polyphony/blob/master/CHANGELOG.md"
   }
   s.rdoc_options = ["--title", "polyphony", "--main", "README.md"]
@@ -31,9 +29,4 @@ Gem::Specification.new do |s|
   s.add_development_dependency  'msgpack',              '1.6.0'
   s.add_development_dependency  'httparty',             '0.21.0'
   s.add_development_dependency  'localhost',            '1.1.10'
-
-  # s.add_development_dependency  'jekyll',               '~>3.8.6'
-  # s.add_development_dependency  'jekyll-remote-theme',  '~>0.4.1'
-  # s.add_development_dependency  'jekyll-seo-tag',       '~>2.6.1'
-  # s.add_development_dependency  'just-the-docs',        '~>0.3.0'
 end

data/test/stress.rb

@@ -3,7 +3,7 @@
 count = ARGV[0] ? ARGV[0].to_i : 100
 test_name = ARGV[1]
 
-$test_cmd = +'ruby test/run.rb  --name test_signal_handler_trace'
+$test_cmd = +'ruby test/run.rb'
 if test_name
   $test_cmd << " --name #{test_name}"
 end

data/test/test_global_api.rb

@@ -145,13 +145,13 @@ class MoveOnAfterTest < MiniTest::Test
 
     t0 = monotonic_clock
     o = move_on_after(0.01, with_value: 1) do
-      move_on_after(0.02, with_value: 2) do
+      move_on_after(0.03, with_value: 2) do
         sleep 1
       end
     end
     t1 = monotonic_clock
     assert_equal 1, o
-    assert_in_range 0.008..0.015, t1 - t0 if IS_LINUX
+    assert_in_range 0.008..0.027, t1 - t0 if IS_LINUX
 
     t0 = monotonic_clock
     o = move_on_after(0.05, with_value: 1) do
@@ -161,7 +161,7 @@ class MoveOnAfterTest < MiniTest::Test
     end
     t1 = monotonic_clock
     assert_equal 2, o
-    assert_in_range 0.008..0.013, t1 - t0 if IS_LINUX
+    assert_in_range 0.008..0.025, t1 - t0 if IS_LINUX
   end
 end
 
@@ -181,15 +181,17 @@ class CancelAfterTest < MiniTest::Test
 
   def test_cancel_after_with_reset
     t0 = monotonic_clock
-    cancel_after(0.01) do |f|
+    cancel_after(0.1) do |f|
       assert_kind_of Fiber, f
       assert_equal Fiber.current, f.parent
-      sleep 0.007
+      sleep 0.05
       f.reset
-      sleep 0.007
+      sleep 0.05
+      f.reset
+      sleep 0.05
     end
     t1 = monotonic_clock
-    assert_in_range 0.014..0.024, t1 - t0 if IS_LINUX
+    assert_in_range 0.14..0.24, t1 - t0 if IS_LINUX
   end
 
   class CustomException < Exception
@@ -228,6 +230,34 @@ class CancelAfterTest < MiniTest::Test
       assert_equal 'foo', e.message
     end
   end
+
+  def test_lots_of_cancel_after
+    cancels = 100
+
+    cancel_count = 0
+    cancels.times do
+      begin
+        cancel_after(0.001) { sleep 1 }
+      rescue Polyphony::Cancel
+        cancel_count += 1
+      end
+    end
+    assert_equal cancels, cancel_count
+  end
+
+  def test_cancel_after_with_lots_of_resets
+    resets = 100
+
+    t0 = monotonic_clock
+    cancel_after(0.1) do |f|
+      resets.times do
+        sleep 0.0001
+        f.reset
+      end
+    end
+    t1 = monotonic_clock
+    assert_in_range 0.01..0.2, t1 - t0 if IS_LINUX
+  end
 end
 
 
@@ -381,6 +411,14 @@ class ThrottledLoopTest < MiniTest::Test
     assert_in_range 0.075..0.15, t1 - t0 if IS_LINUX
     assert_equal [1, 2, 3, 4, 5], buffer
   end
+
+  def test_throttled_loop_inside_move_on_after
+    count = 0
+    move_on_after(0.1) do
+      throttled_loop(50) { count += 1 }
+    end
+    assert_in_range 3..7, count
+  end
 end
 
 class GlobalAPIEtcTest < MiniTest::Test