polyphony 0.19 → 0.20

data/Rakefile

@@ -6,15 +6,15 @@ require "rake/clean"
 # frozen_string_literal: true
 
 require "rake/extensiontask"
-Rake::ExtensionTask.new("ev_ext") do |ext|
-  ext.ext_dir = "ext/ev"
+Rake::ExtensionTask.new("gyro_ext") do |ext|
+  ext.ext_dir = "ext/gyro"
 end
 
 task :default => [:compile, :test]
 task :test do
-  Dir.glob('./test/test_*.rb').each { |file| require(file) }
+  exec 'ruby test/run.rb'
 end
 
-# task default: %w[compile]# spec rubocop]
+task default: %w[compile]
 
 CLEAN.include "**/*.o", "**/*.so", "**/*.bundle", "**/*.jar", "pkg", "tmp"

data/TODO.md

@@ -1,26 +1,53 @@
 # Roadmap:
 
-## 0.20 Full Rack adapter implementation
+## 0.20.1
+
+- Cull, edit and annotate examples
+- Work better mechanism supervising multiple coprocesses (`when_done` feels a
+  bit hacky)
+
+## 0.21 REPL usage, coprocess introspection, monitoring
+
+- Implement `move_on_after(1, with: nil) { ... }`
+- Implement `Coprocess.await` for waiting on multiple coprocesses without
+  starting them in a supervisor, will also necessitate adding `Supervisor#add`
+- Implement `Coprocess#location`
+- Implement `Coprocess#alive?`
+- Implement `Coprocess#caller` - points to coprocess that called the coprocess
+- Implement `Coprocess.list` - a list of running coprocesses
+
+## 0.22 Full Rack adapter implementation
+
+- Homogenize HTTP 1 and HTTP 2 headers - upcase ? downcase ?
+- Rewrite agent code to use sequential API (like I did for server)
+- Streaming bodies for HTTP client
+
+  ```ruby
+  def download_doc
+    response = Polyphony::HTTP::Agent.get('https://acme.com/doc.pdf')
+    File.open('doc.pdf', 'wb+') do |f|
+      response.each { |chunk| f << chunk } # streaming body
+    end
+  end
+  ```
 
-- follow Rack specification (doesn't have to include stuff like streaming or
-  websockets)
 - find some demo Rack apps and test with Polyphony
 
-## 0.21 Working Rails application
+## 0.23 Working Sinatra application
 
 - app with database access (postgresql)
 - benchmarks!
 
-## 0.22 Support for multi-threading
+## 0.24 Support for multi-threading
 
 - Separate event loop for each thread
 
-## 0.23 Testing
+## 0.25 Testing
 
 - test thread / thread_pool modules
 - report test coverage
 
-## 0.24 Documentation
+## 0.26 Documentation
 
 # DNS
 
@@ -56,3 +83,4 @@ puts "listening on port 5300"
 Prior art:
 
 - https://github.com/socketry/async-dns
+

data/bin/poly

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require_relative('../lib/polyphony/http')
+
+app_path = ARGV.first || './config.ru'
+app = Polyphony::HTTP::Rack.load(app_path)
+opts = { reuse_addr: true, dont_linger: true }
+
+puts "listening on port 1234"
+puts "pid: #{Process.pid}"
+Polyphony::HTTP::Server.serve('0.0.0.0', 1234, opts, &app)

data/docs/getting-started/getting-started.md

@@ -3,7 +3,7 @@
 ## Installing
 
 ```bash
-$ gem install nuclear
+$ gem install polyphony
 ```
 
 ## Tutorial

data/docs/summary.md

@@ -7,3 +7,6 @@
 * [Installing](getting-started/getting-started.md)
 * [Tutorial](getting-started/tutorial.md)
 
+## Technical overview
+
+* [Error handling](technical-overview/error-handling.md)

data/docs/technical-overview/exception-handling.md

