polyphony 0.79 → 0.80

data/lib/polyphony/core/global_api.rb

@@ -3,8 +3,16 @@
 require_relative './throttler'
 
 module Polyphony
-  # Global API methods to be included in ::Object
+  
+  # Global API methods to be included in `::Object`
   module GlobalAPI
+
+    # 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
         sleep interval
@@ -12,64 +20,88 @@ module Polyphony
       end
     end
 
+    # call-seq:
+    #   cancel_after(interval) { ... }
+    #   cancel_after(interval, with_exception: exception) { ... }
+    #   cancel_after(interval, with_exception: [klass, message]) { ... }
+    #   cancel_after(interval) { |timeout| ... }
+    #   cancel_after(interval, with_exception: exception) { |timeout| ... }
+    #   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)
+    #     cancel_after(10) { io.read }
+    #   rescue Polyphony::Cancel
+    #     nil
+    #   end
+    #
+    # The timeout period can be reset by passing a block that takes a single
+    # argument. The block will be provided with the canceller fiber. To reset
+    # the timeout, use `Fiber#reset`, as shown in the following example:
+    #
+    #   cancel_after(10) do |timeout|
+    #     loop do
+    #       msg = socket.gets
+    #       timeout.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, &block)
-      if !block
-        cancel_after_blockless_canceller(Fiber.current, interval, with_exception)
-      elsif block.arity > 0
-        cancel_after_with_block(Fiber.current, interval, with_exception, &block)
+      if block.arity > 0
+        cancel_after_with_optional_reset(interval, with_exception, &block)
       else
         Polyphony.backend_timeout(interval, with_exception, &block)
       end
     end
 
-    def cancel_after_blockless_canceller(fiber, interval, with_exception)
-      spin do
-        sleep interval
-        exception = cancel_exception(with_exception)
-        exception.raising_fiber = nil
-        fiber.schedule exception
-      end
-    end
-
-    def cancel_after_with_block(fiber, interval, with_exception, &block)
-      canceller = cancel_after_blockless_canceller(fiber, interval, with_exception)
-      block.call(canceller)
-    ensure
-      canceller.stop
-    end
-
-    def cancel_exception(exception)
-      case exception
-      when Class then exception.new
-      when Array then exception[0].new(exception[1])
-      else RuntimeError.new(exception)
-      end
-    end
-
+    # Spins up a new fiber.
+    #
+    # @param tag [any] optional tag for the new fiber
+    # @param &block [Proc] fiber block
+    # @return [Fiber] new fiber
     def spin(tag = nil, &block)
       Fiber.current.spin(tag, caller, &block)
     end
 
+    # Spins up a new fiber, running the given block inside an infinite loop. If
+    # `rate:` or `interval:` parameters are given, the loop is throttled
+    # accordingly.
+    #
+    # @param tag [any] optional tag for the new fiber
+    # @param rate: [Number, nil] loop rate (times per second)
+    # @param interval: [Number, nil] interval between consecutive iterations in seconds
+    # @param &block [Proc] code to run
+    # @return [Fiber] new fiber
     def spin_loop(tag = nil, rate: nil, interval: nil, &block)
       if rate || interval
         Fiber.current.spin(tag, caller) do
           throttled_loop(rate: rate, interval: interval, &block)
         end
       else
-        spin_looped_block(tag, caller, block)
-      end
-    end
-
-    def spin_looped_block(tag, caller, block)
-      Fiber.current.spin(tag, caller) do
-        block.call while true
-      rescue LocalJumpError, StopIteration
-        # break called or StopIteration raised
+        spin_loop_without_throttling(tag, caller, block)
       end
     end
 
-    def spin_scope
-      raise unless block_given?
+    # Runs the given code, then waits for any child fibers of the current fibers
+    # to terminate.
+    #
+    # @param &block [Proc] code to run
+    # @return [any] given block's return value
+    def spin_scope(&block)
+      raise unless block
 
       spin do
         result = yield
@@ -78,61 +110,121 @@ module Polyphony
       end.await
     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, &block)
       Polyphony.backend_timer_loop(interval, &block)
     end
 
+    # call-seq:
+    #   move_on_after(interval) { ... }
+    #   move_on_after(interval, with_value: value) { ... }
+    #   move_on_after(interval) { |canceller| ... }
+    #   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:
+    #
+    #   move_on_after(10) {
+    #     sleep 60
+    #     42
+    #   } #=> nil
+    #
+    #   move_on_after(10, with_value: :oops) {
+    #     sleep 60
+    #     42
+    #   } #=> :oops
+    #
+    # The timeout period can be reset by passing a block that takes a single
+    # argument. The block will be provided with the canceller fiber. To reset
+    # the timeout, use `Fiber#reset`, as shown in the following example:
+    #
+    #   move_on_after(10) do |timeout|
+    #     loop do
+    #       msg = socket.gets
+    #       timeout.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, &block)
-      if !block
-        move_on_blockless_canceller(Fiber.current, interval, with_value)
-      elsif block.arity > 0
-        move_on_after_with_block(Fiber.current, interval, with_value, &block)
+      if block.arity > 0
+        move_on_after_with_optional_reset(interval, with_value, &block)
       else
         Polyphony.backend_timeout(interval, nil, with_value, &block)
       end
     end
 
