polyphony 0.99 → 0.99.1

data/ext/polyphony/queue.c

@@ -1,6 +1,19 @@
 #include "polyphony.h"
 #include "ring_buffer.h"
 
+/*
+ * Document-class: Polyphony::Queue
+ *
+ * This class implements a FIFO queue that can be used to exchange data between
+ * different fibers or threads. The queue can simultaneously service multiple
+ * producers and multiple consumers. A consumers trying to remove an item from
+ * an empty queue will block at least one item is added to the queue.
+ *
+ * A queue can also be capped in order to limit its depth. A producer trying to
+ * add an item to a full capped queue will block until at least one item is
+ * removed from it.
+ */
+
 typedef struct queue {
   unsigned int closed;
   ring_buffer values;
@@ -48,6 +61,18 @@ static VALUE Queue_allocate(VALUE klass) {
 #define GetQueue(obj, queue) \
   TypedData_Get_Struct((obj), Queue_t, &Queue_type, (queue))
 
+/* call-seq:
+ *   Queue.new -> queue
+ *   Queue.new(capacity) -> queue
+ *
+ * Initializes a queue instance. If the capacity is given, the queue becomes
+ * capped, i.e. it cannot contain more elements than its capacity. When trying
+ * to add items to a capped queue that is full, the current fiber will block
+ * until at least one item is removed from the queue.
+ * 
+ * @return [void]
+ */
+
 static VALUE Queue_initialize(int argc, VALUE *argv, VALUE self) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -99,6 +124,18 @@ static inline void capped_queue_block_push(Queue_t *queue) {
   }
 }
 
+/* call-seq:
+ *   queue.push(value) -> queue
+ *   queue.enq(value) -> queue
+ *   queue << value -> queue
+ *
+ * Adds the given value to the queue's end. If the queue is capped and full, the
+ * call will block until a value is removed from the queue.
+ * 
+ * @param value [any] value to be added to the queue
+ * @return [Queue] self
+ */
+
 VALUE Queue_push(VALUE self, VALUE value) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -114,6 +151,16 @@ VALUE Queue_push(VALUE self, VALUE value) {
   return self;
 }
 
+/* call-seq:
+ *   queue.unshift(value) -> queue
+ *
+ * Adds the given value to the queue's beginning. If the queue is capped and
+ * full, the call will block until a value is removed from the queue.
+ * 
+ * @param value [any] value to be added to the queue
+ * @return [Queue] self
+ */
+
 VALUE Queue_unshift(VALUE self, VALUE value) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -170,6 +217,22 @@ VALUE Queue_shift_block(Queue_t *queue) {
   return value;
 }
 
+/* call-seq:
+ *   queue.shift -> value
+ *   queue.shift(true) -> value
+ *   queue.pop -> value
+ *   queue.pop(true) -> value
+ *   queue.deq -> value
+ *   queue.deq(true) -> value
+ *
+ * Removes the first value in the queue and returns it. If the optional nonblock
+ * parameter is true, the operation is non-blocking. In non-blocking mode, if
+ * the queue is empty, a ThreadError exception is raised. In blocking mode, if
+ * the queue is empty, the call will block until an item is added to the queue.
+ *
+ * @return [any] first value in queue
+ */
+
 VALUE Queue_shift(int argc,VALUE *argv, VALUE self) {
   int nonblock = argc && RTEST(argv[0]);
   Queue_t *queue;
@@ -180,6 +243,14 @@ VALUE Queue_shift(int argc,VALUE *argv, VALUE self) {
     Queue_shift_block(queue);
 }
 
+/* call-seq:
+ *   queue.delete(value) -> queue
+ *
+ * Removes the given value from the queue.
+ *
+ * @return [Queue] self
+ */
+
 VALUE Queue_delete(VALUE self, VALUE value) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -192,6 +263,16 @@ VALUE Queue_delete(VALUE self, VALUE value) {
   return self;
 }
 
+/* call-seq:
+ *   queue.cap(capacity) -> queue
+ *
+ * Sets the capacity for the queue to the given value. If 0 or nil is given, the
+ * queue becomes uncapped.
+ *
+ * @param cap [Integer, nil] new capacity
+ * @return [Queue] self
+ */
+
 VALUE Queue_cap(VALUE self, VALUE cap) {
   unsigned int new_capacity = NUM2UINT(cap);
   Queue_t *queue;
@@ -206,6 +287,14 @@ VALUE Queue_cap(VALUE self, VALUE cap) {
   return self;
 }
 
+/* call-seq:
+ *   queue.capped? -> bool
+ *
+ * Returns true if the queue is capped.
+ *
+ * @return [boolean] is the queue capped
+ */
+
 VALUE Queue_capped_p(VALUE self) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -213,6 +302,14 @@ VALUE Queue_capped_p(VALUE self) {
   return queue->capacity ? INT2FIX(queue->capacity) : Qnil;
 }
 
+/* call-seq:
+ *   queue.clear -> queue
+ *
+ * Removes all values from the queue.
+ *
+ * @return [Queue] self
+ */
+
 VALUE Queue_clear(VALUE self) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -230,6 +327,16 @@ long Queue_len(VALUE self) {
   return queue->values.count;
 }
 
+/* call-seq:
+ *   queue.shift_each { |value| do_something(value) } -> queue
+ *
+ * Iterates over all values in the queue, removing each item and passing it to
+ * the given block.
+ *
+ * @yield [any] value passed to the given block
+ * @return [Queue] self
+ */
+
 VALUE Queue_shift_each(VALUE self) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -239,6 +346,14 @@ VALUE Queue_shift_each(VALUE self) {
   return self;
 }
 
+/* call-seq:
+ *   queue.shift_all -> array
+ *
+ * Returns all values currently in the queue, clearing the queue.
+ *
+ * @return [Array] all values
+ */
+
 VALUE Queue_shift_all(VALUE self) {
   Queue_t *queue;
   VALUE result;
@@ -250,6 +365,16 @@ VALUE Queue_shift_all(VALUE self) {
   return result;
 }
 
+/* call-seq:
+ *   queue.flush_waiters -> queue
+ *
+ * Flushes all fibers currently blocked waiting to remove items from the queue,
+ * resuming them with the given value.
+ *
+ * @param value [any] value to resome all waiting fibers with
+ * @return [Queue] self
+ */
+
 VALUE Queue_flush_waiters(VALUE self, VALUE value) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -260,8 +385,18 @@ VALUE Queue_flush_waiters(VALUE self, VALUE value) {
 
     Fiber_make_runnable(fiber, value);
   }
+
+  return self;
 }
 
+/* call-seq:
+ *   queue.empty? -> bool
+ *
+ * Returns true if the queue is empty.
+ *
+ * @return [boolean]
+ */
+
 VALUE Queue_empty_p(VALUE self) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -269,6 +404,15 @@ VALUE Queue_empty_p(VALUE self) {
   return (!queue->values.count) ? Qtrue : Qfalse;
 }
 
+/* call-seq:
+ *   queue.pending? -> bool
+ *
+ * Returns true if any fibers are currently waiting to remove items from the
+ * queue.
+ *
+ * @return [boolean]
+ */
+
 VALUE Queue_pending_p(VALUE self) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -276,6 +420,15 @@ VALUE Queue_pending_p(VALUE self) {
   return (queue->shift_queue.count) ? Qtrue : Qfalse;
 }
 
+/* call-seq:
+ *   queue.num_waiting -> integer
+ *
+ * Returns the number of fibers currently waiting to remove items from the
+ * queue.
+ *
+ * @return [Integer]
+ */
+
 VALUE Queue_num_waiting(VALUE self) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -283,6 +436,15 @@ VALUE Queue_num_waiting(VALUE self) {
   return INT2FIX(queue->shift_queue.count);
 }
 
+/* call-seq:
+ *   queue.size -> integer
+ *   queue.length -> integer 
+ *
+ * Returns the number of values currently in the queue.
+ *
+ * @return [Integer] number of values in the queue
+ */
+
 VALUE Queue_size_m(VALUE self) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -290,6 +452,14 @@ VALUE Queue_size_m(VALUE self) {
   return INT2FIX(queue->values.count);
 }
 
+/* call-seq:
+ *   queue.closed? -> bool
+ *
+ * Returns true if the queue has been closed.
+ *
+ * @return [boolean]
+ */
+
 VALUE Queue_closed_p(VALUE self) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -297,6 +467,16 @@ VALUE Queue_closed_p(VALUE self) {
   return (queue->closed) ? Qtrue : Qfalse;
 }
 
+/* call-seq:
+ *   queue.close -> queue
+ *
+ * Marks the queue as closed. Any fibers currently waiting on the queue are
+ * resumed with a `nil` value. After the queue is closed, trying to remove items
+ * from the queue will cause a `ClosedQueueError` to be raised.
+ *
+ * @return [Queue] self
+ */
+
 VALUE Queue_close(VALUE self) {
   Queue_t *queue;
   GetQueue(self, queue);
@@ -319,6 +499,7 @@ void Init_Queue(void) {
   cClosedQueueError = rb_const_get(rb_cObject, rb_intern("ClosedQueueError"));
   cThreadError = rb_const_get(rb_cObject, rb_intern("ThreadError"));
 
+  /* Queue implements a FIFO queue. */
   cQueue = rb_define_class_under(mPolyphony, "Queue", rb_cObject);
   rb_define_alloc_func(cQueue, Queue_allocate);
 

data/ext/polyphony/ring_buffer.c

@@ -10,7 +10,6 @@ void ring_buffer_init(ring_buffer *buffer) {
 }
 
 void ring_buffer_free(ring_buffer *buffer) {
-  // printf("ring_buffer_free ring_buffer: %p entries: %p\n", buffer, buffer->entries);
   free(buffer->entries);
 }
 

data/ext/polyphony/runqueue.c

@@ -15,7 +15,14 @@ inline void runqueue_mark(runqueue_t *runqueue) {
 }
 
 inline void runqueue_push(runqueue_t *runqueue, VALUE fiber, VALUE value, int reschedule) {
-  if (reschedule) runqueue_ring_buffer_delete(&runqueue->entries, fiber);
+  if (reschedule) {
+    if (IS_EXCEPTION(value))
+      runqueue_ring_buffer_delete(&runqueue->entries, fiber);
+    else {
+      int exception_scheduled = runqueue_ring_buffer_delete_if_not_exception(&runqueue->entries, fiber);
+      if (exception_scheduled) return;
+    }
+  }
   runqueue_ring_buffer_push(&runqueue->entries, fiber, value);
   if (runqueue->entries.count > runqueue->high_watermark)
     runqueue->high_watermark = runqueue->entries.count;

data/ext/polyphony/runqueue_ring_buffer.c

@@ -87,6 +87,19 @@ inline void runqueue_ring_buffer_delete(runqueue_ring_buffer *buffer, VALUE fibe
   }
 }
 
+inline int runqueue_ring_buffer_delete_if_not_exception(runqueue_ring_buffer *buffer, VALUE fiber) {
+  for (unsigned int i = 0; i < buffer->count; i++) {
+    unsigned int idx = (buffer->head + i) % buffer->size;
+    if (buffer->entries[idx].fiber == fiber) {
+      if (IS_EXCEPTION(buffer->entries[idx].value)) return 1;
+
+      runqueue_ring_buffer_delete_at(buffer, idx);
+      return 0;
+    }
+  }
+  return 0;
+}
+
 inline int runqueue_ring_buffer_index_of(runqueue_ring_buffer *buffer, VALUE fiber) {
   for (unsigned int i = 0; i < buffer->count; i++) {
     unsigned int idx = (buffer->head + i) % buffer->size;

data/ext/polyphony/runqueue_ring_buffer.h

@@ -27,8 +27,9 @@ void runqueue_ring_buffer_unshift(runqueue_ring_buffer *buffer, VALUE fiber, VAL
 void runqueue_ring_buffer_push(runqueue_ring_buffer *buffer, VALUE fiber, VALUE value);
 
 void runqueue_ring_buffer_delete(runqueue_ring_buffer *buffer, VALUE fiber);
+int runqueue_ring_buffer_delete_if_not_exception(runqueue_ring_buffer *buffer, VALUE fiber);
 int runqueue_ring_buffer_index_of(runqueue_ring_buffer *buffer, VALUE fiber);
 
 void runqueue_ring_buffer_migrate(runqueue_ring_buffer *src, runqueue_ring_buffer *dest, VALUE fiber);
 
-#endif /* RUNQUEUE_RING_BUFFER_H */
+#endif /* RUNQUEUE_RING_BUFFER_H */

data/ext/polyphony/socket_extensions.c

@@ -1,9 +1,13 @@
 #include "polyphony.h"
 
+/* :nop-doc: */
+
 VALUE Socket_send(VALUE self, VALUE msg, VALUE flags) {
   return Backend_send(BACKEND(), self, msg, flags);
 }
 
+/* :nop-doc: */
+
 VALUE Socket_write(int argc, VALUE *argv, VALUE self) {
   VALUE ary = rb_ary_new_from_values(argc, argv);
   VALUE result = Backend_sendv(BACKEND(), self, ary, INT2FIX(0));
@@ -11,6 +15,8 @@ VALUE Socket_write(int argc, VALUE *argv, VALUE self) {
   return result;
 }
 
+/* :nop-doc: */
+
 VALUE Socket_double_chevron(VALUE self, VALUE msg) {
   Backend_send(BACKEND(), self, msg, INT2FIX(0));
   return self;

data/ext/polyphony/thread.c

@@ -8,6 +8,8 @@ ID ID_ivar_main_fiber;
 ID ID_ivar_terminated;
 ID ID_stop;
 
+/* :nop-doc: */
+
 static VALUE Thread_setup_fiber_scheduling(VALUE self) {
   rb_ivar_set(self, ID_ivar_main_fiber, rb_fiber_current());
   return self;
@@ -17,6 +19,15 @@ inline void schedule_fiber(VALUE self, VALUE fiber, VALUE value, int prioritize)
   Backend_schedule_fiber(self, rb_ivar_get(self, ID_ivar_backend), fiber, value, prioritize);
 }
 
+/* call-seq:
+ *   thread.unschedule_fiber(fiber)
+ *
+ * Removes the given fiber from the thread's runqueue.
+ * 
+ * @param fiber [Fiber] fiber to unschedule
+ * @return [Thread] self
+ */
+
 VALUE Thread_fiber_unschedule(VALUE self, VALUE fiber) {
   Backend_unschedule_fiber(rb_ivar_get(self, ID_ivar_backend), fiber);
   return self;
@@ -34,28 +45,49 @@ inline void Thread_schedule_fiber_with_priority(VALUE self, VALUE fiber, VALUE v
   // schedule_fiber(self, fiber, value, 1);
 }
 
+/* call-seq:
+ *   thread.switch_fiber()
+ *
+ * Switches to the next fiber in the thread's runqueue.
+ * 
+ * @return [void]
+ */
+
 VALUE Thread_switch_fiber(VALUE self) {
   return Backend_switch_fiber(rb_ivar_get(self, ID_ivar_backend));
 }
 
+/* @!visibility private */
+
 VALUE Thread_fiber_schedule_and_wakeup(VALUE self, VALUE fiber, VALUE resume_obj) {
   if (fiber != Qnil) {
     Thread_schedule_fiber_with_priority(self, fiber, resume_obj);
   }
 
-  if (Backend_wakeup(rb_ivar_get(self, ID_ivar_backend)) == Qnil) {
+  VALUE backend = rb_ivar_get(self, ID_ivar_backend);
+  if (Backend_wakeup(backend) == Qnil) {
     // we're not inside Backend_poll, so we just do a switchpoint
-    Thread_switch_fiber(self);
+    Backend_switch_fiber(backend);
   }
 
   return self;
 }
 
+/* @!visibility private */
+
 VALUE Thread_debug(VALUE self) {
   rb_ivar_set(self, rb_intern("@__debug__"), Qtrue);
   return self;
 }
 
+/* call-seq:
+ *   Thread.backend
+ *
+ * Returns the backend for the current thread.
+ * 
+ * @return [Polyphony::Backend] backend for the current thread
+ */
+
 VALUE Thread_class_backend(VALUE _self) {
   return rb_ivar_get(rb_thread_current(), ID_ivar_backend);
 }

data/lib/polyphony/adapters/process.rb

@@ -13,7 +13,7 @@ module Polyphony
       # process is killed.
       #
       # @param cmd [String, nil] command to spawn
-      # @param &block [Proc] block to fork
+      # @yield [] block to fork
       # @return [void]
       def watch(cmd = nil, &block)
         terminated = nil
@@ -24,6 +24,11 @@ module Polyphony
         kill_process(pid) unless terminated || pid.nil?
       end
 
+      # Kills the given pid, waiting for it to terminate, with a timeout of 5
+      # seconds.
+      #
+      # @param pid [Integer] pid
+      # @return [void]
       def kill_process(pid)
         cancel_after(5) do
           kill_and_await('TERM', pid)
@@ -34,6 +39,11 @@ module Polyphony
 
       private
 
+      # Kills the given process with given signal, waiting for it to terminate.
+      #
+      # @param sig [String, Symbol, Integer] signal to use
+      # @param pid [Integer] pid
+      # @return [void]
       def kill_and_await(sig, pid)
         ::Process.kill(sig, pid)
         Polyphony.backend_waitpid(pid)

data/lib/polyphony/adapters/sequel.rb

@@ -11,7 +11,7 @@ module Polyphony
     # Initializes the connection pool.
     #
     # @param db [any] db to connect to
-    # @opts [Hash] connection pool options
+    # @paral opts [Hash] connection pool options
     def initialize(db, opts = OPTS)
       super
       max_size = Integer(opts[:max_connections] || 4)

data/lib/polyphony/core/channel.rb

@@ -8,6 +8,8 @@ module Polyphony
   class Channel < Polyphony::Queue
     alias_method :receive, :shift
 
+    # Closes the channel, resuming any fibers waiting on the channel with
+    # a Polyphony::MoveOn exception
     def close
       flush_waiters(Polyphony::MoveOn.new)
     end

data/lib/polyphony/core/debug.rb

@@ -32,7 +32,7 @@ module Polyphony
       # If an IO instance is given, events are dumped to it instead.
       #
       # @param io [IO, nil] IO instance
-      # @param &block [Proc] event handler block
+      # @yield [Hash] event handler block
       # @return [void]
       def start_event_firehose(io = nil, &block)
         Thread.backend.trace_proc = firehose_proc(io, block)

data/lib/polyphony/core/global_api.rb

@@ -10,8 +10,8 @@ module Polyphony
     # 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
+    # @param interval [Number] delay in seconds before running the given block
+    # @yield [] block to run
     # @return [Fiber] spun fiber
     def after(interval, &block)
       spin do
@@ -56,8 +56,8 @@ module Polyphony
     #   end
     #
     # @param interval [Number] timout in seconds
-    # @param with_exception: [Class, Exception] exception or exception class
-    # @param &block [Proc] block to execute
+    # @param with_exception [Class, Exception] exception or exception class
+    # @yield [Fiber] block to execute
     # @return [any] block's return value
     def cancel_after(interval, with_exception: Polyphony::Cancel, &block)
       if block.arity > 0
@@ -70,7 +70,7 @@ module Polyphony
     # Spins up a new fiber.
     #
     # @param tag [any] optional tag for the new fiber
-    # @param &block [Proc] fiber block
+    # @yield [any] fiber block
     # @return [Fiber] new fiber
     def spin(tag = nil, &block)
       Fiber.current.spin(tag, caller, &block)
@@ -81,9 +81,9 @@ module Polyphony
     # 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
+    # @param rate [Number, nil] loop rate (times per second)
+    # @param interval [Number, nil] interval between consecutive iterations in seconds
+    # @yield [any] code to run
     # @return [Fiber] new fiber
     def spin_loop(tag = nil, rate: nil, interval: nil, &block)
       if rate || interval
@@ -98,7 +98,7 @@ module Polyphony
     # Runs the given code, then waits for any child fibers of the current fibers
     # to terminate.
     #
-    # @param &block [Proc] code to run
+    # @yield [any] code to run
     # @return [any] given block's return value
     def spin_scope(&block)
       raise unless block
@@ -114,7 +114,7 @@ module Polyphony
     # consecutive iterations.
     #
     # @param interval [Number] interval between consecutive iterations in seconds
-    # @param &block [Proc] block to run
+    # @yield [any] block to run
     # @return [void]
     def every(interval, &block)
       Polyphony.backend_timer_loop(interval, &block)
@@ -160,8 +160,8 @@ module Polyphony
     #   end
     #
     # @param interval [Number] timout in seconds
-    # @param with_value: [any] return value in case of timeout
-    # @param &block [Proc] block to execute
+    # @param with_value [any] return value in case of timeout
+    # @yield [Fiber] block to execute
     # @return [any] block's return value
     def move_on_after(interval, with_value: nil, &block)
       if block.arity > 0
@@ -189,9 +189,9 @@ module Polyphony
     # 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
+    # @param args [Array] positional parameters
+    # @param opts [Hash] named parameters
+    # @yield [any] given block
     # @return [void]
     def supervise(*args, **opts, &block)
       Fiber.current.supervise(*args, **opts, &block)
@@ -220,10 +220,10 @@ module Polyphony
     # `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
+    # @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)
+    # @yield [] code to run
     # @return [void]
     def throttled_loop(rate = nil, **opts, &block)
       throttler = Polyphony::Throttler.new(rate || opts)
@@ -244,14 +244,15 @@ module Polyphony
     #
     # @param interval [Number] timeout interval in seconds
     # @param exception [Exception, Class, Array<class, message>] exception spec
-    # @param &block [Proc] block to run
+    # @yield [Fiber] block to run
     # @return [any] block's return value
     def cancel_after_with_optional_reset(interval, exception, &block)
+      fiber = Fiber.current
       canceller = spin do
-        sleep interval
+        Polyphony.backend_sleep(interval)
         exception = cancel_exception(exception)
         exception.raising_fiber = Fiber.current
-        fiber.cancel(exception).await
+        fiber.cancel(exception)
       end
       block.call(canceller)
     ensure
@@ -289,13 +290,13 @@ module Polyphony
     #
     # @param interval [Number] timeout interval in seconds
     # @param value [any] return value in case of timeout
-    # @param &block [Proc] code to run
+    # @yield [Fiber] 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
+        fiber.move_on(value)
       end
       block.call(canceller)
     rescue Polyphony::MoveOn => e