polyphony 0.79 → 0.81.1

data/lib/polyphony/core/debug.rb

@@ -1,8 +1,15 @@
+# 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
 
+  # Formats a trace message.
+  #
+  # @return [String] trace message
   def format_trace(args)
     if args.size > 1 && args.first.is_a?(String)
       format("%s: %p\n", args.shift, args.size == 1 ? args.first : args)
@@ -15,14 +22,29 @@ module ::Kernel
 end
 
 module Polyphony
+
+  # Trace provides tools for tracing the activity of the current thread's
+  # backend.
   module Trace
     class << self
+
+      # Starts tracing, emitting events converted to hashes to the given block.
+      # If an IO instance is given, events are dumped to it instead.
+      #
+      # @param io [IO, nil] IO instance
+      # @param &block [Proc] event handler block
+      # @return [void]
       def start_event_firehose(io = nil, &block)
         Thread.backend.trace_proc = firehose_proc(io, block)
       end
 
       private
 
+      # Returns a firehose proc for the given io and block.
+      #
+      # @param io [IO, nil] IO instance
+      # @param block [Proc] event handler block
+      # @return [Proc] firehose proc
       def firehose_proc(io, block)
         if io
           ->(*e) { io.orig_write("#{trace_event_info(e).inspect}\n") }
@@ -33,53 +55,50 @@ module Polyphony
         end
       end
 
+      # Converts an event (expressed as an array) to a hash.
+      #
+      # @param e [Array] event as emitted by the backend
+      # @return [Hash] event hash
       def trace_event_info(e)
         {
-          stamp: format_current_time,
+          stamp: Time.now,
           event: e[0]
         }.merge(
           send(:"event_props_#{e[0]}", e)
         )
       end
-      
-      def format_trace_event_message(e)
-        props = send(:"event_props_#{e[0]}", e).merge(
-          timestamp: format_current_time,
-          event: e[0]
-        )
-        # templ = send(:"event_format_#{e[0]}", e)
-
-        # msg = format("%<timestamp>s #{templ}\n", **props)
-      end
-
-      def format_current_time
-        Time.now.strftime('%Y-%m-%d %H:%M:%S')
-      end
 
-      def generic_event_format
-        '%<event>-12.12s'
-      end
-
-      def fiber_event_format
-        "#{generic_event_format} %<fiber>-44.44s"
+      # Returns an event hash for a `:block` event.
+      #
+      # @param e [Array] event array
+      # @return [Hash] event hash
+      def event_props_block(e)
+        {
+          fiber: e[1],
+          caller: e[2]
+        }
       end
 
+      # Returns an event hash for a `:enter_poll` event.
+      #
+      # @param e [Array] event array
+      # @return [Hash] event hash
       def event_props_enter_poll(e)
         {}
       end
 
-      def event_format_enter_poll(e)
-        generic_event_format
-      end
-
+      # Returns an event hash for a `:leave_poll` event.
+      #
+      # @param e [Array] event array
+      # @return [Hash] event hash
       def event_props_leave_poll(e)
         {}
       end
 
-      def event_format_leave_poll(e)
-        generic_event_format
-      end
-
+      # Returns an event hash for a `:schedule` event.
+      #
+      # @param e [Array] event array
+      # @return [Hash] event hash
       def event_props_schedule(e)
         {
           fiber: e[1],
@@ -89,22 +108,22 @@ module Polyphony
         }
       end
 
-      def event_format_schedule(e)
-        "#{fiber_event_format} %<value>-24.24p %<caller>-120.120s <= %<origin_fiber>s"
-      end
-
-      def event_props_unblock(e)
+      # Returns an event hash for a `:spin` event.
+      #
+      # @param e [Array] event array
+      # @return [Hash] event hash
+      def event_props_spin(e)
         {
           fiber: e[1],
-          value: e[2],
-          caller: e[3],
+          caller: e[2],
+          source_fiber: Fiber.current
         }
       end
 
-      def event_format_unblock(e)
-        "#{fiber_event_format} %<value>-24.24p %<caller>-120.120s"
-      end
-
+      # Returns an event hash for a `:terminate` event.
+      #
+      # @param e [Array] event array
+      # @return [Hash] event hash
       def event_props_terminate(e)
         {
           fiber: e[1],
@@ -112,48 +131,86 @@ module Polyphony
         }
       end
 
-      def event_format_terminate(e)
-        "#{fiber_event_format} %<value>-24.24p"
-      end
-
-      def event_props_block(e)
+      # Returns an event hash for a `:unblock` event.
+      #
+      # @param e [Array] event array
+      # @return [Hash] event hash
+      def event_props_unblock(e)
         {
           fiber: e[1],
-          caller: e[2]
+          value: e[2],
+          caller: e[3],
         }
       end
 
