polyphony 0.99 → 0.99.1

data/lib/polyphony/core/resource_pool.rb

@@ -8,7 +8,7 @@ module Polyphony
     # Initializes a new resource pool.
     #
     # @param opts [Hash] options
-    # @param &block [Proc] allocator block
+    # @yield [] allocator block
     def initialize(opts, &block)
       @allocator = block
       @limit = opts[:limit] || 4
@@ -36,7 +36,7 @@ module Polyphony
     #     db.query(sql).to_a
     #   end
     #
-    # @param &block [Proc] code to run
+    # @yield [any] code to run
     # @return [any] return value of block
     def acquire(&block)
       fiber = Fiber.current
@@ -54,13 +54,14 @@ module Polyphony
     #   }
     #
     # @param sym [Symbol] method name
-    # @param *args [Array<any>] method arguments
-    # @param &block [Proc] block passed to method
+    # @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) }
     end
 
-    # :no-doc:
+    # @!visibility private
     def respond_to_missing?(*_args)
       true
     end
@@ -87,7 +88,7 @@ module Polyphony
     # 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
+    # @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,7 @@ module Polyphony
     # This method is re-entrant. Recursive calls from the given block will not
     # block.
     #
-    # @param &block [Proc] code to run
+    # @yield [] code to run
     # @return [any] return value of block
     def synchronize(&block)
       return yield if @holding_fiber == Fiber.current
@@ -140,7 +140,7 @@ module Polyphony
     # 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)
+    # @param _timeout [Number, nil] timeout in seconds (currently not implemented)
     # @return [void]
     def wait(mutex, _timeout = nil)
       mutex.conditional_release

data/lib/polyphony/core/thread_pool.rb

@@ -12,7 +12,7 @@ module Polyphony
 
     # Runs the given block on an available thread from the default thread pool.
     #
-    # @param &block [Proc] given block
+    # @yield [] given block
     # @return [any] return value of given block
     def self.process(&block)
       @default_pool ||= new
@@ -41,7 +41,7 @@ module Polyphony
 
     # Runs the given block on an available thread from the pool.
     #
-    # @param &block [Proc] given block
+    # @yield [] given block
     # @return [any] return value of block
     def process(&block)
       setup unless @task_queue
@@ -55,7 +55,7 @@ module Polyphony
     # method does not block. The task will be performed once a thread becomes
     # available.
     #
-    # @param &block [Proc] given block
+    # @yield [] given block
     # @return [Polyphony::ThreadPool] self
     def cast(&block)
       setup unless @task_queue

data/lib/polyphony/core/timer.rb

@@ -11,7 +11,7 @@ module Polyphony
     # 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
+    # @param resolution [Number] timer granularity in seconds or fractions thereof
     def initialize(tag = nil, resolution:)
       @fiber = spin_loop(tag, interval: resolution) { update }
       @timeouts = {}
@@ -43,8 +43,8 @@ module Polyphony
     # 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
+    # @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 +57,7 @@ module Polyphony
     # consecutive iterations.
     #
     # @param interval [Number] interval between consecutive iterations in seconds
-    # @param &block [Proc] block to run
+    # @yield [] block to run
     # @return [void]
     def every(interval)
       fiber = Fiber.current
@@ -109,8 +109,8 @@ module Polyphony
     #   end
     #
     # @param interval [Number] timout in seconds
-    # @param with_exception: [Class, Exception] exception or exception class
-    # @param &block [Proc] block to execute
+    # @param with_exception [Class, Exception] exception or exception class
+    # @yield [Canceller] block to execute
     # @return [any] block's return value
     def cancel_after(interval, with_exception: Polyphony::Cancel)
       fiber = Fiber.current
@@ -163,8 +163,8 @@ module Polyphony
     #   end
     #
     # @param interval [Number] timout in seconds
-    # @param with_value: [any] return value in case of timeout
-    # @param &block [Proc] block to execute
+    # @param with_value [any] return value in case of timeout
+    # @yield [Fiber] block to execute
     # @return [any] block's return value
     def move_on_after(interval, with_value: nil)
       fiber = Fiber.current

data/lib/polyphony/extensions/exception.rb

