polyphony 0.36 → 0.42

data/docs/api-reference.md

@@ -1,11 +0,0 @@
----
-layout: page
-title: API Reference
-description: Lorem ipsum
-has_children: true
-alphabetical_order: true
-section: true
-has_toc: false
-nav_order: 5
-section_link: /api-reference/exception
----

data/docs/api-reference/gyro-async.md

@@ -1,57 +0,0 @@
----
-layout: page
-title: Gyro::Async
-parent: API Reference
-permalink: /api-reference/gyro-async/
----
-# Gyro::Async
-
-`Gyro::Async` encapsulates a libev [async
-watcher](http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_async_code_how_to_wake_up_an),
-allowing thread-safe synchronisation and signalling. `Gyro::Async` watchers are
-used both directly and indirectly in Polyphony to implement
-[queues](../gyro-queue/), await fibers and threads, and auxiliary features such
-as [thread pools](../polyphony-threadpool/).
-
-A `Gyro::Async` watcher instance is shared across two or more fibers (across one
-or more threads), where one fiber waits to be signalled by calling
-`Gyro::Async#await`, and one or more other fibers do the signalling by calling
-`Gyro::Async#signal`:
-
-```ruby
-async = Gyro::Async.new
-spin do
-  sleep 1
-  async.signal
-end
-
-async.await
-```
-
-The signalling of async watchers is compressed, which means that multiple
-invocations of `Gyro::Async#signal` before the event loop can continue will
-result the watcher being signalled just a single time.
-
-In addition to signalling, the async watcher can also be used to transfer an
-arbitrary value to the awaitng fiber. See `#signal` for an example.
-
-## Instance methods
-
-### #await → object
-
-Blocks the current thread until the watcher is signalled.
-
-### #initialize
-
-Initializes the watcher instance.
-
-### #signal(value = nil) → async
-
-Signals the watcher, causing the fiber awaiting the watcher to become runnable
-and be eventually resumed with the given value.
-
-```ruby
-async = Gyro::Async.new
-spin { async.signal('foo') }
-async.await #=> 'foo'
-```

data/docs/api-reference/gyro-child.md

@@ -1,29 +0,0 @@
----
-layout: page
-title: Gyro::Child
-parent: API Reference
-permalink: /api-reference/gyro-child/
----
-# Gyro::Child
-
-`Gyro::Child` encapsulates a libev [child
-watcher](http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_child_code_watch_out_for_pro),
-used for waiting for a child process to terminate. A `Gyro::Child` watcher
-instance can be used for low-level control of child processes, instead of using
-more high-level APIs such `Process.wait` etc.
-
-## Instance methods
-
-### #await → [pid, exitcode]
-
-Blocks the current thread until the watcher is signalled. The return value is an
-array containing the child's pid and the exit code.
-
-```ruby
-pid = Polyphony.fork { sleep 1 }
-Gyro::Child.new(pid).await #=> [pid, 0]
-```
-
-### #initialize(pid)
-
-Initializes the watcher instance with the given pid

data/docs/api-reference/gyro-queue.md

@@ -1,44 +0,0 @@
----
-layout: page
-title: Gyro::Queue
-parent: API Reference
-permalink: /api-reference/gyro-queue/
----
-# Gyro::Queue
-
-`Gyro::Queue` implements a polyphonic (fiber-aware) queue that can store 0 or
-more items of any data types. Adding an item to the queue never blocks.
-Retrieving an item from the queue will block if the queue is empty.
-`Gyro::Queue` is both fiber-safe and thread-safe. This means multiple fibers
-from multiple threads can concurrently interact with the same queue.
-`Gyro::Queue` is used pervasively across the Polyphony code base for
-synchronisation and fiber control.
-
-## Instance methods
-
-### #&lt;&lt;(object) → queue<br>#push(object) → queue
-
-Adds an item to the queue.
-
-### #clear → queue
-
-Removes all items currently in the queue.
-
-### #empty? → true or false
-
-Returns true if the queue is empty. Otherwise returns false.
-
-### #initialize
-
-Initializes an empty queue.
-
-### #shift → object<br>#pop → object
-
-Retrieves an item from the queue. If the queue is empty, `#shift` blocks until
-an item is added to the queue or until interrupted. Multiple fibers calling
-`#shift` are served in a first-ordered first-served manner.
-
-### #shift_each → [*object]<br>#shift_each({ block }) → queue
-
-Removes and returns all items currently in the queue. If a block is given, it
-will be invoked for each item.

data/docs/api-reference/gyro-timer.md

