polyphony 0.78 → 0.81

data/lib/polyphony/extensions/thread.rb

@@ -5,8 +5,11 @@ require_relative '../core/exceptions'
 # Thread extensions
 class ::Thread
   attr_reader :main_fiber, :result
+  attr_accessor :backend
 
   alias_method :orig_initialize, :initialize
+
+  # Initializes the thread.
   def initialize(*args, &block)
     @join_wait_queue = []
     @finalization_mutex = Mutex.new
@@ -15,53 +18,30 @@ class ::Thread
     orig_initialize { execute }
   end
 
-  def execute
-    # backend must be created in the context of the new thread, therefore it
-    # cannot be created in Thread#initialize
-    raise_error = false
-    begin
-      @backend = Polyphony::Backend.new
-    rescue Exception => e
-      raise_error = true
-      raise e
-    end
-    setup
-    @ready = true
-    result = @block.(*@args)
-  rescue Polyphony::MoveOn, Polyphony::Terminate => e
-    result = e.value
-  rescue Exception => e
-    raise_error ? (raise e) : (result = e)
-  ensure
-    @ready = true
-    finalize(result)
-  end
-
-  attr_accessor :backend
-
+  # Sets up the thread and its main fiber.
+  #
+  # @return [void]
   def setup
     @main_fiber = Fiber.current
     @main_fiber.setup_main_fiber
     setup_fiber_scheduling
   end
 
-  def finalize(result)
-    unless Fiber.current.children.empty?
-      Fiber.current.shutdown_all_children
-    end
-    @finalization_mutex.synchronize do
-      @terminated = true
-      @result = result
-      signal_waiters(result)
-    end
-    @backend&.finalize
-  end
-
-  def signal_waiters(result)
-    @join_wait_queue.each { |w| w.signal(result) }
-  end
-
   alias_method :orig_join, :join
+
+  # call-seq:
+  #   thread.join -> result
+  #   thread.join(timeout) -> result
+  #   thread.await -> result
+  #   thread.await(timeout) -> result
+  # 
+  # Waits for the thread to terminate and returns its return value. If the
+  # thread terminated with an uncaught exception, it is propagated to the
+  # waiting fiber. If a timeout interval is specified, the thread will be
+  # terminated without propagating the timeout exception.
+  #
+  # @param timeout [Number] timeout interval
+  # @return [any] thread's return value
   def join(timeout = nil)
     watcher = Fiber.current.auto_watcher
 
@@ -77,6 +57,16 @@ class ::Thread
   alias_method :await, :join
 
   alias_method :orig_raise, :raise
+
+  # call-seq:
+  #   thread.raise
+  #   thread.raise(exception_class)
+  #   thread.raise(exception_instance)
+  # 
+  # Raises an exception in the context of the thread. If no exception is given,
+  # a `RuntimeError` is raised.
+  #
+  # @param error [Exception, Class, nil] exception spec
   def raise(error = nil)
     Thread.pass until @main_fiber
     error = RuntimeError.new if error.nil?
@@ -88,13 +78,22 @@ class ::Thread
   end
 
   alias_method :orig_kill, :kill
+
+  # Terminates the thread.
+  #
+  # @return [Thread] self
   def kill
-    return if @terminated
+    return self if @terminated
 
     raise Polyphony::Terminate
+    self
   end
 
   alias_method :orig_inspect, :inspect
+
+  # Returns a string representation of the thread for debugging purposes.
+  #
+  # @return [String] string representation
   def inspect
     return orig_inspect if self == Thread.main
 
@@ -103,20 +102,86 @@ class ::Thread
   end
   alias_method :to_s, :inspect
 
+  # Returns the source location of the thread's block.
+  #
+  # @return [String] source location
   def location
     @block.source_location.join(':')
   end
 
-  def <<(value)
-    main_fiber << value
+  # Sends a message to the thread's main fiber.
+  #
+  # @param msg [any] message
+  # @return [Fiber] main fiber
+  def <<(msg)
+    main_fiber << msg
   end
   alias_method :send, :<<
 
+  # Sets the idle GC period for the thread's backend.
+  #
+  # @param period [Number] GC period in seconds
+  # @return [Number] GC period
   def idle_gc_period=(period)
     backend.idle_gc_period = period
   end
 
+  # Sets the idle handler for the thread's backend.
+  #
+  # @param &block [Proc] idle handler
+  # @return [Proc] idle handler
   def on_idle(&block)
     backend.idle_proc = block
   end
