polyphony 0.77 → 0.80

data/ext/polyphony/queue.c

@@ -2,6 +2,7 @@
 #include "ring_buffer.h"
 
 typedef struct queue {
+  unsigned int closed;
   ring_buffer values;
   ring_buffer shift_queue;
   ring_buffer push_queue;
@@ -9,6 +10,8 @@ typedef struct queue {
 } Queue_t;
 
 VALUE cQueue = Qnil;
+VALUE cClosedQueueError = Qnil;
+VALUE cThreadError = Qnil;
 
 static void Queue_mark(void *ptr) {
   Queue_t *queue = ptr;
@@ -49,6 +52,7 @@ static VALUE Queue_initialize(int argc, VALUE *argv, VALUE self) {
   Queue_t *queue;
   GetQueue(self, queue);
 
+  queue->closed = 0;
   ring_buffer_init(&queue->values);
   ring_buffer_init(&queue->shift_queue);
   ring_buffer_init(&queue->push_queue);
@@ -99,6 +103,9 @@ VALUE Queue_push(VALUE self, VALUE value) {
   Queue_t *queue;
   GetQueue(self, queue);
 
+  if (queue->closed)
+    rb_raise(cClosedQueueError, "queue closed");
+
   if (queue->capacity) capped_queue_block_push(queue);
 
   queue_schedule_first_blocked_fiber(&queue->shift_queue);
@@ -111,6 +118,9 @@ VALUE Queue_unshift(VALUE self, VALUE value) {
   Queue_t *queue;
   GetQueue(self, queue);
 
+  if (queue->closed)
+    rb_raise(cClosedQueueError, "queue closed");
+
   if (queue->capacity) capped_queue_block_push(queue);
 
   queue_schedule_first_blocked_fiber(&queue->shift_queue);
@@ -119,14 +129,25 @@ VALUE Queue_unshift(VALUE self, VALUE value) {
   return self;
 }
 
-VALUE Queue_shift(VALUE self) {
-  Queue_t *queue;
+VALUE Queue_shift_nonblock(Queue_t *queue) {
+  if (queue->values.count) {
+    VALUE value = ring_buffer_shift(&queue->values);
+    if ((queue->capacity) && (queue->capacity > queue->values.count))
+      queue_schedule_first_blocked_fiber(&queue->push_queue);
+    RB_GC_GUARD(value);
+    return value;
+  }
+  rb_raise(cThreadError, "queue empty");
+}
+
+VALUE Queue_shift_block(Queue_t *queue) {
   VALUE fiber = rb_fiber_current();
   VALUE thread = rb_thread_current();
   VALUE backend = rb_ivar_get(thread, ID_ivar_backend);
   VALUE value;
 
-  GetQueue(self, queue);
+  if (queue->closed && !queue->values.count)
+    rb_raise(cClosedQueueError, "queue closed");
 
   while (1) {
     VALUE switchpoint_result;
@@ -140,6 +161,7 @@ VALUE Queue_shift(VALUE self) {
     RAISE_IF_EXCEPTION(switchpoint_result);
     RB_GC_GUARD(switchpoint_result);
     if (queue->values.count) break;
+    if (queue->closed) return Qnil;
   }
   value = ring_buffer_shift(&queue->values);
   if ((queue->capacity) && (queue->capacity > queue->values.count))
@@ -148,6 +170,16 @@ VALUE Queue_shift(VALUE self) {
   return value;
 }
 
+VALUE Queue_shift(int argc,VALUE *argv, VALUE self) {
+  int nonblock = argc && RTEST(argv[0]);
+  Queue_t *queue;
+  GetQueue(self, queue);
+
+  return nonblock ?
+    Queue_shift_nonblock(queue) :
+    Queue_shift_block(queue);
+}
+
 VALUE Queue_delete(VALUE self, VALUE value) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -244,6 +276,13 @@ VALUE Queue_pending_p(VALUE self) {
   return (queue->shift_queue.count) ? Qtrue : Qfalse;
 }
 
+VALUE Queue_num_waiting(VALUE self) {
+  Queue_t *queue;
+  GetQueue(self, queue);
+
+  return INT2NUM(queue->shift_queue.count);
+}
+
 VALUE Queue_size_m(VALUE self) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -251,20 +290,54 @@ VALUE Queue_size_m(VALUE self) {
   return INT2NUM(queue->values.count);
 }
 
+VALUE Queue_closed_p(VALUE self) {
+  Queue_t *queue;
+  GetQueue(self, queue);
+
+  return (queue->closed) ? Qtrue : Qfalse;
+}
+
+VALUE Queue_close(VALUE self) {
+  Queue_t *queue;
+  GetQueue(self, queue);
+
+  if (queue->closed) goto end;
+  queue->closed = 1;
+
+  // release all fibers waiting on `#shift`
+  while (queue->shift_queue.count) {
+    VALUE fiber = ring_buffer_shift(&queue->shift_queue);
+    if (fiber == Qnil) break;
+    Fiber_make_runnable(fiber, Qnil);
+  }
+
+end:
+  return self;
+}
+
 void Init_Queue() {
+  cClosedQueueError = rb_const_get(rb_cObject, rb_intern("ClosedQueueError"));
+  cThreadError = rb_const_get(rb_cObject, rb_intern("ThreadError"));
+
   cQueue = rb_define_class_under(mPolyphony, "Queue", rb_cObject);
   rb_define_alloc_func(cQueue, Queue_allocate);
 
   rb_define_method(cQueue, "initialize", Queue_initialize, -1);
   rb_define_method(cQueue, "push", Queue_push, 1);
   rb_define_method(cQueue, "<<", Queue_push, 1);
+  rb_define_method(cQueue, "enq", Queue_push, 1);
   rb_define_method(cQueue, "unshift", Queue_unshift, 1);
 
-  rb_define_method(cQueue, "shift", Queue_shift, 0);
-  rb_define_method(cQueue, "pop", Queue_shift, 0);
+  rb_define_method(cQueue, "shift", Queue_shift, -1);
+  rb_define_method(cQueue, "pop", Queue_shift, -1);
+  rb_define_method(cQueue, "deq", Queue_shift, -1);
+
   rb_define_method(cQueue, "delete", Queue_delete, 1);
   rb_define_method(cQueue, "clear", Queue_clear, 0);
 
+  rb_define_method(cQueue, "size", Queue_size_m, 0);
+  rb_define_method(cQueue, "length", Queue_size_m, 0);
+
   rb_define_method(cQueue, "cap", Queue_cap, 1);
   rb_define_method(cQueue, "capped?", Queue_capped_p, 0);
 
@@ -273,5 +346,8 @@ void Init_Queue() {
   rb_define_method(cQueue, "flush_waiters", Queue_flush_waiters, 1);
   rb_define_method(cQueue, "empty?", Queue_empty_p, 0);
   rb_define_method(cQueue, "pending?", Queue_pending_p, 0);
-  rb_define_method(cQueue, "size", Queue_size_m, 0);
+  rb_define_method(cQueue, "num_waiting", Queue_num_waiting, 0);
+
+  rb_define_method(cQueue, "closed?", Queue_closed_p, 0);
+  rb_define_method(cQueue, "close", Queue_close, 0);
 }

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)
@@ -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,13 +1,216 @@
+# 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)
+    elsif args.size == 1 && args.first.is_a?(String)
+      "#{args.first}\n"
     else
       format("%p\n", args.size == 1 ? args.first : args)
     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