polyphony 0.99.4 → 0.99.5

data/lib/polyphony/adapters/process.rb

@@ -8,12 +8,11 @@ module Polyphony
       # Watches a forked or spawned process, waiting for it to terminate. If
       # `cmd` is given it is spawned, otherwise the process is forked with the
       # given block.
-      # 
+      #
       # If the operation is interrupted for any reason, the spawned or forked
       # process is killed.
       #
       # @param cmd [String, nil] command to spawn
-      # @yield [] block to fork
       # @return [void]
       def watch(cmd = nil, &block)
         terminated = nil

data/lib/polyphony/adapters/sequel.rb

@@ -4,10 +4,10 @@ require_relative '../../polyphony'
 require 'sequel'
 
 module Polyphony
-  
+
   # Sequel ConnectionPool that delegates to Polyphony::ResourcePool.
   class FiberConnectionPool < Sequel::ConnectionPool
-  
+
     # Initializes the connection pool.
     #
     # @param db [any] db to connect to

data/lib/polyphony/core/debug.rb

@@ -32,7 +32,7 @@ module Polyphony
       # If an IO instance is given, events are dumped to it instead.
       #
       # @param io [IO, nil] IO instance
-      # @yield [Hash] event handler block
+      # @yield [Hash] event information
       # @return [void]
       def start_event_firehose(io = nil, &block)
         Thread.backend.trace_proc = firehose_proc(io, block)

data/lib/polyphony/core/exceptions.rb

@@ -40,7 +40,7 @@ module Polyphony
 
   # Interjection is used to run arbitrary code on arbitrary fibers at any point
   class Interjection < BaseException
-    
+
     # Initializes an Interjection with the given proc.
     #
     # @param proc [Proc] interjection proc

data/lib/polyphony/core/global_api.rb

@@ -3,7 +3,7 @@
 require_relative './throttler'
 
 module Polyphony
-  
+
   # Global API methods to be included in `::Object`
   module GlobalAPI
 
@@ -11,7 +11,6 @@ module Polyphony
     # given delay.
     #
     # @param interval [Number] delay in seconds before running the given block
-    # @yield [] block to run
     # @return [Fiber] spun fiber
     def after(interval, &block)
       spin do
