polyphony 0.99.4 → 0.99.6

data/ext/polyphony/thread.c

@@ -19,11 +19,8 @@ inline void schedule_fiber(VALUE self, VALUE fiber, VALUE value, int prioritize)
   Backend_schedule_fiber(self, rb_ivar_get(self, ID_ivar_backend), fiber, value, prioritize);
 }
 
-/* call-seq:
- *   thread.unschedule_fiber(fiber)
+/* Removes the given fiber from the thread's runqueue.
  *
- * Removes the given fiber from the thread's runqueue.
- * 
  * @param fiber [Fiber] fiber to unschedule
  * @return [Thread] self
  */
@@ -45,12 +42,9 @@ inline void Thread_schedule_fiber_with_priority(VALUE self, VALUE fiber, VALUE v
   // schedule_fiber(self, fiber, value, 1);
 }
 
-/* call-seq:
- *   thread.switch_fiber()
+/* Switches to the next fiber in the thread's runqueue.
  *
- * Switches to the next fiber in the thread's runqueue.
- * 
- * @return [void]
+ * @return [any] resume value
  */
 
 VALUE Thread_switch_fiber(VALUE self) {
@@ -80,11 +74,8 @@ VALUE Thread_debug(VALUE self) {
   return self;
 }
 
-/* call-seq:
- *   Thread.backend
+/* Returns the backend for the current thread.
  *
- * Returns the backend for the current thread.
- * 
  * @return [Polyphony::Backend] backend for the current thread
  */
 

data/lib/polyphony/adapters/process.rb

@@ -8,13 +8,12 @@ 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]
+      # @return [true]
       def watch(cmd = nil, &block)
         terminated = nil
         pid = cmd ? Kernel.spawn(cmd) : Polyphony.fork(&block)
@@ -28,7 +27,6 @@ module Polyphony
       # seconds.
       #
       # @param pid [Integer] pid
-      # @return [void]
       def kill_process(pid)
         cancel_after(5) do
           kill_and_await('TERM', pid)
@@ -43,7 +41,6 @@ module Polyphony
       #
       # @param sig [String, Symbol, Integer] signal to use
       # @param pid [Integer] pid
-      # @return [void]
       def kill_and_await(sig, pid)
         ::Process.kill(sig, pid)
         Polyphony.backend_waitpid(pid)

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

@@ -1,8 +1,6 @@
 # Kernel extensions
 module ::Kernel
   # Prints a trace message to `STDOUT`, bypassing the Polyphony backend.
-  #
-  # @return [void]
   def trace(*args)
     STDOUT.orig_write(format_trace(args))
   end
@@ -32,8 +30,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
-      # @return [void]
+      # @yield [Hash] event information
       def start_event_firehose(io = nil, &block)
         Thread.backend.trace_proc = firehose_proc(io, block)
       end

data/lib/polyphony/core/exceptions.rb

@@ -16,7 +16,6 @@ module Polyphony
     # Initializes the exception, setting the caller and the value.
     #
     # @param value [any] Exception value
-    # @return [void]
     def initialize(value = nil)
       @caller_backtrace = caller
       @value = value
@@ -40,18 +39,15 @@ 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
-    # @return [void]
     def initialize(proc)
       @proc = proc
     end
 
     # Invokes the exception by calling the associated proc.
-    #
-    # @return [void]
     def invoke
       @proc.call
     end

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
@@ -28,7 +27,7 @@ module Polyphony
     # Conditionally releases the mutex. This method is used by condition
     # variables.
     #
-    # @return [void]
+    # @return [nil]
     def conditional_release
       @store << @token
       @token = nil
@@ -38,7 +37,7 @@ module Polyphony
     # Conditionally reacquires the mutex. This method is used by condition
     # variables.
     #
-    # @return [void]
+    # @return [Fiber] current fiber
     def conditional_reacquire
       @token = @store.shift
       @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
@@ -141,7 +140,7 @@ module Polyphony
     #
     # @param mutex [Polyphony::Mutex] mutex to release while waiting for signal
     # @param _timeout [Number, nil] timeout in seconds (currently not implemented)
-    # @return [void]
+    # @return [any]
     def wait(mutex, _timeout = nil)
       mutex.conditional_release
       @queue << Fiber.current
@@ -152,7 +151,7 @@ module Polyphony
     # Signals the condition variable, causing the first fiber in the waiting
     # queue to be resumed.
     #
-    # @return [void]
+    # @return [Fiber] resumed fiber
     def signal
       return if @queue.empty?
 
@@ -161,8 +160,6 @@ module Polyphony
     end
 
     # Resumes all waiting fibers.
-    #
-    # @return [void]
     def broadcast
       return if @queue.empty?
 

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
@@ -21,7 +20,7 @@ module Polyphony
 
     # Resets the default thread pool.
     #
-    # @return [void]
+    # @return [nil]
     def self.reset
       return unless @default_pool
 
@@ -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
@@ -81,8 +78,6 @@ module Polyphony
     private
 
     # Runs a processing loop on a worker thread.
-    #
-    # @return [void]
     def thread_loop
       while true
         run_queued_task
@@ -90,8 +85,6 @@ module Polyphony
     end
 
     # Runs the first queued task in the task queue.
-    #
-    # @return [void]
     def run_queued_task
       (block, watcher) = @task_queue.shift
       result = block.()

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

@@ -28,7 +28,6 @@ module Polyphony
     # Sleeps for the given duration.
     #
     # @param duration [Number] sleep duration in seconds
-    # @return [void]
     def sleep(duration)
       fiber = Fiber.current
       @timeouts[fiber] = {
@@ -44,7 +43,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,8 +55,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
       @timeouts[fiber] = {
@@ -74,14 +70,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 +96,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 +122,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 +154,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] = {
@@ -181,8 +178,6 @@ module Polyphony
     end
 
     # Resets the timeout for the current fiber.
-    #
-    # @return [void]
     def reset
       record = @timeouts[Fiber.current]
       return unless record
@@ -217,8 +212,6 @@ module Polyphony
     end
 
     # Runs a timer iteration, invoking any timeouts that are due.
-    #
-    # @return [void]      
     def update
       return if @timeouts.empty?