polyphony 0.79 → 0.80

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,14 @@ module Polyphony
         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 +72,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 +90,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,11 +103,26 @@ 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
 
+      # 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|

data/lib/polyphony/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Polyphony
-  VERSION = '0.79'
+  VERSION = '0.80'
 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_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_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

data/test/test_trace.rb

@@ -130,4 +130,91 @@ class TraceTest < MiniTest::Test
   ensure
     Thread.backend.trace_proc = nil
   end
+
+  def test_event_firehose_with_threaded_receiver
+    buffer = []
+    this = Fiber.current
+    receiver = Thread.new {
+      this << :ok
+      loop {
+        e = receive
+        break if e == :stop
+        buffer << e
+      }
+    }
+    receive
+    
+    Polyphony::Trace.start_event_firehose { |e| receiver << e }
+
+    f1 = spin(:f1) do
+      receive
+    end
+
+    f1 << :foo
+    f1.await
+
+    Thread.backend.trace_proc = nil
+    receiver << :stop
+    receiver.await
+
+    buffer.each { |e| e.delete(:stamp); e.delete(:caller) }
+
+    main = Fiber.current
+    assert_equal(
+      [
+        { event: :spin,       fiber: f1,                  source_fiber: main  },
+        { event: :schedule,   fiber: f1,    value: nil,   source_fiber: main  },
+        { event: :block,      fiber: main                                     },
+        { event: :unblock,    fiber: f1,    value: nil                        },
+        { event: :schedule,   fiber: f1,    value: nil,   source_fiber: f1    },
+        { event: :block,      fiber: f1,                                      },
+        { event: :enter_poll                                                  },
+        { event: :leave_poll                                                  },
+        { event: :unblock,    fiber: f1,    value: nil                        },
+        { event: :terminate,  fiber: f1,    value: :foo                       },
+        { event: :schedule,   fiber: main,  value: nil,   source_fiber: f1    },
+        { event: :block,      fiber: f1                                       },
+        { event: :unblock,    fiber: main,  value: nil                        }
+      ], buffer
+    )
+  ensure
+    Thread.backend.trace_proc = nil
+  end
+
+  # def test_event_firehose_with_reentrancy
+  #   buffer = []
+  #   Polyphony::Trace.start_event_firehose { |e| buffer << e }
+
+  #   f1 = spin(:f1) do
+  #     receive
+  #   end
+
+  #   f1 << :foo
+  #   f1.await
+
+  #   Thread.backend.trace_proc = nil
+  #   buffer.each { |e| e.delete(:stamp); e.delete(:caller) }
+
+  #   main = Fiber.current
+  #   assert_equal(
+  #     [
+  #       { event: :spin,       fiber: f1,                  source_fiber: main  },
+  #       { event: :schedule,   fiber: f1,    value: nil,   source_fiber: main  },
+  #       { event: :block,      fiber: main                                     },
+  #       { event: :unblock,    fiber: f1,    value: nil                        },
+  #       { event: :schedule,   fiber: f1,    value: nil,   source_fiber: f1    },
+  #       { event: :block,      fiber: f1,                                      },
+  #       { event: :enter_poll                                                  },
+  #       { event: :leave_poll                                                  },
+  #       { event: :unblock,    fiber: f1,    value: nil                        },
+  #       { event: :terminate,  fiber: f1,    value: :foo                       },
+  #       { event: :schedule,   fiber: main,  value: nil,   source_fiber: f1    },
+  #       { event: :block,      fiber: f1                                       },
+  #       { event: :unblock,    fiber: main,  value: nil                        }
+  #     ], buffer
+  #   )
+  # ensure
+  #   Thread.backend.trace_proc = nil
+  # end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: polyphony
 version: !ruby/object:Gem::Version
-  version: '0.79'
+  version: '0.80'
 platform: ruby
 authors:
 - Sharon Rosner
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-02-19 00:00:00.000000000 Z
+date: 2022-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -136,7 +136,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.1.4
-description:
+description: 
 email: sharon@noteflakes.com
 executables: []
 extensions:
@@ -249,6 +249,7 @@ files:
 - examples/core/trap2.rb
 - examples/core/using-a-mutex.rb
 - examples/core/worker-thread.rb
+- examples/core/zlib_stream.rb
 - examples/io/backticks.rb
 - examples/io/echo_client.rb
 - examples/io/echo_client_from_stdin.rb
@@ -358,7 +359,6 @@ files:
 - lib/polyphony/adapters/readline.rb
 - lib/polyphony/adapters/redis.rb
 - lib/polyphony/adapters/sequel.rb
-- lib/polyphony/core/channel.rb
 - lib/polyphony/core/debug.rb
 - lib/polyphony/core/exceptions.rb
 - lib/polyphony/core/global_api.rb
@@ -373,6 +373,7 @@ files:
 - lib/polyphony/extensions/fiber.rb
 - lib/polyphony/extensions/io.rb
 - lib/polyphony/extensions/kernel.rb
+- lib/polyphony/extensions/object.rb
 - lib/polyphony/extensions/openssl.rb
 - lib/polyphony/extensions/process.rb
 - lib/polyphony/extensions/socket.rb
@@ -415,7 +416,7 @@ metadata:
   documentation_uri: https://digital-fabric.github.io/polyphony/
   homepage_uri: https://digital-fabric.github.io/polyphony/
   changelog_uri: https://github.com/digital-fabric/polyphony/blob/master/CHANGELOG.md
-post_install_message:
+post_install_message: 
 rdoc_options:
 - "--title"
 - polyphony
@@ -434,8 +435,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
-signing_key:
+rubygems_version: 3.1.6
+signing_key: 
 specification_version: 4
 summary: Fine grained concurrency for Ruby
 test_files: []

data/lib/polyphony/core/channel.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-require_relative './exceptions'
-
-module Polyphony
-  # Implements a unidirectional communication channel along the lines of Go
-  # (buffered) channels.
-  class Channel < Polyphony::Queue
-    alias_method :receive, :shift
-
-    def close
-      flush_waiters(Polyphony::MoveOn.new)
-    end
-  end
-end