polyphony 0.99.4 → 0.99.6

data/lib/polyphony/extensions/io.rb

@@ -108,7 +108,7 @@ class ::IO
       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
@@ -232,7 +232,7 @@ class ::IO
     Polyphony.backend_write(self, str)
     self
   end
-  
+
   # @!visibility private
   alias_method :orig_gets, :gets
 
@@ -350,24 +350,16 @@ class ::IO
     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]
+  # @yield [String] read data
+  # @return [IO] self
   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.
@@ -384,8 +376,7 @@ class ::IO
   #
   # @param receiver [any] receiver object
   # @param method [Symbol] method to call
-  # @yield [any] block to handle result of method call to receiver
-  # @return [void]
+  # @return [IO] self
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_feed_loop(self, receiver, method, &block)
   end

data/lib/polyphony/extensions/object.rb

@@ -1,8 +1,289 @@
 # frozen_string_literal: true
 
-require_relative '../core/global_api'
+require_relative '../core/throttler'
 
 # Object extensions (methods available to all objects / call sites)
 class ::Object
-  include Polyphony::GlobalAPI
+  # Spins up a fiber that will run the given block after sleeping for the
+  # given delay.
+  #
+  # @param interval [Number] delay in seconds before running the given block
+  # @return [Fiber] spun fiber
+  def after(interval, &block)
+    spin do
+      sleep interval
+      block.()
+    end
+  end
+
+  # 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
+  #
+  # @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)
+    else
+      Polyphony.backend_timeout(interval, with_exception, &block)
+    end
+  end
+
+  # Spins up a new fiber.
+  #
+  # @param tag [any] optional tag for the new fiber
+  # @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
+  # @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_loop_without_throttling(tag, caller, block)
+    end
+  end
+
+  # Runs the given code, then waits for any child fibers of the current fibers
+  # to terminate.
+  #
+  # @return [any] given block's return value
+  def spin_scope(&block)
+    raise unless block
+
+    spin do
+      result = yield
+      Fiber.current.await_all_children
+      result
+    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
+  def every(interval, &block)
+    Polyphony.backend_timer_loop(interval, &block)
+  end
+
+  # 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
+  #
+  # @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)
+    else
+      Polyphony.backend_timeout(interval, nil, with_value, &block)
+    end
+  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
+  # @return [any]
+  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 [any]
+  def sleep(duration = nil)
+    duration ?
+    Polyphony.backend_sleep(duration) : Polyphony.backend_wait_event(true)
+  end
+
+  # 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)
+  # @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)
+  # @return [any]
+  def throttled_loop(rate = nil, **opts, &block)
+    throttler = Polyphony::Throttler.new(rate || opts)
+    if opts[:count]
+      opts[:count].times { |_i| throttler.(&block) }
+    else
+      while true
+        throttler.(&block)
+      end
+    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
+  # @return [any] block's return value
+  def cancel_after_with_optional_reset(interval, exception, &block)
+    fiber = Fiber.current
+    canceller = spin do
+      Polyphony.backend_sleep(interval)
+      exception = cancel_exception(exception)
+      exception.raising_fiber = Fiber.current
+      fiber.cancel(exception)
+    end
+    block.call(canceller)
+  ensure
+    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 [any]
+  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
+  # @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)
+    end
+    block.call(canceller)
+  rescue Polyphony::MoveOn => e
+    e.value
+  ensure
+    canceller.stop
+  end
 end

data/lib/polyphony/extensions/openssl.rb

@@ -17,7 +17,6 @@ class ::OpenSSL::SSL::SSLSocket
   #
   # @param socket [TCPSocket] socket to wrap
   # @param context [OpenSSL::SSL::SSLContext] optional SSL context
-  # @return [void]
   def initialize(socket, context = nil)
     socket = socket.respond_to?(:io) ? socket.io || socket : socket
     context ? orig_initialize(socket, context) : orig_initialize(socket)
@@ -89,12 +88,6 @@ class ::OpenSSL::SSL::SSLSocket
   # @!visibility private
   alias_method :orig_read, :read
 
-  # call-seq:
-  #   socket.read -> string
-  #   socket.read(maxlen) -> string
-  #   socket.read(maxlen, buf) -> buf
-  #   socket.read(maxlen, buf, buf_pos) -> buf
-  #
   # Reads from the socket. If `maxlen` is given, reads up to `maxlen` bytes from
   # the socket, otherwise reads to `EOF`. If `buf` is given, it is used as the
   # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