@@ -0,0 +1,94 @@
+# Exception Handling in a Multi-Fiber Environment
+
+Ruby employs a pretty robust exception handling mechanism. An raised exception
+will bubble up the call stack until a suitable exception handler is found, based
+on the exception's class. In addition, the exception will include a stack trace
+showing the execution path from the exception's locus back to the program's
+entry point. Unfortunately, when exceptions are raised while switching between
+fibers, stack traces will only include partial information. Here's a simple
+demonstration:
+
+*fiber_exception.rb*
+```ruby
+require 'fiber'
+
+def fail!
+  raise 'foobar'
+end
+
+f = Fiber.new do
+  Fiber.new do
+    fail!
+  end.transfer
+end
+
+f.transfer
+```
+
+Running the above program will give us:
+
+```
+Traceback (most recent call last):
+        1: from fiber_exception.rb:9:in `block (2 levels) in <main>'
+fiber_exception.rb:4:in `fail!': foobar (RuntimeError)
+```
+
+So, the stack trace includes two frames: the exception's locus on line 4 and the
+call site at line 9. But we have no information on how we got to line 9. Let's
+imagine if we had more complete information about the sequence of execution. In
+fact, what is missing is information about how the different fibers were
+created. If we had that, our stack trace would have looked something like this:
+
+```
+Traceback (most recent call last):
+        4: from fiber_exception.rb:13:in `<main>'
+        3: from fiber_exception.rb:7:in `Fiber.new'
+        2: from fiber_exception.rb:8:in `Fiber.new'
+        1: from fiber_exception.rb:9:in `block (2 levels) in <main>'
+fiber_exception.rb:4:in `fail!': foobar (RuntimeError)
+```
+
+In order to achieve this, Polyphony patches `Fiber.new` to keep track of the
+call stack at the moment the fiber was created, as well as the fiber from which
+the call happened. In addition, Polyphony patches `Exception#backtrace` in order
+to synthesize a complete stack trace based on the call stack information stored
+for the current fiber. This is done recursively through the chain of fibers
+leading up to the current location. What we end up with is a record of the
+entire sequence of (possibly intermittent) execution leading up to the point
+where the exception was raised.
+
+In addition, the backtrace is sanitized to remove stack frames originating from
+the Polyphony code itself, which hides away the Polyphony plumbing and lets
+developers concentrate on their own code. The sanitizing of exception backtraces
+can be disabled by setting the `Exception.__disable_sanitized_backtrace__` flag:
+
+```ruby
+Exception.__disable_sanitized_backtrace__ = true
+...
+```
+
+## Cleaning up after exceptions
+
+A major issue when handling exceptions is cleaning up - freeing up resources
+that have been allocated, cancelling ongoing operations, etc. Polyphony allows
+using the normal `ensure` statement for cleaning up. Have a look at Polyphony's
+implementation of `Kernel#sleep`:
+
+```ruby
+def sleep(duration)
+  timer = Gyro::Timer.new(duration, 0)
+  timer.await
+ensure
+  timer.stop
+end
+```
+
+This method creates a one-shot timer with the given duration and then suspends
+the current fiber, waiting for the timer to fire and then resume the fiber.
+While the awaiting fiber is suspended, other operations might be going on, which
+might interrupt the `sleep` operation by scheduling the awaiting fiber with an
+exception, for example a `MoveOn` or a `Cancel` exception. For this reason, we
+need to *ensure* that the timer will be stopped, regardless of whether it has
+fired or not. We call `timer.stop` inside an ensure block, thus ensuring that
+the timer will have stopped once the awaiting fiber has resumed, even if it has
+not fired.

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