+
+  private
+
+  # Runs the thread's block, handling any uncaught exceptions.
+  #
+  # @return [void]
+  def execute
+    # backend must be created in the context of the new thread, therefore it
+    # cannot be created in Thread#initialize
+    raise_error = false
+    begin
+      @backend = Polyphony::Backend.new
+    rescue Exception => e
+      raise_error = true
+      raise e
+    end
+    setup
+    @ready = true
+    result = @block.(*@args)
+  rescue Polyphony::MoveOn, Polyphony::Terminate => e
+    result = e.value
+  rescue Exception => e
+    raise_error ? (raise e) : (result = e)
+  ensure
+    @ready = true
+    finalize(result)
+  end
+
+  # Finalizes the thread.
+  #
+  # @param result [any] thread's return value
+  # @return [void]
+  def finalize(result)
+    unless Fiber.current.children.empty?
+      Fiber.current.shutdown_all_children
+    end
+    @finalization_mutex.synchronize do
+      @terminated = true
+      @result = result
+      signal_waiters(result)
+    end
+    @backend&.finalize
+  end
+
+  # Signals all fibers waiting for the thread to terminate.
+  #
+  # @param result [any] thread's return value
+  # @return [void]
+  def signal_waiters(result)
+    @join_wait_queue.each { |w| w.signal(result) }
+  end
 end

data/lib/polyphony/extensions/timeout.rb

@@ -2,8 +2,19 @@
 
 require 'timeout'
 
-# Override Timeout to use cancel scope
+# Timeout extensions
 module ::Timeout
+
+  # Sets a timeout for the given block. This method provides an equivalent API
+  # to the stock Timeout API provided by Ruby. In case of a timeout, the block
+  # will be interrupted and an exception will be raised according to the given
+  # arguments.
+  #
+  # @param sec [Number] timeout period in seconds
+  # @param klass [Class] exception class
+  # @param message [String] exception message
+  # @param &block [Proc] 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)
   end

data/lib/polyphony/extensions.rb

@@ -3,6 +3,7 @@
 require_relative './extensions/exception'
 require_relative './extensions/fiber'
 require_relative './extensions/io'
+require_relative './extensions/object'
 require_relative './extensions/kernel'
 require_relative './extensions/process'
 require_relative './extensions/thread'

data/lib/polyphony/net.rb

@@ -4,9 +4,25 @@ require_relative './extensions/socket'
 require_relative './extensions/openssl'
 
 module Polyphony
+  
   # A more elegant networking API
   module Net
     class << self
+
+      # call-seq:
+      #   Polyphony::Net.tcp_connect(host, port) -> TCPSocket
+      #   Polyphony::Net.tcp_connect(host, port, secure: true) -> SSLSocket
+      #   Polyphony::Net.tcp_connect(host, port, secure_context: ctx) -> SSLSocket
+      #
+      # Create a TCP connection to the given host and port, returning the new
+      # socket. If `opts[:secure]` is true, or if an SSL context is given in
+      # `opts[:secure_context]`, a TLS handshake is performed, and an SSLSocket
+      # is returned.
+      #
+      # @param host [String] hostname
+      # @param port [Integer] port number
+      # @param opts [Hash] connection options
+      # @return [TCPSocket, SSLSocket] connected socket
       def tcp_connect(host, port, opts = {})
         socket = TCPSocket.new(host, port)
         if opts[:secure_context] || opts[:secure]
@@ -16,6 +32,15 @@ module Polyphony
         end
       end
 
+      # Creates a server socket for accepting incoming connection on the given
+      # host and port. If `opts[:secure]` is true, or if an SSL context is given
+      # in `opts[:secure_context]`, a TLS handshake is performed, and an
+      # SSLSocket is returned.
+      #
+      # @param host [String] hostname
+      # @param port [Integer] port number
+      # @param opts [Hash] connection options
+      # @return [TCPServer, SSLServer] listening socket
       def tcp_listen(host = nil, port = nil, opts = {})
         host ||= '0.0.0.0'
         raise 'Port number not specified' unless port
@@ -28,6 +53,29 @@ module Polyphony
         end
       end
 
+      # Sets up ALPN negotiation for the given context. The ALPN handler for the
+      # context will select the first protocol from the list given by the client
+      # that appears in the list of given protocols, according to the specified
+      # order.
+      # 
+      # @param context [SSLContext] SSL context
+      # @param protocols [Array] array of supported protocols
+      # @return [void]
+      def setup_alpn(context, protocols)
+        context.alpn_protocols = protocols
+        context.alpn_select_cb = lambda do |peer_protocols|
+          (protocols & peer_protocols).first
+        end
+      end
+
+      private
+
+      # Creates a listening `Socket` instance.
+      #
+      # @param host [String] hostname
+      # @param port [Integer] port number
+      # @param opts [Hash] connection options
+      # @return [Socket] listening socket
       def listening_socket_from_options(host, port, opts)
         ::Socket.new(:INET, :STREAM).tap do |s|
           s.reuse_addr if opts[:reuse_addr]