@@ -18,6 +18,7 @@ class ::Exception
   # Set to the fiber from which the exception was raised.
   attr_accessor :raising_fiber
 
+  # @!visibility private
   alias_method :orig_initialize, :initialize
 
   # Initializes the exception with the given arguments.
@@ -26,6 +27,7 @@ class ::Exception
     orig_initialize(*args)
   end
 
+  # @!visibility private
   alias_method :orig_backtrace, :backtrace
 
   # Returns the backtrace for the exception. If

data/lib/polyphony/extensions/fiber.rb

@@ -116,7 +116,7 @@ module Polyphony
     # operation will be resumed. This API is experimental and might be removed
     # in the future.
     #
-    # @param &block [Proc] given block
+    # @yield [any] given block
     # @return [Fiber] self
     def interject(&block)
       raise Polyphony::Interjection.new(block)
@@ -132,7 +132,7 @@ module Polyphony
 
     private
 
-    # :no-doc:
+    # @!visibility private
     def error_from_raise_args(args)
       case (arg = args.shift)
       when String then RuntimeError.new(arg)
@@ -171,10 +171,11 @@ module Polyphony
     #
     # This method blocks indefinitely.
     #
-    # @param *fibers [Array<Fiber>] fibers to supervise
-    # @param on_done: [Proc, nil] proc to call when a supervised fiber is terminated
-    # @param on_error: [Proc, nil] proc to call when a supervised fiber is terminated with an exception
-    # @param restart: [:always, :on_error, nil] whether to restart terminated fibers
+    # @param fibers [Array<Fiber>] fibers to supervise
+    # @option opts [Proc, nil] :on_done proc to call when a supervised fiber is terminated
+    # @option opts [Proc, nil] :on_error proc to call when a supervised fiber is terminated with an exception
+    # @option opts [:always, :on_error, nil] :restart whether to restart terminated fibers
+    # @yield [] supervisor block
     # @return [void]
     def supervise(*fibers, **opts, &block)
       block ||= supervise_opts_to_block(opts)
@@ -198,7 +199,7 @@ module Polyphony
 
     private
 
-    # :no-doc:
+    # @!visibility private
     def supervise_opts_to_block(opts)
       block = opts[:on_done] || opts[:on_error]
       restart = opts[:restart]
@@ -228,7 +229,7 @@ module Polyphony
     # terminates with an uncaught exception, `Fiber.await` will await all the
     # other fibers to terminate, then reraise the exception.
     #
-    # @param *fibers [Array<Fiber>] fibers to wait for
+    # @param fibers [Array<Fiber>] fibers to wait for
     # @return [Array<any>] return values of given fibers
     def await(*fibers)
       return [] if fibers.empty?
@@ -267,7 +268,7 @@ module Polyphony
     # array containing the first terminated fiber and its return value. If an
     # exception occurs in one of the given fibers, it will be reraised.
     #
-    # @param *fibers [Array<Fiber>] Fibers to wait for
+    # @param fibers [Array<Fiber>] Fibers to wait for
     # @return [Array] Array containing the first terminated fiber and its return value
     def select(*fibers)
       return nil if fibers.empty?
@@ -301,7 +302,7 @@ module Polyphony
     # also be scheduled with priority. This method is mainly used trapping
     # signals (see also the patched `Kernel#trap`)
     #
-    # @param &block [Proc] given block
+    # @yield [] given block
     # @return [void]
     def schedule_priority_oob_fiber(&block)
       oob_fiber = Fiber.new do
@@ -322,7 +323,7 @@ module Polyphony
 
     private
 
-    # :no-doc:
+    # @!visibility private
     def prepare_oob_fiber(fiber, block)
       fiber.oob = true
       fiber.tag = :oob
@@ -348,7 +349,7 @@ module Polyphony
     #
     # @param tag [any] child fiber's tag
     # @param orig_caller [Array<String>] caller to set for fiber
-    # @param &block [Proc] child fiber's block
+    # @yield [any] child fiber's block
     # @return [Fiber] child fiber
     def spin(tag = nil, orig_caller = Kernel.caller, &block)
       f = Fiber.new { |v| f.run(v) }
@@ -456,10 +457,11 @@ module Polyphony
 
     # Removes a child fiber reference. Used internally.
     #