@@ -123,12 +116,6 @@ class ::OpenSSL::SSL::SSLSocket
     buf
   end
 
-  # call-seq:
-  #   socket.readpartial(maxlen) -> string
-  #   socket.readpartial(maxlen, buf) -> buf
-  #   socket.readpartial(maxlen, buf, buf_pos) -> buf
-  #   socket.readpartial(maxlen, buf, buf_pos, raise_on_eof) -> buf
-  #
   # Reads up to `maxlen` from the socket. If `buf` is given, it is used as the
   # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
   # given, reads into the given offset (in bytes) in the given buffer. If the
@@ -162,18 +149,12 @@ class ::OpenSSL::SSL::SSLSocket
     result
   end
 
-  # call-seq:
-  #   socket.recv_loop { |data| ... }
-  #   socket.recv_loop(maxlen) { |data| ... }
-  #   socket.read_loop { |data| ... }
-  #   socket.read_loop(maxlen) { |data| ... }
-  #
   # Receives up to `maxlen` bytes at a time in an infinite loop. Read buffers
   # will be passed to the given block.
   #
   # @param maxlen [Integer] maximum bytes to receive
-  # @yield [String] handler block
-  # @return [void]
+  # @yield [String] read data
+  # @return [OpenSSL::SSL::SSLSocket] self
   def read_loop(maxlen = 8192)
     while (data = sysread(maxlen))
       yield data
@@ -279,13 +260,11 @@ class ::OpenSSL::SSL::SSLServer
     orig_close
   end
 
-  # call-seq:
-  #   socket.accept_loop { |conn| ... }
-  #
   # Accepts incoming connections in an infinite loop.
   #
-  # @yield [OpenSSL::SSL::SSLSocket] block receiving accepted sockets
-  # @return [void]
+  # @param ignore_errors [boolean] whether to ignore IO and SSL errors
+  # @yield [OpenSSL::SSL::SSLSocket] accepted socket
+  # @return [OpenSSL::SSL::SSLServer] self
   def accept_loop(ignore_errors = true)
     loop do
       yield accept

data/lib/polyphony/extensions/pipe.rb

@@ -72,7 +72,7 @@ class Polyphony::Pipe
   end
 
   # Writes to the pipe.
-  
+
   # @param buf [String] data to write
   # @param args [any] further arguments to pass to Polyphony.backend_write
   # @return [Integer] bytes written
@@ -81,7 +81,7 @@ class Polyphony::Pipe
   end
 
   # Writes to the pipe.
-  
+
   # @param buf [String] data to write
   # @return [Integer] bytes written
   def <<(buf)
@@ -89,12 +89,6 @@ class Polyphony::Pipe
     self
   end
 
-  # call-seq:
-  #   pipe.gets(limit, chomp)
-  #   pipe.gets(separator, limit, chomp)
-  #
-  # Reads a single line from the pipe.
-  #
   # @param sep [String] line separator
   # @param _limit [Integer, nil] line length limit
   # @param _chomp [boolean, nil] whether to chomp the read line
@@ -134,7 +128,7 @@ class Polyphony::Pipe
   LINEFEED_RE = /\n$/.freeze
 
   # Writes a line with line feed to the pipe.
-  # 
+  #
   # @param args [Array] zero or more lines
   def puts(*args)
     if args.empty?
@@ -183,16 +177,12 @@ class Polyphony::Pipe
   # Runs a read loop.
   #
   # @param maxlen [Integer] maximum bytes to read
-  # @yield [String] read block
-  # @return [void]
+  # @yield [String] read data
+  # @return [Polyphony::Pipe] self
   def read_loop(maxlen = 8192, &block)
     Polyphony.backend_read_loop(self, maxlen, &block)
   end
 
-  # call-seq:
-  #   pipe.feed_loop(receiver, method)
-  #   pipe.feed_loop(receiver, method) { |result| ... }
-  #
   # Receives data from the pipe 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.
@@ -209,8 +199,7 @@ class Polyphony::Pipe
   #
   # @param receiver [any] receiver object
   # @param method [Symbol] method to call
-  # @yield [any] block to handle result of method call to receiver
-  # @return [void]
+  # @return [Polyphony::Pipe] self
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_feed_loop(self, receiver, method, &block)
   end