@@ -0,0 +1,99 @@
+# Fiber Scheduling
+
+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 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.
+
+## 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.
+
+## 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.
+
+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):
+
+```ruby
+def read_from(io)
+  loop do
+    result = IO.readnonblock(8192, exception: false)
+    if result == :wait_readable
+      wait_readable(io)
+    else
+      return result
+    end
+  end
+end
+
+def wait_readable(io)
+  watcher = Gyro::IO.new(io, :read)
+  # transfer control to event loop
+  result = $__reactor_fiber__.transfer
+  # got control back, check if result is an exception
+  raise result if result.is_a?(Exception)
+  result
+ensure
+  watcher.active = false
+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.
+
+## Deferred Operations
+
+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
+  exception handling.
+- `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
+  current fiber to be resumed immediately once the event loop is idle.
+- `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.

data/examples/core/cancel.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
 require 'bundler/setup'
-require 'polyphony'
+require 'polyphony/auto_run'
 
-puts "going to sleep..."
-cancel_after(1) do
-  sleep(60)
+begin
+  puts 'going to sleep...'
+  cancel_after(1) do
+    sleep(60)
+  end
+rescue Polyphony::Cancel
+  puts 'cancelled'
 end

data/examples/core/channel_echo.rb

@@ -1,41 +1,42 @@
 # frozen_string_literal: true
 
 require 'bundler/setup'
-require 'polyphony'
+require 'polyphony/auto_run'
 
-def echo(rchan, wchan)
-  puts "start echoer"
-  while msg = rchan.receive
-    wchan << "you said: #{msg}"
+def echo(cin, cout)
+  puts 'start echoer'
+  while (msg = cin.receive)
+    cout << "you said: #{msg}"
   end
 ensure
-  puts "echoer stopped"
+  puts 'echoer stopped'
 end
 
-chan1, chan2 = Polyphony::Channel.new, Polyphony::Channel.new
+chan1, chan2 = 2.times.map { Polyphony::Channel.new }
 
-echoer = spin { echo(chan1, chan2) }
+spin { echo(chan1, chan2) }
 
 spin do
-  puts "start receiver"
-  while msg = chan2.receive
+  puts 'start receiver'
+  while (msg = chan2.receive)
     puts msg
     $main.resume if msg =~ /world/
   end
 ensure
-  puts "receiver stopped"
+  puts 'receiver stopped'
 end
 
 $main = spin do
+  puts 'start main'
   t0 = Time.now
-  puts "send hello"
-  chan1 << "hello"
-  puts "send world"
-  chan1 << "world"
+  puts 'send hello'
+  chan1 << 'hello'
+  puts 'send world'
+  chan1 << 'world'
 
   suspend
-  
-  puts "closing channels"
+
+  puts 'closing channels'
   chan1.close
   chan2.close
   puts "done #{Time.now - t0}"

data/examples/core/defer.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony/auto_run'
+
+defer do
+  puts 'two'
+  defer { puts 'four' }
+  puts 'three'
+end
+
+puts 'one'

data/examples/core/enumerator.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 require 'bundler/setup'
-require 'polyphony'
+require 'polyphony/auto_run'
 
-enum = [1,2,3].each
+enum = [1, 2, 3].each
 
 spin do
-  while e = enum.next rescue nil
+  while (e = enum.next rescue nil)
     puts e
-    sleep 1
+    sleep 0.1
   end
 end

data/examples/core/fiber_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+f = Fiber.new do
+  raise 'hi'
+end
+
+f.resume
+
+puts 'done'

data/examples/core/fiber_error_with_backtrace.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'fiber'
+
+# This is an experiment to see if we could provide better backtraces for
+# exceptions raised in fibers. Our approach is to monkey-patch Fiber.new so as
+# to keep track of the caller stack trace and calling fiber. We also
+# monkey-patch Exception#backtrace to calculate the full backtrace based on the
+# fiber in which the exception was raised. The benefit of this approach is that
+# there's no need to sanitize the backtrace (remove stack frames related to the
+# backtrace calculation).
+class Fiber
+  attr_writer :__calling_fiber__, :__caller__
+
+  class << self
+    alias_method :orig_new, :new
+    def new(&block)
+      calling_fiber = Fiber.current
+      fiber_caller = caller
+      orig_new(&block).tap do |f|
+        f.__calling_fiber__ = calling_fiber
+        f.__caller__ = fiber_caller
+      end
+    end
+  end
+
+  def caller
+    @__caller__ ||= []
+    if @__calling_fiber__
+      @__caller__ + @__calling_fiber__.caller
+    else
+      @__caller__
+    end
+  end
+end
+
+class Exception
+  alias_method :orig_initialize, :initialize
+
+  def initialize(*args)
+    @__raising_fiber__ = Fiber.current
+    orig_initialize(*args)
+  end
+
+  alias_method :orig_backtrace, :backtrace
+  def backtrace
+    unless @backtrace_called
+      @backtrace_called = true
+      return orig_backtrace
+    end
+
+    if @__raising_fiber__
+      backtrace = orig_backtrace || []
+      backtrace + @__raising_fiber__.caller
+    else
+      orig_backtrace
+    end
+  end
+end
+
+def foo
+  Fiber.new do
+    bar
+  end.resume
+end
+
+def bar
+  Fiber.new do
+    raise 'baz'
+  end.resume
+end
+
+foo