polyphony 0.77 → 0.80

data/lib/polyphony/core/thread_pool.rb

@@ -3,15 +3,25 @@
 require 'etc'
 
 module Polyphony
+  
   # Implements a pool of threads
   class ThreadPool
+  
+    # The pool size.
     attr_reader :size
 
+    # Runs the given block on an available thread from the default thread pool.
+    #
+    # @param &block [Proc] given block
+    # @return [any] return value of given block
     def self.process(&block)
       @default_pool ||= new
       @default_pool.process(&block)
     end
 
+    # Resets the default thread pool.
+    #
+    # @return [void]
     def self.reset
       return unless @default_pool
 
@@ -19,12 +29,20 @@ module Polyphony
       @default_pool = nil
     end
 
+    # Initializes the thread pool. The pool size defaults to the number of
+    # available CPU cores.
+    #
+    # @param size [Integer] number of threads in pool
     def initialize(size = Etc.nprocessors)
       @size = size
       @task_queue = Polyphony::Queue.new
       @threads = (1..@size).map { Thread.new { thread_loop } }
     end
 
+    # Runs the given block on an available thread from the pool.
+    #
+    # @param &block [Proc] given block
+    # @return [any] return value of block
     def process(&block)
       setup unless @task_queue
 
@@ -33,6 +51,12 @@ module Polyphony
       watcher.await
     end
 
+    # Adds a task to be performed asynchronously on a thread from the pool. This
+    # method does not block. The task will be performed once a thread becomes
+    # available.
+    #
+    # @param &block [Proc] given block
+    # @return [Polyphony::ThreadPool] self
     def cast(&block)
       setup unless @task_queue
 
@@ -40,16 +64,34 @@ module Polyphony
       self
     end
 
+    # Returns true if there are any currently running tasks, or any pending
+    # tasks waiting for a thread to become available.
+    #
+    # @return [bool] true if the pool is busy
     def busy?
       !@task_queue.empty?
     end
 
+    # Stops and waits for all threads in the queue to terminate.
+    def stop
+      @threads.each(&:kill)
+      @threads.each(&:join)
+    end
+
+    private
+
+    # Runs a processing loop on a worker thread.
+    #
+    # @return [void]
     def thread_loop
       while true
         run_queued_task
       end
     end
 
+    # Runs the first queued task in the task queue.
+    #
+    # @return [void]
     def run_queued_task
       (block, watcher) = @task_queue.shift
       result = block.()
@@ -57,10 +99,5 @@ module Polyphony
     rescue Exception => e
       watcher ? watcher.signal(e) : raise(e)
     end
-
-    def stop
-      @threads.each(&:kill)
-      @threads.each(&:join)
-    end
   end
 end

data/lib/polyphony/core/throttler.rb

@@ -3,31 +3,47 @@
 module Polyphony
   # Implements general-purpose throttling
   class Throttler
+
+    # Initializes a throttler instance with the given rate.
+    #
+    # @param rate [Number] throttler rate in times per second
     def initialize(rate)
       @rate = rate_from_argument(rate)
       @min_dt = 1.0 / @rate
       @next_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
     end
 
+    # call-seq:
+    #   throttler.call { ... }
+    #   throttler.process { ... }
+    #
+    # Invokes the throttler with the given block. The throttler will
+    # automatically introduce a delay to keep to the maximum specified rate.
+    # The throttler instance is passed to the given block.
+    #
+    # @return [any] given block's return value
     def call
       now = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       delta = @next_time - now
       Polyphony.backend_sleep(delta) if delta > 0
-      yield self
+      result = yield self
 
       while true
         @next_time += @min_dt
         break if @next_time > now
       end
+      
+      result
     end
     alias_method :process, :call
 
-    def stop
-      @stop = true
-    end
-
     private
 
+    # Converts the given argument to a rate. If a hash is given, the throttler's
+    # rate is computed from the value of either the `:interval` or `:rate` keys.
+    #
+    # @param arg [Number, Hash] rate argument
+    # @return [Number] rate in times per second
     def rate_from_argument(arg)
       return arg if arg.is_a?(Numeric)
 

data/lib/polyphony/core/timer.rb

@@ -1,17 +1,34 @@
 # frozen_string_literal: true
 
 module Polyphony