@@ -39,6 +87,12 @@ module Polyphony
         end
       end
 
+      # Wraps the given socket with a SSLSocket and performs a TLS handshake.
+      #
+      # @param socket [Socket] plain socket
+      # @param context [SSLContext, nil] SSL context
+      # @param opts [Hash] connection options
+      # @return [SSLSocket] SSL socket
       def secure_socket(socket, context, opts)
         context ||= OpenSSL::SSL::SSLContext.new
         setup_alpn(context, opts[:alpn_protocols]) if opts[:alpn_protocols]
@@ -51,6 +105,11 @@ module Polyphony
         end
       end
 
+      # Wraps the given socket with an SSLSocket.
+      #
+      # @param socket [Socket] plain socket
+      # @param context [SSLContext] SSL context
+      # @return [SSLSocket] SSL socket
       def secure_socket_wrapper(socket, context)
         if context
           OpenSSL::SSL::SSLSocket.new(socket, context)
@@ -59,17 +118,17 @@ module Polyphony
         end
       end
 
+      # Wraps the given socket with an SSLServer, setting up ALPN from the given
+      # options.
+      #
+      # @param socket [Socket] plain socket
+      # @param context [SSLContext] SSL context
+      # @param opts [Hash] options
+      # @return [SSLServer] SSL socket
       def secure_server(socket, context, opts)
         setup_alpn(context, opts[:alpn_protocols]) if opts[:alpn_protocols]
         OpenSSL::SSL::SSLServer.new(socket, context)
       end
-
-      def setup_alpn(context, protocols)
-        context.alpn_protocols = protocols
-        context.alpn_select_cb = lambda do |peer_protocols|
-          (protocols & peer_protocols).first
-        end
-      end
     end
   end
 end

data/lib/polyphony/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Polyphony
-  VERSION = '0.78'
+  VERSION = '0.81'
 end

data/lib/polyphony.rb

@@ -9,7 +9,6 @@ Thread.current.backend = Polyphony::Backend.new
 
 require_relative './polyphony/extensions'
 require_relative './polyphony/core/exceptions'
-require_relative './polyphony/core/global_api'
 require_relative './polyphony/core/resource_pool'
 require_relative './polyphony/core/sync'
 require_relative './polyphony/core/timer'
@@ -53,7 +52,6 @@ module Polyphony
 
     def run_forked_block(&block)
       Thread.current.setup
-      Fiber.current.setup_main_fiber
       Thread.current.backend.post_fork
 
       install_terminating_signal_handlers

data/test/test_backend.rb

@@ -191,7 +191,9 @@ class BackendTest < MiniTest::Test
   Net = Polyphony::Net
 
   def test_accept
-    server = Net.listening_socket_from_options('127.0.0.1', 1234, reuse_addr: true)
+    server = Net.send(
+      :listening_socket_from_options, '127.0.0.1', 1234, reuse_addr: true
+    )
 
     clients = []
     server_fiber = spin_loop do
@@ -218,7 +220,9 @@ class BackendTest < MiniTest::Test
   end
 
   def test_accept_loop
-    server = Net.listening_socket_from_options('127.0.0.1', 1235, reuse_addr: true)
+    server = Net.send(
+      :listening_socket_from_options, '127.0.0.1', 1235, reuse_addr: true
+    )
 
     clients = []
     server_fiber = spin do

data/test/test_global_api.rb

@@ -140,17 +140,6 @@ class MoveOnAfterTest < MiniTest::Test
     assert_in_range 0.014..0.02, t1 - t0 if IS_LINUX
   end
 
-  def test_move_on_after_without_block
-    t0 = Time.now
-    f = move_on_after(0.01, with_value: 'foo')
-    assert_kind_of Fiber, f
-    assert_equal Fiber.current, f.parent
-    v = sleep 1
-    t1 = Time.now
-    assert t1 - t0 < 0.1
-    assert_equal 'foo', v
-  end
-
   def test_nested_move_on_after
     skip unless IS_LINUX
 
@@ -190,18 +179,6 @@ class CancelAfterTest < MiniTest::Test
     assert t1 - t0 < 0.1
   end
 
