polyphony 0.98 → 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
@@ -58,6 +58,58 @@ module Polyphony
       @holding_fiber
     end
 
+    # Obtains a lock. Raises `ThreadError` if mutex is locked by the current
+    # thread.
+    #
+    # @return [Mutex] self
+    def lock
+      raise ThreadError if owned?
+      
+      @token = @store.shift
+      @holding_fiber = Fiber.current
+      self
+    end
+
+    # Releases the lock. Raises `ThreadError` if mutex is not locked by the
+    # current thread.
+    #
+    # @return [Mutex] self
+    def unlock
+      raise ThreadError if !owned?
+
+      @holding_fiber = nil
+      @store << @token if @token
+      @token = nil
+    end
+
+    # Attempts to obtain the lock and returns immediately. Returns `true` if the
+    # lock was granted.
+    #
+    # @return [true, false]
+    def try_lock
+      return false if @holding_fiber
+
+      @token = @store.shift
+      @holding_fiber = Fiber.current
+      true
+    end
+
+    # Releases the lock and sleeps timeout seconds if it is given and non-nil or
+    # forever. Raises `ThreadError` if mutex wasn’t locked by the current
+    # thread.
+    #
+    # @param timeout [nil, Number] sleep timeout
+    # @return [Number] slept time in seconds
+    def sleep(timeout = nil)
+      unlock
+      t0 = Time.now
+      Kernel.sleep(timeout)
+      t1 = Time.now
+      lock
+
+      return t1 - t0
+    end
+
     private
 
     # Helper method for performing a `#synchronize` when not currently holding
@@ -72,6 +124,7 @@ module Polyphony
       ensure
         @holding_fiber = nil
         @store << @token if @token
+        @token = nil
       end
     end
   end
@@ -87,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,24 +27,27 @@ class ::IO
       end
     end
 
+    # @!visibility private
     EMPTY_HASH = {}.freeze
 
-    # 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
-
-    #   # if sep.is_a?(Integer)
-    #   #   sep = $/
-    #   #   limit = sep
-    #   # end
-    #   # File.open(name, 'r') do |f|
-    #   #   f.each_line(sep, limit, getline_args, &block)
-    #   # end
-    # end
+    # @!visibility private
+    alias_method :orig_foreach, :foreach
+
+    # @!visibility private
+    def foreach(name, sep = $/, limit = nil, getline_args = EMPTY_HASH, &block)
+      if sep.is_a?(Integer)
+        sep = $/
+        limit = sep
+      end
+      File.open(name, 'r') do |f|
+        f.each_line(sep, limit, chomp: getline_args[:chomp], &block)
+      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
@@ -59,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
@@ -67,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
@@ -92,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
@@ -114,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?
 
@@ -131,6 +173,7 @@ class ::IO
     nil
   end
 
+  # @!visibility private
   def ungetc(c)
     c = c.chr if c.is_a?(Integer)
     if @read_buffer
@@ -141,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
 
@@ -158,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
@@ -166,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 = $/
@@ -198,6 +257,31 @@ class ::IO
     return nil
   end
 
+  # @!visibility private
+  def each_line(sep = $/, limit = nil, chomp: false)
+    if sep.is_a?(Integer)
+      limit = sep
+      sep = $/
+    end
+    sep_size = sep.bytesize
+
+
+    @read_buffer ||= +''
+
+    while true
+      while (idx = @read_buffer.index(sep))
+        line = @read_buffer.slice!(0, idx + sep_size)
+        line = line.chomp if chomp
+        yield line
+      end
+
+      result = readpartial(8192, @read_buffer, -1)
+      return self if !result
+    end
+  rescue EOFError
+    return self
+  end
+
   # def print(*args)
   # end
 
@@ -207,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
@@ -245,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
 
@@ -277,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
@@ -289,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