-  # Implements a common timer for running multiple timeouts
+
+  # Implements a common timer for running multiple timeouts. This class may be
+  # used to reduce the timer granularity in case a large number of timeouts is
+  # used concurrently. This class basically provides the same methods as global
+  # methods concerned with timeouts, such as `#cancel_after`, `#every` etc.
   class Timer
+
+    # Initializes a new timer with the given resolution.
+    #
+    # @param tag [any] tag to use for the timer's fiber
+    # @param resolution: [Number] timer granularity in seconds or fractions thereof
     def initialize(tag = nil, resolution:)
       @fiber = spin_loop(tag, interval: resolution) { update }
       @timeouts = {}
     end
 
+    # Stops the timer's associated fiber.
+    #
+    # @return [Polyphony::Timer] self
     def stop
       @fiber.stop
+      self
     end
 
+    # Sleeps for the given duration.
+    #
+    # @param duration [Number] sleep duration in seconds
+    # @return [void]
     def sleep(duration)
       fiber = Fiber.current
       @timeouts[fiber] = {
@@ -23,6 +40,12 @@ module Polyphony
       @timeouts.delete(fiber)
     end
 
+    # Spins up a fiber that will run the given block after sleeping for the
+    # given delay.
+    #
+    # @param delay [Number] delay in seconds before running the given block
+    # @param &block [Proc] block to run
+    # @return [Fiber] spun fiber
     def after(interval, &block)
       spin do
         self.sleep interval
@@ -30,6 +53,12 @@ module Polyphony
       end
     end
 
+    # Runs the given block in an infinite loop with a regular interval between
+    # consecutive iterations.
+    #
+    # @param interval [Number] interval between consecutive iterations in seconds
+    # @param &block [Proc] block to run
+    # @return [void]
     def every(interval)
       fiber = Fiber.current
       @timeouts[fiber] = {
@@ -45,6 +74,44 @@ module Polyphony
       @timeouts.delete(fiber)
     end
 
+    # call-seq:
+    #   timer.cancel_after(interval) { ... }
+    #   timer.cancel_after(interval, with_exception: exception) { ... }
+    #   timer.cancel_after(interval, with_exception: [klass, message]) { ... }
+    #   timer.cancel_after(interval) { |timeout| ... }
+    #   timer.cancel_after(interval, with_exception: exception) { |timeout| ... }
+    #   timer.cancel_after(interval, with_exception: [klass, message]) { |timeout| ... }
+    #
+    # Runs the given block after setting up a cancellation timer for
+    # cancellation. If the cancellation timer elapses, the execution will be
+    # interrupted with an exception defaulting to `Polyphony::Cancel`.
+    #
+    # This method should be used when a timeout should cause an exception to be
+    # propagated down the call stack or up the fiber tree.
+    #
+    # Example of normal use:
+    #
+    #   def read_from_io_with_timeout(io)
+    #     timer.cancel_after(10) { io.read }
+    #   rescue Polyphony::Cancel
+    #     nil
+    #   end
+    #
+    # The timeout period can be reset using `Timer#reset`, as shown in the
+    # following example:
+    #
+    #   timer.cancel_after(10) do
+    #     loop do
+    #       msg = socket.gets
+    #       timer.reset
+    #       handle_msg(msg)
+    #     end
+    #   end
+    #
+    # @param interval [Number] timout in seconds
+    # @param with_exception: [Class, Exception] exception or exception class
+    # @param &block [Proc] block to execute
+    # @return [any] block's return value
     def cancel_after(interval, with_exception: Polyphony::Cancel)
       fiber = Fiber.current
       @timeouts[fiber] = {
@@ -57,6 +124,48 @@ module Polyphony
       @timeouts.delete(fiber)
     end
 
+    # call-seq:
+    #   timer.move_on_after(interval) { ... }
+    #   timer.move_on_after(interval, with_value: value) { ... }
+    #   timer.move_on_after(interval) { |canceller| ... }
+    #   timer.move_on_after(interval, with_value: value) { |canceller| ... }
+    #
+    # Runs the given block after setting up a cancellation timer for
+    # cancellation. If the cancellation timer elapses, the execution will be
+    # interrupted with a `Polyphony::MoveOn` exception, which will be rescued,
+    # and with cause the operation to return the given value.
+    #
+    # This method should be used when a timeout is to be handled locally,
+    # without generating an exception that is to propagated down the call stack
+    # or up the fiber tree.
+    #
+    # Example of normal use:
+    #
+    #   timer.move_on_after(10) {
+    #     sleep 60
+    #     42
+    #   } #=> nil
+    #
+    #   timer.move_on_after(10, with_value: :oops) {
+    #     sleep 60
+    #     42
+    #   } #=> :oops
+    #
+    # The timeout period can be reset using `Timer#reset`, as shown in the
+    # following example:
+    #
+    #   timer.move_on_after(10) do
+    #     loop do
+    #       msg = socket.gets
+    #       timer.reset
+    #       handle_msg(msg)
+    #     end
+    #   end
+    #
+    # @param interval [Number] timout in seconds
+    # @param with_value: [any] return value in case of timeout
+    # @param &block [Proc] block to execute
+    # @return [any] block's return value
     def move_on_after(interval, with_value: nil)
       fiber = Fiber.current
       @timeouts[fiber] = {
@@ -71,6 +180,9 @@ module Polyphony
       @timeouts.delete(fiber)
     end
 
+    # Resets the timeout for the current fiber.
+    #
+    # @return [void]
     def reset
       record = @timeouts[Fiber.current]
       return unless record
@@ -80,21 +192,33 @@ module Polyphony
 
     private
 
+    # Returns the current monotonic clock value.
+    #
+    # @return [Number] monotonic clock value in seconds
     def now
       ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
     end
 
+    # Converts a timeout record's exception spec to an exception instance.
+    #
+    # @param record [Array, Class, Exception, String] exception spec
+    # @return [Exception] exception instance
     def timeout_exception(record)
       case (exception = record[:exception])
       when Array
         exception[0].new(exception[1])
       when Class
         exception.new
+      when Exception
+        exception
       else
         RuntimeError.new(exception)
       end
     end
 
+    # Runs a timer iteration, invoking any timeouts that are due.
+    #
+    # @return [void]      
     def update
       return if @timeouts.empty?
 

data/lib/polyphony/extensions/exception.rb

@@ -1,20 +1,38 @@
 # frozen_string_literal: true
 
-# Exeption overrides
+# Extensions to the Exception class
 class ::Exception
   class << self
+
+    # Set to true to disable sanitizing the backtrace (to remove frames occuring
+    # in the Polyphony code itself.)
     attr_accessor :__disable_sanitized_backtrace__
   end
 
-  attr_accessor :source_fiber, :raising_fiber
+  # Set to the fiber in which the exception was *originally* raised (in case the
+  # exception was not caught.) The exception will propagate up the fiber tree,
+  # allowing it to be caught in any of the fiber's ancestors, while the
+  # `@source_fiber`` attribute will continue pointing to the original fiber.
+  attr_accessor :source_fiber
+
+  # Set to the fiber from which the exception was raised.
+  attr_accessor :raising_fiber
 
   alias_method :orig_initialize, :initialize
+
+  # Initializes the exception with the given arguments.
   def initialize(*args)
     @raising_fiber = Fiber.current
     orig_initialize(*args)
   end
 
   alias_method :orig_backtrace, :backtrace
+
+  # Returns the backtrace for the exception. If
+  # `Exception.__disable_sanitized_backtrace__` is not true, any stack frames
+  # occuring in Polyphony's code will be removed from the backtrace.
+  #
+  # @return [Array<String>] backtrace
   def backtrace
     unless @backtrace_called
       @backtrace_called = true
@@ -24,6 +42,17 @@ class ::Exception
     sanitized_backtrace
   end
 
+  # Raises the exception. this method is a simple wrapper to `Kernel.raise`. It
+  # is overriden in the `Polyphony::Interjection` exception class.
+  def invoke
+    Kernel.raise(self)
+  end
+
+  private
+
+  # Returns a sanitized backtrace for the exception.
+  #
+  # @return [Array<String>] sanitized backtrace
   def sanitized_backtrace
     return sanitize(orig_backtrace) unless @raising_fiber
 
@@ -33,13 +62,14 @@ class ::Exception
 
   POLYPHONY_DIR = File.expand_path(File.join(__dir__, '..'))
 
+  # Sanitizes the backtrace by removing any frames occuring in Polyphony's code
+  # base.
+  #
+  # @param backtrace [Array<String>] unsanitized backtrace
+  # @return [Array<String>] sanitized backtrace
   def sanitize(backtrace)
     return backtrace if ::Exception.__disable_sanitized_backtrace__
 
     backtrace.reject { |l| l[POLYPHONY_DIR] }
   end
-
-  def invoke
-    Kernel.raise(self)
-  end
 end