polyphony 0.79 → 0.80

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34ed5a7685a8986f1fe5fd6cd714ee049633952746ecb8bced1aee73553c6c99
-  data.tar.gz: 03ded408e8849a921d0cfbbe1a232c5cea83cfbd58710efade4900f6240f511c
+  metadata.gz: cf3658689c8bb7614624ad75492b16fc31401c5c8ee37cd510bb4aab1c9d1449
+  data.tar.gz: 5e2520d758db10e9dfe8022d6a85df61e1702f2e1e6560a95968e37b6f4f6e82
 SHA512:
-  metadata.gz: 91fe5a0979c0158315e942bba88f563a47926e78ad3da0ff8e483ee91aff1482af1f2fc3e3aa4cacd49e787531627bfc3295d45439e99d8400b4736b1a749443
-  data.tar.gz: 3c1eaaccec661c4f3e4c07853fbaaaab19222837d5ac25b4098856bd1b1367833cbc35a58602fb9c30ff8e7cd63d04f79206bf07438a1e842eb86871c8036063
+  metadata.gz: 7bd42d8fed28064941281c0e010f86a7ff7fff56e28c8e8190c8bc5c68eebd26a8d568e03ce20120db64684a036afb8d9b8586668c59f39fadebdaba2624ba75
+  data.tar.gz: cd91d0394a0642fbb43d59cc3ba6a3100377be955f1cabeebc051f8f6159d6fb0e78fa7deedabc6bc4fabc20b12453c963b85ed9ce76002211d3423b05f51542

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.80 2022-02-28
+
+- Prevent reentry into `trace_proc`
+- Rename `__parser_read_method__` to `__read_method__`
+- Rename `ResourcePool#preheat!` to `#fill`.
+- Remove ability to use `#cancel_after` or `#move_on` without a block
+- Add #move_on alias to `Fiber#interrupt`
+- Allow specifying exception in `Fiber#cancel`
+- Remove deprecated `Polyphony::Channel` class
+
 ## 0.79 2022-02-19
 
 - Overhaul trace events system (#73)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    polyphony (0.79)
+    polyphony (0.80)
 
 GEM
   remote: https://rubygems.org/
@@ -60,6 +60,7 @@ GEM
     unicode-display_width (1.8.0)
 
 PLATFORMS
+  ruby
   universal-darwin
   universal-freebsd
   universal-linux

data/examples/core/zlib_stream.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony'
+require 'zlib'
+
+r, w = IO.pipe
+writer = Zlib::GzipWriter.new(w)
+
+writer << 'chunk'
+writer.flush
+p pos: writer.pos
+w.close
+
+p r.read

data/ext/polyphony/backend_common.c

@@ -17,6 +17,7 @@ inline void backend_base_initialize(struct Backend_base *base) {
   base->idle_gc_last_time = 0;
   base->idle_proc = Qnil;
   base->trace_proc = Qnil;
+  base->in_trace_proc = 0;
 }
 
 inline void backend_base_finalize(struct Backend_base *base) {
@@ -137,7 +138,7 @@ inline void backend_base_unpark_fiber(struct Backend_base *base, VALUE fiber) {
 }
 
 inline void backend_trace(struct Backend_base *base, int argc, VALUE *argv) {
-  if (base->trace_proc == Qnil) return;
+  if (base->trace_proc == Qnil || base->in_trace_proc) return;
 
   rb_funcallv(base->trace_proc, ID_call, argc, argv);
 }

data/ext/polyphony/backend_common.h

@@ -32,6 +32,7 @@ struct Backend_base {
   double idle_gc_last_time;
   VALUE idle_proc;
   VALUE trace_proc;
+  unsigned int in_trace_proc;
 };
 
 void backend_base_initialize(struct Backend_base *base);
@@ -46,8 +47,12 @@ void backend_trace(struct Backend_base *base, int argc, VALUE *argv);
 struct backend_stats backend_base_stats(struct Backend_base *base);
 
 // tracing
-#define SHOULD_TRACE(base) ((base)->trace_proc != Qnil)
-#define TRACE(base, ...)  rb_funcall((base)->trace_proc, ID_call, __VA_ARGS__)
+#define SHOULD_TRACE(base) ((base)->trace_proc != Qnil && !(base)->in_trace_proc)
+#define TRACE(base, ...) { \
+  (base)->in_trace_proc = 1; \
+  rb_funcall((base)->trace_proc, ID_call, __VA_ARGS__); \
+  (base)->in_trace_proc = 0; \
+}
 #define COND_TRACE(base, ...) if (SHOULD_TRACE(base)) { TRACE(base, __VA_ARGS__); }
 
 

data/lib/polyphony/adapters/fs.rb

@@ -6,6 +6,8 @@ require_relative '../core/thread_pool'
 
 ::File.singleton_class.instance_eval do
   alias_method :orig_stat, :stat
+
+  # Offloads `File.stat` to the default thread pool.
   def stat(path)
     ThreadPool.process { orig_stat(path) }
   end
@@ -13,6 +15,8 @@ end
 
 ::IO.singleton_class.instance_eval do
   alias_method :orig_read, :read
+
+  # Offloads `IO.read` to the default thread pool.
   def read(path)
     ThreadPool.process { orig_read(path) }
   end

data/lib/polyphony/adapters/process.rb

@@ -1,9 +1,20 @@
 # frozen_string_literal: true
 
 module Polyphony
-  # Process patches
+  # Process extensions
   module Process
     class << self
+
+      # 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
+      # @param &block [Proc] block to fork
+      # @return [void]
       def watch(cmd = nil, &block)
         terminated = nil
         pid = cmd ? Kernel.spawn(cmd) : Polyphony.fork(&block)
@@ -13,6 +24,8 @@ module Polyphony
         kill_process(pid) unless terminated || pid.nil?
       end
 
+      private
+
       def kill_process(pid)
         cancel_after(5) do
           kill_and_await('TERM', pid)

data/lib/polyphony/adapters/redis.rb

@@ -7,6 +7,10 @@ require 'hiredis/reader'
 
 # Polyphony-based Redis driver
 class Polyphony::RedisDriver
+
+  # Connects to a Redis server using the given config.
+  #
+  # @return [TCPSocket, UNIXSocket, SSLSocket] client connectio
   def self.connect(config)
     raise 'unix sockets not supported' if config[:scheme] == 'unix'
 
@@ -20,28 +24,49 @@ class Polyphony::RedisDriver
     # connection.connect(config[:host], config[:port], connect_timeout)
   end
 
+  # Initializes a Redis client connection.
+  #
+  # @param host [String] hostname
+  # @param port [Integer] port number
   def initialize(host, port)
     @connection = Polyphony::Net.tcp_connect(host, port)
     @reader = ::Hiredis::Reader.new
   end
 
+  # Returns true if connected to server.
+  #
+  # @return [bool] is connected to server
   def connected?
     @connection && !@connection.closed?
   end
 
+  # Sets a timeout for the connection.
+  #
+  # @return [void]
   def timeout=(timeout)
     # ignore timeout for now
   end
 
+  # Disconnects from the server.
+  #
+  # @return [void]
   def disconnect
     @connection.close
     @connection = nil
   end
 
+  # Sends a command to the server.
+  #
+  # @param command [Array] Redis command
+  # @return [void]
   def write(command)
     @connection.write(format_command(command))
   end
 
+  # Formats a command for sending to server.
+  #
+  # @param args [Array] command
+  # @return [String] formatted command
   def format_command(args)
     args = args.flatten
     (+"*#{args.size}\r\n").tap do |s|
@@ -52,6 +77,9 @@ class Polyphony::RedisDriver
     end
   end
 
+  # Reads from the connection, feeding incoming data to the parser.
+  #
+  # @return [void]
   def read
     reply = @reader.gets
     return reply if reply

data/lib/polyphony/adapters/sequel.rb

@@ -4,14 +4,23 @@ 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
+    # @opts [Hash] connection pool options
     def initialize(db, opts = OPTS)
       super
       max_size = Integer(opts[:max_connections] || 4)
       @pool = Polyphony::ResourcePool.new(limit: max_size) { make_new(:default) }
     end
 
+    # Holds a connection from the pool, passing it to the given block.
+    #
+    # @return [any] block's return value
     def hold(_server = nil)
       @pool.acquire do |conn|
         yield conn
@@ -23,16 +32,25 @@ module Polyphony
       end
     end
 
+    # Returns the pool's size.
+    #
+    # @return [Integer] size of pool
     def size
       @pool.size
     end
 
+    # Returns the pool's maximal size.
+    #
+    # @return [Integer] maximum pool size
     def max_size
       @pool.limit
     end
 
+    # Fills pool and preconnects all db instances in pool.
+    #
+    # @return [void]
     def preconnect(_concurrent = false)
-      @pool.preheat!
+      @pool.fill!
     end
   end
 

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