-    # @param parent [Fiber] new parent
+    # @param child_fiber [Fiber] child fiber to be removed
     # @return [Fiber] self
     def remove_child(child_fiber)
       @children.delete(child_fiber) if @children
+      self
     end
   end
 

data/lib/polyphony/extensions/io.rb

@@ -5,9 +5,10 @@ require 'open3'
 # IO extensions
 class ::IO
   class << self
+    # @!visibility private
     alias_method :orig_binread, :binread
 
-    # TODO: add docs to all methods in this file
+    # @!visibility private
     def binread(name, length = nil, offset = nil)
       File.open(name, 'rb:ASCII-8BIT') do |f|
         f.seek(offset) if offset
@@ -15,7 +16,10 @@ class ::IO
       end
     end
 
+    # @!visibility private
     alias_method :orig_binwrite, :binwrite
+
+    # @!visibility private
     def binwrite(name, string, offset = nil)
       File.open(name, 'wb:ASCII-8BIT') do |f|
         f.seek(offset) if offset
@@ -23,13 +27,14 @@ class ::IO
       end
     end
 
+    # @!visibility private
     EMPTY_HASH = {}.freeze
 
+    # @!visibility private
     alias_method :orig_foreach, :foreach
-    def foreach(name, sep = $/, limit = nil, getline_args = EMPTY_HASH, &block)
-      # IO.orig_read(name).each_line(&block)
-      # raise NotImplementedError
 
+    # @!visibility private
+    def foreach(name, sep = $/, limit = nil, getline_args = EMPTY_HASH, &block)
       if sep.is_a?(Integer)
         sep = $/
         limit = sep
@@ -39,7 +44,10 @@ class ::IO
       end
     end
 
+    # @!visibility private
     alias_method :orig_read, :read
+
+    # @!visibility private
     def read(name, length = nil, offset = nil, opt = EMPTY_HASH)
       if length.is_a?(Hash)
         opt = length
@@ -58,7 +66,10 @@ class ::IO
     #   end
     # end
 
+    # @!visibility private
     alias_method :orig_write, :write
+
+    # @!visibility private
     def write(name, string, offset = nil, opt = EMPTY_HASH)
       File.open(name, opt[:mode] || 'w') do |f|
         f.seek(offset) if offset
@@ -66,22 +77,44 @@ class ::IO
       end
     end
 
+    # @!visibility private
     alias_method :orig_popen, :popen
+
+
+    # @!visibility private
     def popen(cmd, mode = 'r')
       return orig_popen(cmd, mode) unless block_given?
 
       Open3.popen2(cmd) { |_i, o, _t| yield o }
     end
 
+    # Splices from one IO to another IO. At least one of the IOs must be a pipe.
+    #
+    # @param src [IO, Polyphony::Pipe] source to splice from
+    # @param dest [IO, Polyphony::Pipe] destination to splice to
+    # @param maxlen [Integer] maximum bytes to splice
+    # @return [Integer] bytes spliced
     def splice(src, dest, maxlen)
       Polyphony.backend_splice(src, dest, maxlen)
     end
 
     if RUBY_PLATFORM =~ /linux/
+      # Creates a pipe and splices data between the two given IOs using the
+      # pipe, splicing until EOF.
+      #
+      # @param src [IO, Polyphony::Pipe] source to splice from
+      # @param dest [IO, Polyphony::Pipe] destination to splice to
+      # @return [Integer] total bytes spliced
       def double_splice(src, dest)
         Polyphony.backend_double_splice(src, dest)
       end
     
+      # Tees data from the source to the desination.
+      #
+      # @param src [IO, Polyphony::Pipe] source to tee from
+      # @param dest [IO, Polyphony::Pipe] destination to tee to
+      # @param maxlen [Integer] maximum bytes to tee
+      # @return [Integer] total bytes teed
       def tee(src, dest, maxlen)
         Polyphony.backend_tee(src, dest, maxlen)
       end
@@ -91,10 +124,12 @@ end
 
 # IO instance method patches
 class ::IO
+  # @!visibility private
   def __read_method__
     :backend_read
   end
 
+  # @!visibility private
   def __write_method__
     :backend_write
   end
@@ -113,13 +148,21 @@ class ::IO
   # def each_codepoint
   # end
 