@@ -1,51 +0,0 @@
----
-layout: page
-title: Gyro::Timer
-parent: API Reference
-permalink: /api-reference/gyro-timer/
----
-# Gyro::Timer
-
-`Gyro::Timer` encapsulates a libev [timer
-watcher](http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_timer_code_relative_and_opti),
-allowing waiting a certain amount of time before proceeding with an operation.
-Watchers can be either one-time timers or recurring timers. The Polyphony API
-provides various APIs that use timer watchers for timeouts, throttled
-operations, and sleeping.
-
-## Instance methods
-
-### #await → object
-
-Blocks the current thread until the timer has elapsed. For recurrent timers,
-`#await` will block until the next timer period has elapsed, as specified by the
-`repeat` argument given to `#initialize`.
-
-### #initialize(after, repeat)
-
-Initializes the watcher instance. The `after` argument gives the time duration
-in seconds before the timer has elapsed. The `repeat` argument gives the time
-period for recurring timers, or `0` for non-recurring timers.
-
-### #stop
-
-Stops an active recurring timer. Recurring timers stay active (from the point of
-view of the event loop) even after the timer period has elapsed. Calling `#stop`
-marks the timer as inactive and cleans up associated resources. This should
-normally be done inside an `ensure` block:
-
-```ruby
-def repeat(period)
-  timer = Gyro::Timer.new(period, period)
-  loop do
-    timer.await
-    yield
-  end
-ensure
-  timer.stop
-end
-
-repeat(10) { puts Time.now }
-```
-
-There's no need to call `#stop` for non-recurring timers.

data/docs/api-reference/gyro.md

@@ -1,25 +0,0 @@
----
-layout: page
-title: Gyro
-parent: API Reference
-permalink: /api-reference/gyro/
----
-# Gyro
-
-`Gyro` is the subsystem in charge of the low-level functionality in Polyphony.
-It contains all of the different event watcher classes, as well as other
-low-level constructs such as `Gyro::Queue`, a fiber-aware queue implementation,
-used pervasively across the Polyphony code base.
-
-While most Polyphony-based applications do not normally need to interact
-directly with the `Gyro` classes, more advanced applications and libraries may
-use those classes to enhance Polyphony and create custom concurrency patterns.
-
-## Classes
-
-- [`Gyro::Async`](../gyro-async/) - async event watcher
-- [`Gyro::Child`](../gyro-child/) - child process event watcher
-- [`Gyro::IO`](../gyro-io/) - IO event watcher
-- [`Gyro::Queue`](../gyro-queue/) - fiber-aware queue
-- [`Gyro::Signal`](../gyro-signal/) - signal event watcher
-- [`Gyro::Timer`](../gyro-timer/) - timer event watcher

data/docs/getting-started.md

@@ -1,10 +0,0 @@
----
-layout: page
-title: Getting Started
-description: Lorem ipsum
-has_children: true
-section: true
-has_toc: false
-nav_order: 2
-section_link: /getting-started/installing
----

data/docs/main-concepts.md

@@ -1,10 +0,0 @@
----
-layout: page
-title: Main Concepts
-description: Lorem ipsum
-has_children: true
-section: true
-has_toc: false
-nav_order: 3
-section_link: /main-concepts/concurrency
----

data/docs/user-guide.md

@@ -1,10 +0,0 @@
----
-layout: page
-title: User Guide
-description: Lorem ipsum
-has_children: true
-section: true
-has_toc: false
-nav_order: 4
-section_link: /user-guide/all-about-timers
----

data/examples/core/forever_sleep.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-require 'bundler/setup'
-require 'polyphony'
-
-trap('TERM') do
-  # do nothing
-end
-
-trap('INT') do
-  # do nothing
-end
-
-puts "go to sleep"
-begin
-  sleep
-ensure
-  puts "done sleeping"
-end

data/ext/gyro/async.c