-  def test_cancel_after_without_block
-    t0 = Time.now
-    f = cancel_after(0.01)
-    assert_kind_of Fiber, f
-    assert_equal Fiber.current, f.parent
-    assert_raises Polyphony::Cancel do
-      sleep 1
-    end
-    t1 = Time.now
-    assert t1 - t0 < 0.1
-  end
-
   def test_cancel_after_with_reset
     t0 = Time.now
     cancel_after(0.01) do |f|

data/test/test_io.rb

@@ -309,13 +309,13 @@ class IOClassMethodsTest < MiniTest::Test
     assert_equal BIN_DATA, s
   end
 
-  def test_foreach
-    skip 'IO.foreach is not yet implemented'
-    lines = []
-    IO.foreach(__FILE__) { |l| lines << l }
-    assert_equal "# frozen_string_literal: true\n", lines[0]
-    assert_equal "end\n", lines[-1]
-  end
+  # def test_foreach
+  #   skip 'IO.foreach is not yet implemented'
+  #   lines = []
+  #   IO.foreach(__FILE__) { |l| lines << l }
+  #   assert_equal "# frozen_string_literal: true\n", lines[0]
+  #   assert_equal "end\n", lines[-1]
+  # end
 
   def test_read_class_method
     s = IO.read(__FILE__)

data/test/test_resource_pool.rb

@@ -88,7 +88,7 @@ class ResourcePoolTest < MiniTest::Test
     assert_equal 2, pool.limit
     assert_equal 0, pool.size
 
-    pool.preheat!
+    pool.fill!
     assert_equal 2, pool.size
   end
 

data/test/test_signal.rb

@@ -33,24 +33,24 @@ class SignalTrapTest < Minitest::Test
     Fiber.current.tag = :main
 
     expected = [
-      [:fiber_switchpoint, :main],
-      [:fiber_event_poll_enter, :main],
-      [:fiber_create, :oob],
-      [:fiber_schedule, :oob],
-      [:fiber_event_poll_leave, :main],
-      [:fiber_run, :oob],
-      [:fiber_terminate, :oob],
-      [:fiber_switchpoint, :oob],
-      [:fiber_event_poll_enter, :oob],
-      [:fiber_schedule, :main],
-      [:fiber_event_poll_leave, :oob],
-      [:fiber_run, :main]
+      [:block, :main],
+      [:enter_poll, :main],
+      [:spin, :oob],
+      [:schedule, :oob],
+      [:leave_poll, :main],
+      [:unblock, :oob],
+      [:terminate, :oob],
+      [:block, :oob],
+      [:enter_poll, :oob],
+      [:schedule, :main],
+      [:leave_poll, :oob],
+      [:unblock, :main]
     ]
     if Thread.backend.kind == :libev
       expected += [
-        [:fiber_schedule, :main],
-        [:fiber_switchpoint, :main],
-        [:fiber_run, :main]
+        [:schedule, :main],
+        [:block, :main],
+        [:unblock, :main]
       ]
     end
 

data/test/test_thread.rb

@@ -132,7 +132,7 @@ class ThreadTest < MiniTest::Test
     Thread.backend.trace_proc = proc {|*r| records << r }
     suspend
     assert_equal [
-      [:fiber_switchpoint, Fiber.current, ["#{__FILE__}:#{__LINE__ - 2}:in `test_that_suspend_returns_immediately_if_no_watchers'"] + caller]
+      [:block, Fiber.current, ["#{__FILE__}:#{__LINE__ - 2}:in `test_that_suspend_returns_immediately_if_no_watchers'"] + caller]
     ], records
   ensure
     Thread.backend.trace_proc = nil

data/test/test_throttler.rb

@@ -11,8 +11,6 @@ class ThrottlerTest < MiniTest::Test
     sleep 0.2
     f.stop
     assert_in_range 1..4, buffer.size if IS_LINUX
-  ensure
-    t.stop
   end
 
   def test_throttler_with_hash_of_rate
@@ -24,8 +22,6 @@ class ThrottlerTest < MiniTest::Test
     sleep 0.25
     f.stop
     assert_in_range 4..6, buffer.size if IS_LINUX
-  ensure
-    t.stop
   end
 
   def test_throttler_with_hash_of_interval
@@ -35,8 +31,6 @@ class ThrottlerTest < MiniTest::Test
     sleep 0.02
     f.stop
     assert_in_range 2..4, buffer.size if IS_LINUX
-  ensure
-    t.stop
   end
 
   def test_throttler_with_invalid_argument