-      def event_format_block(e)
-        "#{fiber_event_format} #{' ' * 24} %<caller>-120.120s"
-      end
+      # TODO: work on text formatting of events
+      # def format_trace_event_message(e)
+      #   props = send(:"event_props_#{e[0]}", e).merge(
+      #     timestamp: format_current_time,
+      #     event: e[0]
+      #   )
+      #   templ = send(:"event_format_#{e[0]}", e)
+      #   msg = format("%<timestamp>s #{templ}\n", **props)
+      # end
 
-      def event_props_spin(e)
-        {
-          fiber: e[1],
-          caller: e[2],
-          source_fiber: Fiber.current
-        }
-      end
+      # def format_current_time
+      #   Time.now.strftime('%Y-%m-%d %H:%M:%S')
+      # end
 
-      def event_format_spin(e)
-        "#{fiber_event_format} #{' ' * 24} %<caller>-120.120s <= %<origin_fiber>s"
-      end
+      # def generic_event_format
+      #   '%<event>-12.12s'
+      # end
 
-      def fibe_repr(fiber)
-        format("%-6x %-20.20s %-10.10s", fiber.object_id, fiber.tag, "(#{fiber.state})")
-      end
+      # def fiber_event_format
+      #   "#{generic_event_format} %<fiber>-44.44s"
+      # end
 
-      def fiber_compact_repr(fiber)
-        if fiber.tag
-          format("%-6x %-.20s %-.10s", fiber.object_id, fiber.tag, "(#{fiber.state})")
-        else
-          format("%-6x %-.10s", fiber.object_id, "(#{fiber.state})")
-        end
-      end
+      # def event_format_enter_poll(e)
+      #   generic_event_format
+      # end
 
-      def caller_repr(c)
-       c.map { |i| i.gsub('/home/sharon/repo/polyphony/lib/polyphony', '') }.join('  ')
-      end
+      # def event_format_leave_poll(e)
+      #   generic_event_format
+      # end
+
+
+      # def event_format_schedule(e)
+      #   "#{fiber_event_format} %<value>-24.24p %<caller>-120.120s <= %<origin_fiber>s"
+      # end
+
+
+      # def event_format_unblock(e)
+      #   "#{fiber_event_format} %<value>-24.24p %<caller>-120.120s"
+      # end
+
+      # def event_format_terminate(e)
+      #   "#{fiber_event_format} %<value>-24.24p"
+      # end
+
+      # def event_format_block(e)
+      #   "#{fiber_event_format} #{' ' * 24} %<caller>-120.120s"
+      # end
+
+
+      # def event_format_spin(e)
+      #   "#{fiber_event_format} #{' ' * 24} %<caller>-120.120s <= %<origin_fiber>s"
+      # end
+
+      # def fibe_repr(fiber)
+      #   format("%-6x %-20.20s %-10.10s", fiber.object_id, fiber.tag, "(#{fiber.state})")
+      # end
+
+      # def fiber_compact_repr(fiber)
+      #   if fiber.tag
+      #     format("%-6x %-.20s %-.10s", fiber.object_id, fiber.tag, "(#{fiber.state})")
+      #   else
+      #     format("%-6x %-.10s", fiber.object_id, "(#{fiber.state})")
+      #   end
+      # end
+
+      # def caller_repr(c)
+      #  c.map { |i| i.gsub('/home/sharon/repo/polyphony/lib/polyphony', '') }.join('  ')
+      # end
     end
   end
 end

data/lib/polyphony/core/exceptions.rb

@@ -1,15 +1,22 @@
 # frozen_string_literal: true
 
 module Polyphony
-  # Common exception class for interrupting fibers. These exceptions allow
-  # control of fibers. BaseException exceptions can encapsulate a value and thus
-  # provide a way to interrupt long-running blocking operations while still
-  # passing a value back to the call site. BaseException exceptions can also
-  # references a cancel scope in order to allow correct bubbling of exceptions
-  # through nested cancel scopes.
+
+  # Base exception class for interrupting fibers. These exceptions allow control
+  # of fibers. BaseException exceptions can encapsulate a value and thus provide
+  # a way to interrupt long-running blocking operations while still passing a
+  # value back to the call site. BaseException exceptions can also references a
+  # cancel scope in order to allow correct bubbling of exceptions through nested
+  # cancel scopes.
   class BaseException < ::Exception
+
+    # Exception value, used mainly for `MoveOn` exceptions.
     attr_reader :value
 
+    # 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
@@ -33,10 +40,18 @@ 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/global_api.rb

@@ -3,8 +3,16 @@
 require_relative './throttler'
 
 module Polyphony
-  # Global API methods to be included in ::Object
+  
+  # Global API methods to be included in `::Object`
   module GlobalAPI
+
+    # 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
+    # @return [Fiber] spun fiber
     def after(interval, &block)
       spin do
         sleep interval