-    def move_on_blockless_canceller(fiber, interval, with_value)
-      spin do
-        sleep interval
-        fiber.schedule with_value
-      end
-    end
-
-    def move_on_after_with_block(fiber, interval, with_value, &block)
-      canceller = spin do
-        sleep interval
-        fiber.schedule Polyphony::MoveOn.new(with_value)
-      end
-      block.call(canceller)
-    rescue Polyphony::MoveOn => e
-      e.value
-    ensure
-      canceller.stop
-    end
-
+    # Returns the first message from the current fiber's mailbox. If the mailbox
+    # is empty, blocks until a message is available.
+    #
+    # @return [any] received message
     def receive
       Fiber.current.receive
     end
 
+    # Returns all messages currently pending on the current fiber's mailbox.
+    #
+    # @return [Array] array of received messages
     def receive_all_pending
       Fiber.current.receive_all_pending
     end
 
+    # Supervises the current fiber's children. See `Fiber#supervise` for
+    # options.
+    #
+    # @param *args [Array] positional parameters
+    # @param **opts [Hash] named parameters
+    # @param &block [Proc] given block
+    # @return [void]
     def supervise(*args, **opts, &block)
       Fiber.current.supervise(*args, **opts, &block)
     end
 
+    # Sleeps for the given duration. If the duration is `nil`, sleeps
+    # indefinitely.
+    #
+    # @param duration [Number, nil] duration
+    # @return [void]
     def sleep(duration = nil)
-      return sleep_forever unless duration
-
-      Polyphony.backend_sleep duration
-    end
-
-    def sleep_forever
-      Polyphony.backend_wait_event(true)
+      duration ?
+        Polyphony.backend_sleep(duration) : Polyphony.backend_wait_event(true)
     end
 
+    # call-seq:
+    #   throttled_loop(rate) { ... }
+    #   throttled_loop(interval: value) { ... }
+    #   throttled_loop(rate: value) { ... }
+    #   throttled_loop(rate, count: value) { ... }
+    #
+    # Starts a throttled loop with the given rate. If `count:` is given, the
+    # loop is run for the given number of times. Otherwise, the loop is
+    # infinite. The loop rate (times per second) can be given as the rate
+    # parameter. The throttling can also be controlled by providing an
+    # `interval:` or `rate:` named parameter.
+    #
+    # @param rate [Number, nil] loop rate (times per second)
+    # @param rate: [Number] loop rate (times per second)
+    # @param interval: [Number] loop interval in seconds
+    # @param count: [Number, nil] number of iterations (nil for infinite)
+    # @param &block [Proc] code to run
+    # @return [void]
     def throttled_loop(rate = nil, **opts, &block)
       throttler = Polyphony::Throttler.new(rate || opts)
       if opts[:count]
@@ -144,10 +236,73 @@ module Polyphony
       end
     rescue LocalJumpError, StopIteration
       # break called or StopIteration raised
+    end
+
+    private
+
+    # Helper method for performing a `cancel_after` with optional reset.
+    #
+    # @param interval [Number] timeout interval in seconds
+    # @param exception [Exception, Class, Array<class, message>] exception spec
+    # @param &block [Proc] block to run
+    # @return [any] block's return value
+    def cancel_after_with_optional_reset(interval, exception, &block)
+      canceller = spin do
+        sleep interval
+        exception = cancel_exception(exception)
+        exception.raising_fiber = Fiber.current
+        fiber.cancel(exception).await
+      end
+      block.call(canceller)
     ensure
-      throttler&.stop
+      canceller.stop
+    end
+
+    # Converts the given exception spec to an exception instance.
+    #
+    # @param exception [Exception, Class, Array<class, message>] exception spec
+    # @return [Exception] exception instance
+    def cancel_exception(exception)
+      case exception
+      when Class then exception.new
+      when Array then exception[0].new(exception[1])
+      else RuntimeError.new(exception)
+      end
     end
+
+    # Helper method for performing `#spin_loop` without throttling. Spins up a
+    # new fiber in which to run the loop.
+    #
+    # @param tag [any] new fiber's tag
+    # @param caller [Array<String>] caller info
+    # @param block [Proc] code to run
+    # @return [void]
+    def spin_loop_without_throttling(tag, caller, block)
+      Fiber.current.spin(tag, caller) do
+        block.call while true
+      rescue LocalJumpError, StopIteration
+        # break called or StopIteration raised
+      end
+    end
+
+    # Helper method for performing `#move_on_after` with optional reset.
+    #
+    # @param interval [Number] timeout interval in seconds
+    # @param value [any] return value in case of timeout
+    # @param &block [Proc] code to run
+    # @return [any] return value of given block or timeout value
+    def move_on_after_with_optional_reset(interval, value, &block)
+      fiber = Fiber.current
+      canceller = spin do
+        sleep interval
+        fiber.move_on(value).await
+      end
+      block.call(canceller)
+    rescue Polyphony::MoveOn => e
+      e.value
+    ensure
+      canceller.stop
+    end
+
   end
 end
-
-Object.include Polyphony::GlobalAPI

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