polyphony 0.20 → 0.21

data/docs/technical-overview/fiber-scheduling.md

@@ -1,56 +1,24 @@
-# Fiber Scheduling
+# How Fibers are Scheduled
 
-Ruby provides two mechanisms for transferring control between fibers:
-`Fiber#resume` / `Fiber.yield` and `Fiber#transfer`. The first is inherently asymmetric and is famously used
-for implementing generators and [resumable enumerators](https://blog.appsignal.com/2018/11/27/ruby-magic-fibers-and-enumerators-in-ruby.html).
-Another limiting factor of using resume / yield is that the root fiber can't
-yield away, limiting its usability as a resumable fiber.
+Ruby provides two mechanisms for transferring control between fibers: `Fiber#resume` / `Fiber.yield` and `Fiber#transfer`. The first is inherently asymmetric and is famously used for implementing generators and [resumable enumerators](https://blog.appsignal.com/2018/11/27/ruby-magic-fibers-and-enumerators-in-ruby.html). Another limiting factor of using resume / yield is that the root fiber can't yield away, limiting its usability as a resumable fiber.
 
-The second mechanism, using `Fiber#transfer`, is completely symmetric and allows
-use of the root fiber as a general purpose resumable execution context.
-Polyphony uses `Fiber#transfer` exclusively for scheduling fibers.
+The second mechanism, using `Fiber#transfer`, is completely symmetric and allows use of the root fiber as a general purpose resumable execution context. Polyphony uses `Fiber#transfer` exclusively for scheduling fibers.
 
 ## The Reactor Fiber
 
-Polyphony relies on [libev](http://software.schmorp.de/pkg/libev.html) for
-handling events such as I/O readiness, timers and signals. The libev event loop
-runs in a separate fiber (called the reactor fiber) and handles each event by 
-resuming the appropriate fiber using `Fiber#transfer`. The event loop will 
-continue running and scheduling fibers as long as there's active event watchers.
-When all event watchers have been deactivated, the event loop terminates and
-control is  transferred to the root fiber, which will either terminate the
-program, or go on with other work, and possibly another run of the event loop.
+Polyphony relies on [libev](http://software.schmorp.de/pkg/libev.html) for handling events such as I/O readiness, timers and signals. The libev event loop runs in a separate fiber \(called the reactor fiber\) and handles each event by resuming the appropriate fiber using `Fiber#transfer`. The event loop will continue running and scheduling fibers as long as there's active event watchers. When all event watchers have been deactivated, the event loop terminates and control is transferred to the root fiber, which will either terminate the program, or go on with other work, and possibly another run of the event loop.
 
 ## Fiber scheduling
 
-When a new fiber is created, it is in a suspended state. To start it, it needs
-to be resumed using `Fiber#transfer`. Upon performing a blocking operation, such
-as `sleep` or `gets`, an event watcher will be created, and control will be
-transferred to the reactor fiber, which will resume running the event loop. A
-fiber waiting for an event will be resumed using `Fiber#transfer` once the event
-has been received, and will continue execution until encountering another
-blocking operation, at which point it will again create an event watcher and
-transfer control back to the reactor fiber.
+When a new fiber is created, it is in a suspended state. To start it, it needs to be resumed using `Fiber#transfer`. Upon performing a blocking operation, such as `sleep` or `gets`, an event watcher will be created, and control will be transferred to the reactor fiber, which will resume running the event loop. A fiber waiting for an event will be resumed using `Fiber#transfer` once the event has been received, and will continue execution until encountering another blocking operation, at which point it will again create an event watcher and transfer control back to the reactor fiber.
 
 ## Interrupting blocking operations
 
-Sometimes it is desirable to be able to interrupt a blocking operation, such as
-waiting for a socket to be readable, or sleeping for an extended period of time.
-This is especially useful when higher-level constructs are needed for
-controlling multiple concurrent operations.
+Sometimes it is desirable to be able to interrupt a blocking operation, such as waiting for a socket to be readable, or sleeping for an extended period of time. This is especially useful when higher-level constructs are needed for controlling multiple concurrent operations.
 
-Polyphony provides the ability to interrupt a blocking operation by harnessing
-the ability to transfer values back and forth when using `Fiber#transfer`.
-Whenever a waiting fiber transfers control to the reactor fiber, the value 
-received upon being resumed is checked. If the value is an exception, it will
-be raised in the context of the waiting fiber, effectively signalling that the
-blocking operation has been unsuccessful and allowing exception handling using
-the usual mechanisms offered by Ruby, namely `rescue` and `ensure` (see also
-[exception handling](exception-handling.md)).
+Polyphony provides the ability to interrupt a blocking operation by harnessing the ability to transfer values back and forth when using `Fiber#transfer`. Whenever a waiting fiber transfers control to the reactor fiber, the value received upon being resumed is checked. If the value is an exception, it will be raised in the context of the waiting fiber, effectively signalling that the blocking operation has been unsuccessful and allowing exception handling using the usual mechanisms offered by Ruby, namely `rescue` and `ensure` \(see also [exception handling](exception-handling.md)\).
 
-Here's an siplified example of how this mechanism works when reading from an I/O
-object (the actual code for I/O reading in Polyphony is written in C and a bit
-more involved):
+Here's an siplified example of how this mechanism works when reading from an I/O object \(the actual code for I/O reading in Polyphony is written in C and a bit more involved\):
 
 ```ruby
 def read_from(io)
@@ -76,24 +44,27 @@ ensure
 end
 ```
 
-In the above example, the `wait_readable` method will normally wait indefinitely
-until the IO object has become readable. But we could interrupt it at any time
-by scheduling the corresponding fiber with an exception.
+In the above example, the `wait_readable` method will normally wait indefinitely until the IO object has become readable. But we could interrupt it at any time by scheduling the corresponding fiber with an exception.
 
 ## Deferred Operations
 
-In addition to waiting for blocking operations, Polyphony provides numerous APIs 
-for suspending and scheduling fibers:
+In addition to waiting for blocking operations, Polyphony provides numerous APIs for suspending and scheduling fibers:
+
+* `Fiber#safe_transfer(value = nil)` - transfers control to another fiber with
 
-- `Fiber#safe_transfer(value = nil)` - transfers control to another fiber with
   exception handling.
-- `Fiber#schedule(value = nil)` - schedules a fiber to be resumed once the
+
+* `Fiber#schedule(value = nil)` - schedules a fiber to be resumed once the
+
   event loop becomes idle.
-- `Kernel#snooze` - transfers control to the reactor fiber while scheduling the
+
+* `Kernel#snooze` - transfers control to the reactor fiber while scheduling the
+
   current fiber to be resumed immediately once the event loop is idle.
-- `Kernel#suspend` - suspends the current fiber indefinitely by transferring
+
+* `Kernel#suspend` - suspends the current fiber indefinitely by transferring
+
   control to the reactor fiber.
 
-In addition, a lower level API allows running arbitrary code in the context of
-the reactor loop using `Kernel#defer`. Using this API will run the given block
-the next time the event loop is idle.
+In addition, a lower level API allows running arbitrary code in the context of the reactor loop using `Kernel#defer`. Using this API will run the given block the next time the event loop is idle.
+

data/docs/user-guide/web-server.md

@@ -0,0 +1,129 @@
+# Web Server
+
+Polyphony's web server functionality offers a powerful and flexible way to
+create Ruby-based web servers and web applications. In addition to supporting
+both HTTP 1 and HTTP 2, it supports seamless Websocket upgrades (and indeed
+arbitrary protocol upgrade), TLS termination, and automatic ALPN-based protocol
+selection. In addition, it includes a Rack adapter for running Rack
+applications. Polyphony's web server offers excellent performance
+characteristics, in terms of throughput, memory consumption and scalability
+(benchmarks are forthcoming).
+
+What makes Polyphony's web server design stand out is the fact that incoming
+requests can be processed immediately upon receiving the complete headers,
+without needing to wait for the entire request body to be received. This design
+allows web applications to properly buffer uploads of large files without
+consuming large amounts of RAM, as well as reject requests without waiting for
+the entire request body.
+
+## A basic web server
+
+```ruby
+require 'polyphony/http'
+
+Polyphony::HTTP::Server.serve('0.0.0.0', 1234) do |request|
+  request.respond("Hello world!\n")
+end
+```
+
+Note that requests are handled using a callback block which takes a single
+argument. The `request` object provides the entire API for responding to the
+client.
+
+Each client connection will be handled in a separate coprocess, allowing
+concurrent processing of incoming requests.
+
+## HTTP 2 support
+
+HTTP 2 support is baked in to the server, which supports both HTTP 2 upgrades
+(for example on a non-encrypted connection) and ALPN-based protocol selection,
+in a completely effortless manner.
+
+Since HTTP 2 connections are multiplexed, allowing multiple concurrent requests
+on a single connection, each HTTP 2 stream is handled in a separate coprocess.
+
+## TLS termination
+
+TLS termination can be handled by passing a `secure_context` option to the
+server:
+
+```ruby
+require 'polyphony/http'
+require 'localhost/authority'
+
+authority = Localhost::Authority.fetch
+opts = { secure_context: authority.server_context }
+
+Polyphony::HTTP::Server.serve('0.0.0.0', 1234, opts) do |request|
+  request.respond("Hello world!\n")
+end
+```
+
+## Websockets && HTTP upgrades
+
+Polyphony's web server makes it really easy to integrate websocket communication
+with normal HTTP processing:
+
+```ruby
+require 'polyphony/http'
+require 'polyphony/websocket'
+
+ws_handler = Polyphony::Websocket.handler do |ws|
+  while (msg = ws.recv)
+    ws << "you said: #{msg}"
+  end
+end
+
+opts = {
+  upgrade: { websocket: ws_handler }
+}
+
+Polyphony::HTTP::Server.serve('0.0.0.0', 1234, opts) do |request|
+  request.respond("Hello world!\n")
+end
+```
+
+Polyphony also supports general-purpose HTTP upgrades using the same mechanism:
+
+```ruby
+require 'polyphony/http'
+
+opts = {
+  upgrade: {
+    echo: ->(conn) {
+      while (msg = conn.gets)
+        conn << "You said: #{msg}"
+      end
+    }
+  }
+}
+
+Polyphony::HTTP::Server.serve('0.0.0.0', 1234, opts) do |request|
+  request.respond("Hello world!\n")
+end
+```
+
+## Sending HTTP responses
+
+The response API provides multiple ways of responding, with or without a body,
+and enables streaming (using chunked encoding for HTTP/1.1 connections). Here's
+an example of an SSE response:
+
+```ruby
+require 'polyphony/http'
+
+def sse_response(request)
+  request.send_headers('Content-Type': 'text/event-stream')
+  move_on_after(10) {
+    loop {
+      request.send_chunk("data: #{Time.now}\n\n")
+      sleep 1
+    }
+  }
+ensure
+  request.send_chunk("retry: 0\n\n", done: true)
+end
+
+Polyphony::HTTP::Server.serve('0.0.0.0', 1234, &method(:sse_response))
+```
+

data/examples/core/01-spinning-up-coprocesses.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+# In order to automatically start the reactor, we need to require
+# `polyphony/auto_run`. Otherwise, we can just require `polyphony`
+require 'polyphony/auto_run'
+
+def nap(tag, t)
+  puts "#{Time.now} #{tag} napping for #{t} seconds..."
+  sleep t
+  puts "#{Time.now} #{tag} done napping"
+end
+
+# We launch two concurrent coprocesses, each sleeping for the given duration.
+spin { nap(:a, 1) }
+spin { nap(:b, 2) }
+
+# Having required `polyphony/auto_run`, once our program is done, the
+# libev-based event reactor is started, and runs until there's no more work left
+# for it to handle.

data/examples/core/02-awaiting-coprocesses.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony/auto_run'
+
+sleeper = spin do
+  puts 'going to sleep'
+  sleep 1
+  puts 'woke up'
+end
+
+# One way to synchronize coprocesses is by using `Coprocess#await`, which blocks
+# until the coprocess has finished running or has been interrupted.
+waiter = spin do
+  puts 'waiting for coprocess to terminate'
+  sleeper.await
+  puts 'done waiting'
+end

data/examples/core/03-interrupting.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony/auto_run'
+
+# Let's see how a long-running blocking operation can be interrupted. Polyphony
+# provides several APIs for interrupting an ongoing operation, and distinguishes
+# between two different types of interruptions: *cancel* and *move on*. A
+# *cancel* will interrupt an ongoing operation and raise an exception. A *move
+# on* will interrupt an ongoing operation without raising an exception,
+# optionally returning an arbitrary value as the result of that operation.
+
+def nap(tag, t)
+  puts "#{Time.now} #{tag} napping for #{t} seconds..."
+  sleep t
+ensure
+  puts "#{Time.now} #{tag} done napping"
+end
+
+# The Kernel#cancel_after interrupts a blocking operation by raising a
+# Polyphony::Cancel exception after the given timeout
+spin do
+  # cancel after 1 second
+  cancel_after(1) { nap(:cancel, 2) }
+rescue Polyphony::Cancel => e
+  puts "got exception: #{e}"
+end
+
+spin do
+  # move on after 1 second
+  move_on_after(1) do
+    nap(:move_on, 2)
+  end
+end

data/examples/core/04-no-auto-run.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+# Notice we require 'polyphony' and not 'polyphony/auto_run'
+require 'polyphony'
+
+def nap(tag, t)
+  puts "#{Time.now} #{tag} napping for #{t} seconds..."
+  sleep t
+  puts "#{Time.now} #{tag} done napping"
+end
+
+spin { nap(:a, 1) }
+
+# If polyphony/auto_run has not been `require`d, the reactor fiber needs to be
+# started manually. This is done by transferring control to it using `suspend`:
+suspend

data/examples/core/mem-usage.rb

@@ -0,0 +1,34 @@
+require 'fiber'
+
+def mem_usage
+  `ps -o rss #{$$}`.strip.split.last.to_i
+end
+
+def calculate_fiber_memory_cost(count)
+  GC.disable
+  rss0 = mem_usage
+  count.times { Fiber.new { sleep 1 } }
+  rss1 = mem_usage
+  GC.start
+  cost = (rss1 - rss0).to_f / count
+
+  puts "fiber memory cost: #{cost}KB"
+end
+
+calculate_fiber_memory_cost(10000)
+
+require 'bundler/setup'
+require 'polyphony'
+
+def calculate_coprocess_memory_cost(count)
+  GC.disable
+  rss0 = mem_usage
+  count.times { spin { :foo } }
+  rss1 = mem_usage
+  GC.start
+  cost = (rss1 - rss0).to_f / count
+
+  puts "coprocess memory cost: #{cost}KB"
+end
+
+calculate_coprocess_memory_cost(10000)

data/examples/core/spin_error.rb

@@ -2,7 +2,6 @@
 
 require 'bundler/setup'
 require 'polyphony/auto_run'
-require 'polyphony/extensions/backtrace'
 
 def error(t)
   raise "hello #{t}"

data/examples/core/spin_uncaught_error.rb

@@ -2,7 +2,6 @@
 
 require 'bundler/setup'
 require 'polyphony/auto_run'
-require 'polyphony/extensions/backtrace'
 
 def foo
   spin do

data/examples/core/wait_for_signal.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony/auto_run'
+
+waiter = spin do
+  puts 'Waiting for HUP'
+  Polyphony.wait_for_signal('SIGHUP')
+  puts 'Got HUP'
+end
+
+sleep 1
+puts 'Sending HUP'
+Process.kill('SIGHUP', Process.pid)

data/examples/http/http_server_graceful.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony/auto_run'
+require 'polyphony/http'
+
+opts = {
+  reuse_addr:  true,
+  dont_linger: true
+}
+
+server = spin do
+  Polyphony::HTTP::Server.serve('0.0.0.0', 1234, opts) do |req|
+    req.respond("Hello world!\n")
+  end
+end
+
+trap('SIGHUP') do
+  puts 'got hup'
+  server.interrupt
+end
+
+puts "pid: #{Process.pid}"
+puts 'Send HUP to stop gracefully'
+puts 'Listening on port 1234...'

data/examples/http/http_server_simple.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony/http'
+
+puts "pid: #{Process.pid}"
+puts 'Listening on port 1234...'
+
+Polyphony::HTTP::Server.serve('0.0.0.0', 1234) do |req|
+  req.respond("Hello world!\n")
+end

data/examples/interfaces/redis_pubsub_perf.rb

@@ -61,7 +61,7 @@ spin do
   end
 end
 
-Polyphony.trap(:int) do
+trap(:int) do
   puts 'bye...'
   exit!
 end

data/ext/gyro/async.c

@@ -3,7 +3,6 @@
 struct Gyro_Async {
   struct  ev_async ev_async;
   int     active;
-  VALUE   callback;
   VALUE   fiber;
 };
 
@@ -18,8 +17,6 @@ static size_t Gyro_Async_size(const void *ptr);
 /* Methods */
 static VALUE Gyro_Async_initialize(VALUE self);
 
-static VALUE Gyro_Async_start(VALUE self);
-static VALUE Gyro_Async_stop(VALUE self);
 static VALUE Gyro_Async_signal(VALUE self);
 static VALUE Gyro_Async_await(VALUE self);
 
@@ -31,8 +28,6 @@ void Init_Gyro_Async() {
   rb_define_alloc_func(cGyro_Async, Gyro_Async_allocate);
 
   rb_define_method(cGyro_Async, "initialize", Gyro_Async_initialize, 0);
-  rb_define_method(cGyro_Async, "start", Gyro_Async_start, 0);
-  rb_define_method(cGyro_Async, "stop", Gyro_Async_stop, 0);
   rb_define_method(cGyro_Async, "signal!", Gyro_Async_signal, 0);
   rb_define_method(cGyro_Async, "await", Gyro_Async_await, 0);
 }
@@ -51,9 +46,6 @@ static VALUE Gyro_Async_allocate(VALUE klass) {
 
 static void Gyro_Async_mark(void *ptr) {
   struct Gyro_Async *async = ptr;
-  if (async->callback != Qnil) {
-    rb_gc_mark(async->callback);
-  }
   if (async->fiber != Qnil) {
     rb_gc_mark(async->fiber);
   }
@@ -76,16 +68,11 @@ static VALUE Gyro_Async_initialize(VALUE self) {
   struct Gyro_Async *async;
   GetGyro_Async(self, async);
 
-  if (rb_block_given_p()) {
-    async->callback = rb_block_proc();
-  }
   async->fiber = Qnil;
+  async->active = 0;
 
   ev_async_init(&async->ev_async, Gyro_Async_callback);
 
-  async->active = 1;
-  ev_async_start(EV_DEFAULT, &async->ev_async);
-
   return Qnil;
 }
 
@@ -94,38 +81,15 @@ void Gyro_Async_callback(struct ev_loop *ev_loop, struct ev_async *ev_async, int
   struct Gyro_Async *async = (struct Gyro_Async*)ev_async;
 
   if (async->fiber != Qnil) {
+    ev_async_stop(EV_DEFAULT, ev_async);
     async->active = 0;
     fiber = async->fiber;
     async->fiber = Qnil;
     SCHEDULE_FIBER(fiber, 0);
   }
-  else if (async->callback != Qnil) {
-    rb_funcall(async->callback, ID_call, 1, Qtrue);
-  }
-}
-
-static VALUE Gyro_Async_start(VALUE self) {
-  struct Gyro_Async *async;
-  GetGyro_Async(self, async);
-
-  if (!async->active) {
-    ev_async_start(EV_DEFAULT, &async->ev_async);
-    async->active = 1;
-  }
-
-  return self;
-}
-
-static VALUE Gyro_Async_stop(VALUE self) {
-  struct Gyro_Async *async;
-  GetGyro_Async(self, async);
-
-  if (async->active) {
-    ev_async_stop(EV_DEFAULT, &async->ev_async);
-    async->active = 0;
+  else {
+    ev_async_stop(EV_DEFAULT, ev_async);
   }
-
-  return self;
 }
 
 static VALUE Gyro_Async_signal(VALUE self) {

data/ext/gyro/child.c

@@ -5,7 +5,6 @@ struct Gyro_Child {
   int     active;
   int     pid;
   VALUE   self;
-  VALUE   callback;
   VALUE   fiber;
 };
 
@@ -20,8 +19,6 @@ static size_t Gyro_Child_size(const void *ptr);
 /* Methods */
 static VALUE Gyro_Child_initialize(VALUE self, VALUE pid);
 
-static VALUE Gyro_Child_start(VALUE self);
-static VALUE Gyro_Child_stop(VALUE self);
 static VALUE Gyro_Child_await(VALUE self);
 
 void Gyro_Child_callback(struct ev_loop *ev_loop, struct ev_child *child, int revents);
@@ -32,8 +29,6 @@ void Init_Gyro_Child() {
   rb_define_alloc_func(cGyro_Child, Gyro_Child_allocate);
 
   rb_define_method(cGyro_Child, "initialize", Gyro_Child_initialize, 1);
-  rb_define_method(cGyro_Child, "start", Gyro_Child_start, 0);
-  rb_define_method(cGyro_Child, "stop", Gyro_Child_stop, 0);
   rb_define_method(cGyro_Child, "await", Gyro_Child_await, 0);
 }
 
@@ -51,9 +46,6 @@ static VALUE Gyro_Child_allocate(VALUE klass) {
 
 static void Gyro_Child_mark(void *ptr) {
   struct Gyro_Child *child = ptr;
-  if (child->callback != Qnil) {
-    rb_gc_mark(child->callback);
-  }
   if (child->fiber != Qnil) {
     rb_gc_mark(child->fiber);
   }
@@ -80,7 +72,6 @@ static VALUE Gyro_Child_initialize(VALUE self, VALUE pid) {
   GetGyro_Child(self, child);
 
   child->self     = self;
-  child->callback = Qnil;
   child->fiber    = Qnil;
   child->pid      = NUM2INT(pid);
   child->active   = 0;
@@ -105,39 +96,6 @@ void Gyro_Child_callback(struct ev_loop *ev_loop, struct ev_child *ev_child, int
     child->fiber = Qnil;
     SCHEDULE_FIBER(fiber, 1, resume_value);
   }
-  else if (child->callback != Qnil) {
-    rb_funcall(child->callback, ID_call, 1, resume_value);
-  }
-}
-
-static VALUE Gyro_Child_start(VALUE self) {
-  struct Gyro_Child *child;
-  GetGyro_Child(self, child);
-
-  if (rb_block_given_p()) {
-    child->callback = rb_block_proc();
-  }
-
-  if (!child->active) {
-    ev_child_start(EV_DEFAULT, &child->ev_child);
-    child->active = 1;
-    Gyro_add_watcher_ref(self);
-  }
-
-  return self;
-}
-
-static VALUE Gyro_Child_stop(VALUE self) {
-  struct Gyro_Child *child;
-  GetGyro_Child(self, child);
-
-  if (child->active) {
-    ev_child_stop(EV_DEFAULT, &child->ev_child);
-    child->active = 0;
-    Gyro_del_watcher_ref(self);
-  }
-
-  return self;
 }
 
 static VALUE Gyro_Child_await(VALUE self) {