@@ -12,64 +20,88 @@ 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`.
+    #
+    # 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
+    #
+    # @param interval [Number] timout in seconds
+    # @param with_exception: [Class, Exception] exception or exception class
+    # @param &block [Proc] block to execute
+    # @return [any] block's return value
     def cancel_after(interval, with_exception: Polyphony::Cancel, &block)
-      if !block
-        cancel_after_blockless_canceller(Fiber.current, interval, with_exception)
-      elsif block.arity > 0
-        cancel_after_with_block(Fiber.current, interval, with_exception, &block)
+      if block.arity > 0
+        cancel_after_with_optional_reset(interval, with_exception, &block)
       else
         Polyphony.backend_timeout(interval, with_exception, &block)
       end
     end
 
-    def cancel_after_blockless_canceller(fiber, interval, with_exception)
-      spin do
-        sleep interval
-        exception = cancel_exception(with_exception)
-        exception.raising_fiber = nil
-        fiber.schedule exception
-      end
-    end
-
-    def cancel_after_with_block(fiber, interval, with_exception, &block)
-      canceller = cancel_after_blockless_canceller(fiber, interval, with_exception)
-      block.call(canceller)
-    ensure
-      canceller.stop
-    end
-
-    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
-
+    # Spins up a new fiber.
+    #
+    # @param tag [any] optional tag for the new fiber
+    # @param &block [Proc] fiber block
+    # @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
+    # @param &block [Proc] code to run
+    # @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_looped_block(tag, caller, block)
-      end
-    end
-
-    def spin_looped_block(tag, caller, block)
-      Fiber.current.spin(tag, caller) do
-        block.call while true
-      rescue LocalJumpError, StopIteration
-        # break called or StopIteration raised
+        spin_loop_without_throttling(tag, caller, block)
       end
     end
 
-    def spin_scope
-      raise unless block_given?
+    # Runs the given code, then waits for any child fibers of the current fibers
+    # to terminate.
+    #
+    # @param &block [Proc] code to run
+    # @return [any] given block's return value
+    def spin_scope(&block)
+      raise unless block
 
       spin do
         result = yield
@@ -78,61 +110,121 @@ module Polyphony
       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
+    # @param &block [Proc] 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,
+    # 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
+    #
+    # @param interval [Number] timout in seconds
+    # @param with_value: [any] return value in case of timeout
+    # @param &block [Proc] block to execute
+    # @return [any] block's return value
     def move_on_after(interval, with_value: nil, &block)
-      if !block
-        move_on_blockless_canceller(Fiber.current, interval, with_value)
-      elsif block.arity > 0
-        move_on_after_with_block(Fiber.current, interval, with_value, &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
 
-    def move_on_blockless_canceller(fiber, interval, with_value)
-      spin do
-        sleep interval
-        fiber.schedule with_value
-      end
-    end
-
-    def move_on_after_with_block(fiber, interval, with_value, &block)
-      canceller = spin do
-        sleep interval
-        fiber.schedule Polyphony::MoveOn.new(with_value)
-      end
-      block.call(canceller)
-    rescue Polyphony::MoveOn => e
-      e.value
-    ensure
-      canceller.stop
-    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
+    # @param &block [Proc] given block
+    # @return [void]
     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 [void]
     def sleep(duration = nil)
-      return sleep_forever unless duration
-
-      Polyphony.backend_sleep duration
-    end
-
-    def sleep_forever
-      Polyphony.backend_wait_event(true)
+      duration ?
+        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
+    # parameter. The throttling can also be controlled by providing an
+    # `interval:` or `rate:` named parameter.
+    #
+    # @param rate [Number, nil] loop rate (times per second)
+    # @param rate: [Number] loop rate (times per second)
+    # @param interval: [Number] loop interval in seconds
+    # @param count: [Number, nil] number of iterations (nil for infinite)
+    # @param &block [Proc] code to run
+    # @return [void]
     def throttled_loop(rate = nil, **opts, &block)
       throttler = Polyphony::Throttler.new(rate || opts)
       if opts[:count]
@@ -144,10 +236,73 @@ module Polyphony
       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
+    # @param &block [Proc] block to run
+    # @return [any] block's return value
+    def cancel_after_with_optional_reset(interval, exception, &block)
+      canceller = spin do
+        sleep interval
+        exception = cancel_exception(exception)
+        exception.raising_fiber = Fiber.current
+        fiber.cancel(exception).await
+      end
+      block.call(canceller)
     ensure
-      throttler&.stop
+      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 [void]
+    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
+    # @param &block [Proc] 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
+      canceller = spin do
+        sleep interval
+        fiber.move_on(value).await
+      end
+      block.call(canceller)
+    rescue Polyphony::MoveOn => e
+      e.value
+    ensure
+      canceller.stop
+    end
+
   end
 end
-
-Object.include Polyphony::GlobalAPI