@@ -20,14 +19,6 @@ 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`.
@@ -55,10 +46,20 @@ module Polyphony
     #     end
     #   end
     #
-    # @param interval [Number] timout in seconds
-    # @param with_exception [Class, Exception] exception or exception class
-    # @yield [Fiber] block to execute
-    # @return [any] block's return value
+    # @overload cancel_after(interval)
+    #   @param interval [Number] timout in seconds
+    #   @yield [Fiber] timeout fiber
+    #   @return [any] block's return value
+    # @overload cancel_after(interval, with_exception: exception)
+    #   @param interval [Number] timout in seconds
+    #   @param with_exception [Class, Exception] exception or exception class
+    #   @yield [Fiber] timeout fiber
+    #   @return [any] block's return value
+    # @overload cancel_after(interval, with_exception: [klass, message])
+    #   @param interval [Number] timout in seconds
+    #   @param with_exception [Array] array containing class and message to use as exception
+    #   @yield [Fiber] timeout fiber
+    #   @return [any] block's return value
     def cancel_after(interval, with_exception: Polyphony::Cancel, &block)
       if block.arity > 0
         cancel_after_with_optional_reset(interval, with_exception, &block)
@@ -70,7 +71,6 @@ module Polyphony
     # Spins up a new fiber.
     #
     # @param tag [any] optional tag for the new fiber
-    # @yield [any] fiber block
     # @return [Fiber] new fiber
     def spin(tag = nil, &block)
       Fiber.current.spin(tag, caller, &block)
@@ -83,7 +83,6 @@ module Polyphony
     # @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
-    # @yield [any] code to run
     # @return [Fiber] new fiber
     def spin_loop(tag = nil, rate: nil, interval: nil, &block)
       if rate || interval
@@ -98,7 +97,6 @@ module Polyphony
     # Runs the given code, then waits for any child fibers of the current fibers
     # to terminate.
     #
-    # @yield [any] code to run
     # @return [any] given block's return value
     def spin_scope(&block)
       raise unless block
@@ -114,18 +112,11 @@ module Polyphony
     # consecutive iterations.
     #
     # @param interval [Number] interval between consecutive iterations in seconds
-    # @yield [any] 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,
@@ -159,10 +150,15 @@ module Polyphony
     #     end
     #   end
     #
-    # @param interval [Number] timout in seconds
-    # @param with_value [any] return value in case of timeout
-    # @yield [Fiber] block to execute
-    # @return [any] block's return value
+    # @overload move_on_after(interval) { ... }
+    #   @param interval [Number] timout in seconds
+    #   @yield [Fiber] timeout fiber
+    #   @return [any] block's return value
+    # @overload move_on_after(interval, with_value: value) { ... }
+    #   @param interval [Number] timout in seconds
+    #   @param with_value [any] return value in case of timeout
+    #   @yield [Fiber] timeout fiber
+    #   @return [any] block's return value
     def move_on_after(interval, with_value: nil, &block)
       if block.arity > 0
         move_on_after_with_optional_reset(interval, with_value, &block)
@@ -191,7 +187,6 @@ module Polyphony
     #
     # @param args [Array] positional parameters
     # @param opts [Hash] named parameters
-    # @yield [any] given block
     # @return [void]
     def supervise(*args, **opts, &block)
       Fiber.current.supervise(*args, **opts, &block)
@@ -207,12 +202,6 @@ module Polyphony
         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
@@ -223,7 +212,6 @@ module Polyphony
     # @option opts [Number] :rate loop rate (times per second)
     # @option opts [Number] :interval loop interval in seconds
     # @option opts [Number] :count number of iterations (nil for infinite)
-    # @yield [] code to run
     # @return [void]
     def throttled_loop(rate = nil, **opts, &block)
       throttler = Polyphony::Throttler.new(rate || opts)
@@ -244,7 +232,6 @@ module Polyphony
     #
     # @param interval [Number] timeout interval in seconds
     # @param exception [Exception, Class, Array<class, message>] exception spec
-    # @yield [Fiber] block to run
     # @return [any] block's return value
     def cancel_after_with_optional_reset(interval, exception, &block)
       fiber = Fiber.current
@@ -290,7 +277,6 @@ module Polyphony
     #
     # @param interval [Number] timeout interval in seconds
     # @param value [any] return value in case of timeout
-    # @yield [Fiber] 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

data/lib/polyphony/core/resource_pool.rb

@@ -5,13 +5,15 @@ module Polyphony
   class ResourcePool
     attr_reader :limit, :size
 
-    # Initializes a new resource pool.
+    # Initializes a new resource pool. The given block is used for creating a
+    # resource:
     #
-    # @param opts [Hash] options
-    # @yield [] allocator block
-    def initialize(opts, &block)
+    #   ResourcePool.new { Sequel.connect(DB_URL) }
+    #
+    # @param limit [Integer] maximum open resources
+    def initialize(limit: 4, &block)
       @allocator = block
-      @limit = opts[:limit] || 4
+      @limit = limit
       @size = 0
       @stock = Polyphony::Queue.new
       @acquired_resources = {}
@@ -36,7 +38,6 @@ module Polyphony
     #     db.query(sql).to_a
     #   end
     #
-    # @yield [any] code to run
     # @return [any] return value of block
     def acquire(&block)
       fiber = Fiber.current
@@ -55,7 +56,6 @@ module Polyphony
     #
     # @param sym [Symbol] method name
     # @param args [Array<any>] method arguments
-    # @yield [any] block passed to method
     # @return [any] result of method call
     def method_missing(sym, *args, &block)
       acquire { |r| r.send(sym, *args, &block) }
@@ -88,7 +88,6 @@ module Polyphony
     # Acquires a resource from stock, yielding it to the given block.
     #
     # @param fiber [Fiber] the fiber the resource will be associated with
-    # @yield [any] given block
     # @return [any] return value of block
     def acquire_from_stock(fiber)
       add_to_stock if (@stock.empty? || @stock.pending?) && @size < @limit

data/lib/polyphony/core/sync.rb

@@ -17,7 +17,6 @@ module Polyphony
     # This method is re-entrant. Recursive calls from the given block will not
     # block.
     #
-    # @yield [] code to run
     # @return [any] return value of block
     def synchronize(&block)
       return yield if @holding_fiber == Fiber.current
@@ -64,7 +63,7 @@ module Polyphony
     # @return [Mutex] self
     def lock
       raise ThreadError if owned?
-      
+
       @token = @store.shift
       @holding_fiber = Fiber.current
       self

data/lib/polyphony/core/thread_pool.rb

@@ -3,16 +3,15 @@
 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.
     #
-    # @yield [] given block
     # @return [any] return value of given block
     def self.process(&block)
       @default_pool ||= new
@@ -41,7 +40,6 @@ module Polyphony
 
     # Runs the given block on an available thread from the pool.
     #
-    # @yield [] given block
     # @return [any] return value of block
     def process(&block)
       setup unless @task_queue
@@ -55,7 +53,6 @@ module Polyphony
     # method does not block. The task will be performed once a thread becomes
     # available.
     #
-    # @yield [] given block
     # @return [Polyphony::ThreadPool] self
     def cast(&block)
       setup unless @task_queue

data/lib/polyphony/core/throttler.rb

@@ -13,10 +13,6 @@ module Polyphony
       @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.
@@ -32,7 +28,7 @@ module Polyphony
         @next_time += @min_dt
         break if @next_time > now
       end
-      
+
       result
     end
     alias_method :process, :call

data/lib/polyphony/core/timer.rb

@@ -44,7 +44,6 @@ module Polyphony
     # given delay.
     #
     # @param interval [Number] delay in seconds before running the given block
-    # @yield [] block to run
     # @return [Fiber] spun fiber
     def after(interval, &block)
       spin do
@@ -57,7 +56,6 @@ module Polyphony
     # consecutive iterations.
     #
     # @param interval [Number] interval between consecutive iterations in seconds
-    # @yield [] block to run
     # @return [void]
     def every(interval)
       fiber = Fiber.current
@@ -74,14 +72,6 @@ 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`.
@@ -108,10 +98,20 @@ module Polyphony
     #     end
     #   end
     #
