polyphony 0.78 → 0.81

data/ext/polyphony/polyphony.h

@@ -61,13 +61,13 @@ extern ID ID_switch_fiber;
 extern ID ID_to_s;
 extern ID ID_transfer;
 
-extern VALUE SYM_fiber_create;
-extern VALUE SYM_fiber_event_poll_enter;
-extern VALUE SYM_fiber_event_poll_leave;
-extern VALUE SYM_fiber_run;
-extern VALUE SYM_fiber_schedule;
-extern VALUE SYM_fiber_switchpoint;
-extern VALUE SYM_fiber_terminate;
+extern VALUE SYM_spin;
+extern VALUE SYM_enter_poll;
+extern VALUE SYM_leave_poll;
+extern VALUE SYM_unblock;
+extern VALUE SYM_schedule;
+extern VALUE SYM_block;
+extern VALUE SYM_terminate;
 
 VALUE Fiber_auto_watcher(VALUE self);
 void Fiber_make_runnable(VALUE fiber, VALUE value);
@@ -121,15 +121,29 @@ VALUE Backend_wait_event(VALUE self, VALUE raise_on_exception);
 VALUE Backend_wakeup(VALUE self);
 VALUE Backend_run_idle_tasks(VALUE self);
 VALUE Backend_switch_fiber(VALUE self);
+
 void Backend_schedule_fiber(VALUE thread, VALUE self, VALUE fiber, VALUE value, int prioritize);
 void Backend_unschedule_fiber(VALUE self, VALUE fiber);
 void Backend_park_fiber(VALUE self, VALUE fiber);
 void Backend_unpark_fiber(VALUE self, VALUE fiber);
 
+VALUE Backend_snooze(VALUE self);
+
 void Thread_schedule_fiber(VALUE thread, VALUE fiber, VALUE value);
 void Thread_schedule_fiber_with_priority(VALUE thread, VALUE fiber, VALUE value);
 VALUE Thread_switch_fiber(VALUE thread);
 
 VALUE Polyphony_snooze(VALUE self);
 
+struct raw_buffer {
+  char *base;
+  int size;
+};
+
+struct io_buffer {
+  char *base;
+  int size;
+  int raw;
+};
+
 #endif /* POLYPHONY_H */

data/ext/polyphony/thread.c

@@ -23,11 +23,15 @@ VALUE Thread_fiber_unschedule(VALUE self, VALUE fiber) {
 }
 
 inline void Thread_schedule_fiber(VALUE self, VALUE fiber, VALUE value) {
-  schedule_fiber(self, fiber, value, 0);
+  Backend_schedule_fiber(self, rb_ivar_get(self, ID_ivar_backend), fiber, value, 0);
+
+  // schedule_fiber(self, fiber, value, 0);
 }
 
 inline void Thread_schedule_fiber_with_priority(VALUE self, VALUE fiber, VALUE value) {
-  schedule_fiber(self, fiber, value, 1);
+  Backend_schedule_fiber(self, rb_ivar_get(self, ID_ivar_backend), fiber, value, 1);
+
+  // schedule_fiber(self, fiber, value, 1);
 }
 
 VALUE Thread_switch_fiber(VALUE self) {

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)
@@ -21,6 +32,8 @@ module Polyphony
         kill_and_await(-9, pid)
       end
 
+      private
+
       def kill_and_await(sig, pid)
         ::Process.kill(sig, pid)
         Polyphony.backend_waitpid(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)
@@ -13,3 +20,197 @@ module ::Kernel
     end
   end
 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") }
+        elsif block
+          ->(*e) { block.(trace_event_info(e)) }
+        else
+          raise "Please provide an io or a block"
+        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: Time.now,
+          event: e[0]
+        }.merge(
+          send(:"event_props_#{e[0]}", e)
+        )
+      end
+
+      # 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
+
+      # 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
+
+      # 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],
+          value: e[2],
+          caller: e[4],
+          source_fiber: Fiber.current
+        }
+      end
+
+      # 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],
+          caller: e[2],
+          source_fiber: Fiber.current
+        }
+      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],
+          value: e[2],
+        }
+      end
+
+      # 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],
+          value: e[2],
+          caller: e[3],
+        }
+      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 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"
+      # end
+
+      # def event_format_enter_poll(e)
+      #   generic_event_format
+      # 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