+  # @!visibility private
   alias_method :orig_getbyte, :getbyte
+
+
+  # @!visibility private
   def getbyte
     char = getc
     char ? char.getbyte(0) : nil
   end
 
+  # @!visibility private
   alias_method :orig_getc, :getc
+
+
+  # @!visibility private
   def getc
     return @read_buffer.slice!(0) if @read_buffer && !@read_buffer.empty?
 
@@ -130,6 +173,7 @@ class ::IO
     nil
   end
 
+  # @!visibility private
   def ungetc(c)
     c = c.chr if c.is_a?(Integer)
     if @read_buffer
@@ -140,7 +184,11 @@ class ::IO
   end
   alias_method :ungetbyte, :ungetc
 
+  # @!visibility private
   alias_method :orig_read, :read
+
+
+  # @!visibility private
   def read(len = nil, buf = nil, buf_pos = 0)
     return '' if len == 0
 
@@ -157,7 +205,10 @@ class ::IO
     already_read
   end
 
+  # @!visibility private
   alias_method :orig_readpartial, :read
+
+  # @!visibility private
   def readpartial(len, str = +'', buffer_pos = 0, raise_on_eof = true)
     result = Polyphony.backend_read(self, str, len, false, buffer_pos)
     raise EOFError if !result && raise_on_eof
@@ -165,18 +216,27 @@ class ::IO
     result
   end
 
+  # @!visibility private
   alias_method :orig_write, :write
+
+  # @!visibility private
   def write(str, *args)
     Polyphony.backend_write(self, str, *args)
   end
 
+  # @!visibility private
   alias_method :orig_write_chevron, :<<
+
+  # @!visibility private
   def <<(str)
     Polyphony.backend_write(self, str)
     self
   end
-
+  
+  # @!visibility private
   alias_method :orig_gets, :gets
+
+  # @!visibility private
   def gets(sep = $/, _limit = nil, _chomp: nil)
     if sep.is_a?(Integer)
       sep = $/
@@ -197,6 +257,7 @@ class ::IO
     return nil
   end
 
+  # @!visibility private
   def each_line(sep = $/, limit = nil, chomp: false)
     if sep.is_a?(Integer)
       limit = sep
@@ -230,10 +291,15 @@ class ::IO
   # def putc(obj)
   # end
 
+  # @!visibility private
   LINEFEED = "\n"
+  # @!visibility private
   LINEFEED_RE = /\n$/.freeze
 
+  # @!visibility private
   alias_method :orig_puts, :puts
+
+  # @!visibility private
   def puts(*args)
     if args.empty?
       write LINEFEED
@@ -268,24 +334,66 @@ class ::IO
   # def readlines(sep = $/, limit = nil, chomp: nil)
   # end
 
+  # @!visibility private
   alias_method :orig_write_nonblock, :write_nonblock
+
+  # @!visibility private
   def write_nonblock(string, _options = {})
     write(string)
   end
 
+  # @!visibility private
   alias_method :orig_read_nonblock, :read_nonblock
+
+  # @!visibility private
   def read_nonblock(maxlen, buf = nil, _options = nil)
     buf ? readpartial(maxlen, buf) : readpartial(maxlen)
   end
 
+  # call-seq:
+  #   io.read_loop { |data| ... }
+  #   io.read_loop(maxlen) { |data| ... }
+  #
+  # Reads up to `maxlen` bytes at a time in an infinite loop. Read data
+  # will be passed to the given block.
+  #
+  # @param maxlen [Integer] maximum bytes to receive
+  # @yield [String] handler block
+  # @return [void]
   def read_loop(maxlen = 8192, &block)
     Polyphony.backend_read_loop(self, maxlen, &block)
   end
 
+  # call-seq:
+  #   io.feed_loop(receiver, method)
+  #   io.feed_loop(receiver, method) { |result| ... }
+  #
+  # Receives data from the io in an infinite loop, passing the data to the given
+  # receiver using the given method. If a block is given, the result of the
+  # method call to the receiver is passed to the block.
+  #
+  # This method can be used to feed data into parser objects. The following
+  # example shows how to feed data from a io directly into a MessagePack
+  # unpacker:
+  #
+  #   unpacker = MessagePack::Unpacker.new
+  #   buffer = []
+  #   reader = spin do
+  #     io.feed_loop(unpacker, :feed_each) { |msg| handle_msg(msg) }
+  #   end
+  #
+  # @param receiver [any] receiver object
+  # @param method [Symbol] method to call
+  # @yield [any] block to handle result of method call to receiver
+  # @return [void]
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_feed_loop(self, receiver, method, &block)
   end
 