@@ -1,148 +0,0 @@
-#include "gyro.h"
-
-struct Gyro_Async {
-  struct  ev_async ev_async;
-  struct  ev_loop *ev_loop;
-  int     active;
-  VALUE   self;
-  VALUE   fiber;
-  VALUE   value;
-  VALUE   selector;
-};
-
-VALUE cGyro_Async = Qnil;
-
-static void Gyro_Async_mark(void *ptr) {
-  struct Gyro_Async *async = ptr;
-  if (async->fiber != Qnil) {
-    rb_gc_mark(async->fiber);
-  }
-  if (async->value != Qnil) {
-    rb_gc_mark(async->value);
-  }
-  if (async->selector != Qnil) {
-    rb_gc_mark(async->selector);
-  }
-}
-
-static void Gyro_Async_free(void *ptr) {
-  struct Gyro_Async *async = ptr;
-  if (async->active) {
-    ev_clear_pending(async->ev_loop, &async->ev_async);
-    ev_async_stop(async->ev_loop, &async->ev_async);
-  }
-  xfree(async);
-}
-
-static size_t Gyro_Async_size(const void *ptr) {
-  return sizeof(struct Gyro_Async);
-}
-
-static const rb_data_type_t Gyro_Async_type = {
-    "Gyro_Async",
-    {Gyro_Async_mark, Gyro_Async_free, Gyro_Async_size,},
-    0, 0, 0
-};
-
-static VALUE Gyro_Async_allocate(VALUE klass) {
-  struct Gyro_Async *async = ALLOC(struct Gyro_Async);
-  return TypedData_Wrap_Struct(klass, &Gyro_Async_type, async);
-}
-
-inline void Gyro_Async_activate(struct Gyro_Async *async) {
-  if (async->active) return;
-
-  async->active = 1;
-  async->fiber = rb_fiber_current();
-  async->selector = Thread_current_event_selector();
-  async->ev_loop = Gyro_Selector_ev_loop(async->selector);
-  Gyro_Selector_add_active_watcher(async->selector, async->self);
-  ev_async_start(async->ev_loop, &async->ev_async);
-}
-
-inline void Gyro_Async_deactivate(struct Gyro_Async *async) {
-  if (!async->active) return;
-
-  ev_async_stop(async->ev_loop, &async->ev_async);
-  Gyro_Selector_remove_active_watcher(async->selector, async->self);
-  async->active = 0;
-  async->ev_loop = 0;
-  async->selector = Qnil;
-  async->fiber = Qnil;
-  async->value = Qnil;
-}
-
-void Gyro_Async_callback(struct ev_loop *ev_loop, struct ev_async *ev_async, int revents) {
-  struct Gyro_Async *async = (struct Gyro_Async*)ev_async;
-
-  Fiber_make_runnable(async->fiber, async->value);
-  Gyro_Async_deactivate(async);
-}
-
-#define GetGyro_Async(obj, async) \
-  TypedData_Get_Struct((obj), struct Gyro_Async, &Gyro_Async_type, (async))
-
-static VALUE Gyro_Async_initialize(VALUE self) {
-  struct Gyro_Async *async;
-  GetGyro_Async(self, async);
-
-  async->self = self;
-  async->fiber = Qnil;
-  async->value = Qnil;
-  async->selector = Qnil;
-  async->active = 0;
-  async->ev_loop = 0;
-
-  ev_async_init(&async->ev_async, Gyro_Async_callback);
-
-  return Qnil;
-}
-
-static VALUE Gyro_Async_signal(int argc, VALUE *argv, VALUE self) {
-  struct Gyro_Async *async;
-  GetGyro_Async(self, async);
-
-  if (!async->active) {
-    // printf("signal called before await\n");
-    return Qnil;
-  }
-
-  async->value = (argc == 1) ? argv[0] : Qnil;
-  ev_async_send(async->ev_loop, &async->ev_async);
-
-  return Qnil;
-}
-
-VALUE Gyro_Async_await(VALUE self) {
-  struct Gyro_Async *async;
-  GetGyro_Async(self, async);
-
-  Gyro_Async_activate(async);
-  VALUE ret = Gyro_switchpoint();
-  Gyro_Async_deactivate(async);
-
-  TEST_RESUME_EXCEPTION(ret);
-  RB_GC_GUARD(ret);
-  return ret;
-}
-
-VALUE Gyro_Async_await_no_raise(VALUE self) {
-  struct Gyro_Async *async;
-  GetGyro_Async(self, async);
-
-  Gyro_Async_activate(async);
-  VALUE ret = Gyro_switchpoint();
-  Gyro_Async_deactivate(async);
-  
-  RB_GC_GUARD(ret);
-  return ret;
-}
-
-void Init_Gyro_Async() {
-  cGyro_Async = rb_define_class_under(mGyro, "Async", rb_cData);
-  rb_define_alloc_func(cGyro_Async, Gyro_Async_allocate);
-
-  rb_define_method(cGyro_Async, "initialize", Gyro_Async_initialize, 0);
-  rb_define_method(cGyro_Async, "signal", Gyro_Async_signal, -1);
-  rb_define_method(cGyro_Async, "await", Gyro_Async_await, 0);
-}

data/ext/gyro/child.c