-    # @param interval [Number] timout in seconds
-    # @param with_exception [Class, Exception] exception or exception class
-    # @yield [Canceller] block to execute
-    # @return [any] block's return value
+    # @overload cancel_after(interval)
+    #   @param interval [Number] timout in seconds
+    #   @yield [Fiber] timeout fiber
+    #   @return [any] block's return value
+    # @overload cancel_after(interval, with_exception: exception)
+    #   @param interval [Number] timout in seconds
+    #   @param with_exception [Class, Exception] exception or exception class
+    #   @yield [Fiber] timeout fiber
+    #   @return [any] block's return value
+    # @overload cancel_after(interval, with_exception: [klass, message])
+    #   @param interval [Number] timout in seconds
+    #   @param with_exception [Array] array containing class and message to use as exception
+    #   @yield [Fiber] timeout fiber
+    #   @return [any] block's return value
     def cancel_after(interval, with_exception: Polyphony::Cancel)
       fiber = Fiber.current
       @timeouts[fiber] = {
@@ -124,12 +124,6 @@ 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,
@@ -162,10 +156,15 @@ module Polyphony
     #     end
     #   end
     #
-    # @param interval [Number] timout in seconds
-    # @param with_value [any] return value in case of timeout
-    # @yield [Fiber] block to execute
-    # @return [any] block's return value
+    # @overload move_on_after(interval) { ... }
+    #   @param interval [Number] timout in seconds
+    #   @yield [Fiber] timeout fiber
+    #   @return [any] block's return value
+    # @overload move_on_after(interval, with_value: value) { ... }
+    #   @param interval [Number] timout in seconds
+    #   @param with_value [any] return value in case of timeout
+    #   @yield [Fiber] timeout fiber
+    #   @return [any] block's return value
     def move_on_after(interval, with_value: nil)
       fiber = Fiber.current
       @timeouts[fiber] = {
@@ -218,7 +217,7 @@ module Polyphony
 
     # Runs a timer iteration, invoking any timeouts that are due.
     #
-    # @return [void]      
+    # @return [void]
     def update
       return if @timeouts.empty?