+  # Waits for the IO to become readable, with an optional timeout.
+  #
+  # @param timeout [Integer, nil] optional timeout in seconds.
+  # @return [IO] self
   def wait_readable(timeout = nil)
     return self if @read_buffer && @read_buffer.size > 0
 
@@ -300,6 +408,10 @@ class ::IO
     end
   end
 
+  # Waits for the IO to become writeable, with an optional timeout.
+  #
+  # @param timeout [Integer, nil] optional timeout in seconds.
+  # @return [IO] self
   def wait_writable(timeout = nil)
     if timeout
       move_on_after(timeout) do
@@ -312,11 +424,21 @@ class ::IO
     end
   end
 
+  # Splices data from the given IO.
+  #
+  # @param src [IO, Polpyhony::Pipe] source to splice from
+  # @param maxlen [Integer] maximum bytes to splice
+  # @return [Integer] bytes spliced
   def splice_from(src, maxlen)
     Polyphony.backend_splice(src, self, maxlen)
   end
 
   if RUBY_PLATFORM =~ /linux/
+    # Tees data from the given IO.
+    #
+    # @param src [IO, Polpyhony::Pipe] source to tee from
+    # @param maxlen [Integer] maximum bytes to tee
+    # @return [Integer] bytes teed
     def tee_from(src, maxlen)
       Polyphony.backend_tee(src, self, maxlen)
     end

data/lib/polyphony/extensions/kernel.rb

@@ -4,11 +4,13 @@ require 'open3'
 
 # Kernel extensions (methods available to all objects / call sites)
 module ::Kernel
+  # @!visibility private
   alias_method :orig_sleep, :sleep
 
+  # @!visibility private
   alias_method :orig_backtick, :`
 
-  # TODO: add docs to all methods in this file
+  # @!visibility private
   def `(cmd)
     Open3.popen3(cmd) do |i, o, e, _t|
       i.close
@@ -18,6 +20,7 @@ module ::Kernel
     end
   end
 
+  # @!visibility private
   ARGV_GETS_LOOP = proc do |calling_fiber|
     while (fn = ARGV.shift)
       File.open(fn, 'r') do |f|
@@ -31,7 +34,10 @@ module ::Kernel
     calling_fiber.transfer(e)
   end
 
+  # @!visibility private
   alias_method :orig_gets, :gets
+
+  # Reads a single line from STDIN
   def gets(*_args)
     if !ARGV.empty? || @gets_fiber
       @gets_fiber ||= Fiber.new(&ARGV_GETS_LOOP)
@@ -45,7 +51,10 @@ module ::Kernel
     $stdin.gets
   end
 
+  # @!visibility private
   alias_method :orig_p, :p
+
+  # @!visibility private
   def p(*args)
     strs = args.inject([]) do |m, a|
       m << a.inspect << "\n"
@@ -54,13 +63,19 @@ module ::Kernel
     args.size == 1 ? args.first : args
   end
 
+  # @!visibility private
   alias_method :orig_system, :system
+
+  # @!visibility private
   def system(*args)
     Kernel.system(*args)
   end
 
   class << self
+    # @!visibility private
     alias_method :orig_system, :system
+
+    # @!visibility private
     def system(*args)
       waiter = nil
       Open3.popen2(*args) do |i, o, t|
@@ -74,7 +89,10 @@ module ::Kernel
     end
   end
 
+  # @!visibility private
   alias_method :orig_trap, :trap
+
+  # @!visibility private
   def trap(sig, command = nil, &block)
     return orig_trap(sig, command) if command.is_a? String
 
@@ -93,7 +111,7 @@ module ::Kernel
 
   private
 
-  # :no-doc:
+  # @!visibility private
   def pipe_to_eof(src, dest)
     src.read_loop { |data| dest << data }
   end