@@ -1,127 +0,0 @@
-#include "gyro.h"
-
-struct Gyro_Child {
-  struct  ev_child ev_child;
-  struct  ev_loop *ev_loop;
-  int     active;
-  int     pid;
-  VALUE   self;
-  VALUE   fiber;
-  VALUE   selector;
-};
-
-static VALUE cGyro_Child = Qnil;
-
-static void Gyro_Child_mark(void *ptr) {
-  struct Gyro_Child *child = ptr;
-  if (child->fiber != Qnil) {
-    rb_gc_mark(child->fiber);
-  }
-  if (child->selector != Qnil) {
-    rb_gc_mark(child->selector);
-  }
-}
-
-static void Gyro_Child_free(void *ptr) {
-  struct Gyro_Child *child = ptr;
-  if (child->active) {
-    ev_clear_pending(child->ev_loop, &child->ev_child);
-    ev_child_stop(child->ev_loop, &child->ev_child);
-  }
-  xfree(child);
-}
-
-static size_t Gyro_Child_size(const void *ptr) {
-  return sizeof(struct Gyro_Child);
-}
-
-static const rb_data_type_t Gyro_Child_type = {
-    "Gyro_Child",
-    {Gyro_Child_mark, Gyro_Child_free, Gyro_Child_size,},
-    0, 0, 0
-};
-
-static VALUE Gyro_Child_allocate(VALUE klass) {
-  struct Gyro_Child *child = ALLOC(struct Gyro_Child);
-  return TypedData_Wrap_Struct(klass, &Gyro_Child_type, child);
-}
-
-inline void Gyro_Child_activate(struct Gyro_Child *child) {
-  if (child->active) return;
-
-  child->active = 1;
-  child->fiber = rb_fiber_current();
-  child->selector = Thread_current_event_selector();
-  child->ev_loop = Gyro_Selector_ev_loop(child->selector);
-  Gyro_Selector_add_active_watcher(child->selector, child->self);
-  ev_child_start(child->ev_loop, &child->ev_child);
-}
-
-inline void Gyro_Child_deactivate(struct Gyro_Child *child) {
-  if (!child->active) return;
-
-  ev_child_stop(child->ev_loop, &child->ev_child);
-  Gyro_Selector_remove_active_watcher(child->selector, child->self);
-  child->active = 0;
-  child->ev_loop = 0;
-  child->selector = Qnil;
-  child->fiber = Qnil;
-}
-
-VALUE Gyro_Child_resume_value(struct ev_child *ev_child) {
-  int exit_status = ev_child->rstatus >> 8; // weird, why should we do this?
-
-  return rb_ary_new_from_args(
-    2, INT2NUM(ev_child->rpid), INT2NUM(exit_status)
-  );
-}
-
-void Gyro_Child_callback(struct ev_loop *ev_loop, struct ev_child *ev_child, int revents) {
-  struct Gyro_Child *child = (struct Gyro_Child*)ev_child;
-
-  VALUE resume_value = Gyro_Child_resume_value(ev_child);
-  Fiber_make_runnable(child->fiber, resume_value);
-
-  Gyro_Child_deactivate(child);
-}
-
-#define GetGyro_Child(obj, child) \
-  TypedData_Get_Struct((obj), struct Gyro_Child, &Gyro_Child_type, (child))
-
-static VALUE Gyro_Child_initialize(VALUE self, VALUE pid) {
-  struct Gyro_Child *child;
-
-  GetGyro_Child(self, child);
-
-  child->self     = self;
-  child->fiber    = Qnil;
-  child->selector = Qnil;
-  child->pid      = NUM2INT(pid);
-  child->active   = 0;
-  child->ev_loop  = 0;
-  
-  ev_child_init(&child->ev_child, Gyro_Child_callback, child->pid, 0);
-
-  return Qnil;
-}
-
-static VALUE Gyro_Child_await(VALUE self) {
-  struct Gyro_Child *child;
-  GetGyro_Child(self, child);
-
-  Gyro_Child_activate(child);
-  VALUE ret = Gyro_switchpoint();
-  Gyro_Child_deactivate(child);
-
-  TEST_RESUME_EXCEPTION(ret);
-  RB_GC_GUARD(ret);
-  return ret;
-}
-
-void Init_Gyro_Child() {
-  cGyro_Child = rb_define_class_under(mGyro, "Child", rb_cData);
-  rb_define_alloc_func(cGyro_Child, Gyro_Child_allocate);
-
-  rb_define_method(cGyro_Child, "initialize", Gyro_Child_initialize, 1);
-  rb_define_method(cGyro_Child, "await", Gyro_Child_await, 0);
-}