polyphony 0.79 → 0.81.1

data/lib/polyphony/core/resource_pool.rb

@@ -5,7 +5,8 @@ module Polyphony
   class ResourcePool
     attr_reader :limit, :size
 
-    # Initializes a new resource pool
+    # Initializes a new resource pool.
+    #
     # @param opts [Hash] options
     # @param &block [Proc] allocator block
     def initialize(opts, &block)
@@ -16,10 +17,27 @@ module Polyphony
       @acquired_resources = {}
     end
 
+    # Returns number of currently available resources.
+    #
+    # @return [Integer] size of resource stock
     def available
       @stock.size
     end
 
+    # Acquires a resource, passing it to the given block. If no resource is
+    # available, blocks until a resource becomes available. After the block has
+    # run, the resource is released back to the pool. The resource is passed to
+    # the block as its only argument.
+    #
+    # This method is re-entrant: if called from the same fiber, it will immediately
+    # return the resource currently acquired by the fiber.
+    #
+    #   rows = db_pool.acquire do |db|
+    #     db.query(sql).to_a
+    #   end
+    #
+    # @param &block [Proc] code to run
+    # @return [any] return value of block
     def acquire(&block)
       fiber = Fiber.current
       return yield @acquired_resources[fiber] if @acquired_resources[fiber]
@@ -27,6 +45,50 @@ module Polyphony
       acquire_from_stock(fiber, &block)
     end
 
+    # Acquires a resource, proxies the method calls to the resource, then
+    # releases it. Methods can also be called with blocks, as in the following
+    # example:
+    #
+    #   db_pool.query(sql) { |result|
+    #     process_result_rows(result)
+    #   }
+    #
+    # @param sym [Symbol] method name
+    # @param *args [Array<any>] method arguments
+    # @param &block [Proc] block passed to method
+    def method_missing(sym, *args, &block)
+      acquire { |r| r.send(sym, *args, &block) }
+    end
+
+    # :no-doc:
+    def respond_to_missing?(*_args)
+      true
+    end
+
+    # Discards the currently-acquired resource
+    # instead of returning it to the pool when done.
+    #
+    # @return [Polyphony::ResourcePool] self
+    def discard!
+      @size -= 1 if @acquired_resources.delete(Fiber.current)
+      self
+    end
+
+    # Fills the pool to capacity.
+    #
+    # @return [Polyphony::ResourcePool] self
+    def fill!
+      add_to_stock while @size < @limit
+      self
+    end
+
+    private
+
+    # Acquires a resource from stock, yielding it to the given block.
+    #
+    # @param fiber [Fiber] the fiber the resource will be associated with
+    # @param &block [Proc] given block
+    # @return [any] return value of block
     def acquire_from_stock(fiber)
       add_to_stock if (@stock.empty? || @stock.pending?) && @size < @limit
       resource = @stock.shift
@@ -39,30 +101,13 @@ module Polyphony
       end
     end
 
-    def method_missing(sym, *args, &block)
-      acquire { |r| r.send(sym, *args, &block) }
-    end
-
-    def respond_to_missing?(*_args)
-      true
-    end
-
-    # Allocates a resource
+    # Creates a resource, adding it to the stock.
+    #
     # @return [any] allocated resource
     def add_to_stock
       @size += 1
       resource = @allocator.call
       @stock << resource
     end
-
-    # Discards the currently-acquired resource
-    # instead of returning it to the pool when done.
-    def discard!
-      @size -= 1 if @acquired_resources.delete(Fiber.current)
-    end
-
-    def preheat!
-      add_to_stock while @size < @limit
-    end
   end
 end

data/lib/polyphony/core/sync.rb

@@ -1,56 +1,94 @@
 # frozen_string_literal: true
 
 module Polyphony
-  # Implements mutex lock for synchronizing access to a shared resource
+
+  # Implements mutex lock for synchronizing access to a shared resource. This
+  # class replaces the stock `Thread::Mutex` class.
   class Mutex
+
+    # Initializes a new mutex.
     def initialize
       @store = Queue.new
       @store << :token
     end
 
+    # Locks the mutex, runs the block, then unlocks it.
+    #
+    # This method is re-entrant. Recursive calls from the given block will not
+    # block.
+    #
+    # @param &block [Proc] code to run
+    # @return [any] return value of block
     def synchronize(&block)
       return yield if @holding_fiber == Fiber.current
 
       synchronize_not_holding(&block)
     end
 
-    def synchronize_not_holding
-      @token = @store.shift
-      begin
-        @holding_fiber = Fiber.current
-        yield
-      ensure
-        @holding_fiber = nil
-        @store << @token if @token
-      end
-    end
-
+    # Conditionally releases the mutex. This method is used by condition
+    # variables.
+    #
+    # @return [void]
     def conditional_release
       @store << @token
       @token = nil
       @holding_fiber = nil
     end
 
+    # Conditionally reacquires the mutex. This method is used by condition
+    # variables.
+    #
+    # @return [void]
     def conditional_reacquire
       @token = @store.shift
       @holding_fiber = Fiber.current
     end
 
+    # Returns the fiber currently owning the mutex.
+    #
+    # @return [Fiber, nil] current owner or nil
     def owned?
       @holding_fiber == Fiber.current
     end
 
+    # Returns a truthy value if the mutex is currently locked.
+    #
+    # @return [any] truthy if fiber is currently locked
     def locked?
       @holding_fiber
     end
+
+    private
+
+    # Helper method for performing a `#synchronize` when not currently holding
+    # the mutex.
+    #
+    # @return [any] return value of given block.
+    def synchronize_not_holding
+      @token = @store.shift
+      begin
+        @holding_fiber = Fiber.current
+        yield
+      ensure
+        @holding_fiber = nil
+        @store << @token if @token
+      end
+    end
   end
 
   # Implements a fiber-aware ConditionVariable
   class ConditionVariable
+
+    # Initializes the condition variable.
     def initialize
       @queue = Polyphony::Queue.new
     end
 
+    # Waits for the condition variable to be signalled.
+    #
+    # @param mutex [Polyphony::Mutex] mutex to release while waiting for signal
+    # @param timeout [Number, nil] timeout in seconds (currently not implemented)
+    # @return [void]
     def wait(mutex, _timeout = nil)
       mutex.conditional_release
       @queue << Fiber.current
@@ -58,11 +96,18 @@ module Polyphony
       mutex.conditional_reacquire
     end
 
+    # Signals the condition variable, causing the first fiber in the waiting
+    # queue to be resumed.
+    #
+    # @return [void]
     def signal
       fiber = @queue.shift
       fiber.schedule
     end
 
+    # Resumes all waiting fibers.
+    #
+    # @return [void]
     def broadcast
       while (fiber = @queue.shift)
         fiber.schedule

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