polyphony 0.19 → 0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e79ca0a896fc0b5feffa415e44b9229074d145c2142155caf47f243b6c85078d
-  data.tar.gz: 6aa58f404376be6e6d472e588be4349d6fcaeb3031e5786a0a5ffe0970d9fa5d
+  metadata.gz: ca0e1fc13842ec06d7272fb19e0edc1621eddb4a007ff9b97e07794e60a9d814
+  data.tar.gz: 78cab004907a41474ff1920cbb9f5aceb6851797e6805f9c16256f3d48457eff
 SHA512:
-  metadata.gz: accbeddc33fd7b1de40f411a421c445bc847e8ee744d98dcd1cf20b0a8fe3fc5c880ca373a020b026a0d68aac9cfc74f179bde2c3cebd1b0733a5adbe2b435b0
-  data.tar.gz: 7549c7ac4528bf4747049fb6c4eecbfe500f6aeed3586f8181bbf21506f8725ebb51c1170e369f15b24c748d59be439a2d076d26de1e5b1a1b6b34ae3e344ade
+  metadata.gz: 96de0a203333388768a41d8c81c333e80b9ab20ebf001b744e1a5d0dd8e6bb036ebc5b4d4abe7a85b4016e264afd4f3609cc8aeed9c8bbfc401010966c8090f2
+  data.tar.gz: 30507005291c431dd277d30829f6e4c219d2b176a41eef111caadcc8975adaeb335dc4104dc08cb65c58649863bd7a39d21565adee55a795c58d84894419026d

data/.gitignore

@@ -52,4 +52,4 @@ build-iPhoneSimulator/
 test.rb
 .vscode
 
-lib/ev_ext.bundle
+lib/gyro_ext.bundle

data/.rubocop.yml

@@ -7,6 +7,7 @@ AllCops:
     - 'test/**/*.rb'
     - 'examples/**/*.rb'
     - 'Gemfile*'
+    - lib/polyphony/http/agent.rb
 
 Style/LambdaCall:
   Enabled: false
@@ -46,4 +47,89 @@ Style/NumericPredicate:
   Enabled: false
 
 Style/TrivialAccessors:
-  Enabled: false
+  Enabled: false
+
+Style/MethodMissingSuper:
+  Enabled: false
+
+Style/GlobalVars:
+  Exclude:
+    - lib/polyphony/auto_run.rb
+    - lib/polyphony/extensions/core.rb
+    - examples/**/*.rb
+
+Style/ClassVars:
+  Exclude:
+    - lib/polyphony/core/coprocess.rb
+
+Layout/AlignHash:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Naming/AccessorMethodName:
+  Exclude:
+    - lib/polyphony/http/server/http1.rb
+    - lib/polyphony/http/server/http2_stream.rb
+    - examples/**/*.rb
+
+Naming/MethodName:
+  Exclude:
+    - test/test_signal.rb
+
+Lint/HandleExceptions:
+  Exclude:
+    - lib/polyphony/http/server/http1.rb
+    - lib/polyphony/http/server/http2.rb
+    - lib/polyphony/http/server.rb
+    - examples/**/*.rb
+
+Metrics/MethodLength:
+  Exclude:
+    - lib/polyphony/http/server/rack.rb
+    - lib/polyphony/extensions/io.rb
+    - test/**/*.rb
+    - examples/**/*.rb
+
+Metrics/ModuleLength:
+  Exclude:
+    - lib/polyphony/extensions/core.rb
+    - examples/**/*.rb
+
+Metrics/ClassLength:
+  Exclude:
+    - lib/polyphony/http/server/http1.rb
+    - test/**/*.rb
+    - examples/**/*.rb
+
+Style/RegexpLiteral:
+  Enabled: false
+
+Style/RescueModifier:
+  Exclude:
+    - lib/polyphony/auto_run.rb
+    - test/**/*.rb
+    - examples/**/*.rb
+
+Style/Documentation:
+  Exclude:
+    - test/**/*.rb
+    - examples/**/*.rb
+
+Style/FormatString:
+  Exclude:
+    - test/**/*.rb
+    - examples/**/*.rb
+
+Style/FormatStringToken:
+  Exclude:
+    - test/**/*.rb
+    - examples/**/*.rb
+
+Naming/UncommunicativeMethodParamName:
+  Exclude:
+    - test/**/*.rb
+    - examples/**/*.rb
+
+Security/MarshalLoad:
+  Exclude:
+    - examples/**/*.rb

data/CHANGELOG.md

@@ -1,3 +1,38 @@
+0.20 2019-11-27
+---------------
+
+* Refactor and improve CancelScope, ResourcePool
+* Reimplement cancel_after, move_on_after using plain timers
+* Use Timer#await instead of Timer#start in Pulser
+* Rename Fiber.main to Fiber.root
+* Replace use of defer with proper fiber scheduling
+* Improve Coprocess resume, interrupt, cancel methods
+* Cleanup code using Rubocop
+* Update and cleanup examples
+* Remove fiber pool
+* Rename `CoprocessInterrupt` to `Interrupt`
+* Fix ResourcePool, Mutex, Thread, ThreadPool
+* Fix coprocess message passing behaviour
+* Add HTTP::Request#consume API
+* Use bundler 2.x
+* Remove separate parse loop fiber in HTTP 1, HTTP 2 adapters
+* Fix handling of exceptions in coprocesses
+* Implement synthetic, sanitized exception backtrace showing control flow across
+  fibers
+* Fix channels
+* Fix HTTP1 connection shutdown and error states
+* Workaround for IO#read without length
+* Rename `next_tick` to `defer`
+* Fix race condition in firing of deferred items, use linked list instead of
+  array for deferred items
+* Rename `EV` module to `Gyro`
+* Keep track of main fiber when forking
+* Add `<<` alias for `send_chunk` in HTTP::Request
+* Implement Socket#accept in C
+* Better conformance of rack adapter to rack spec (WIP)
+* Fix HTTP1 adapter
+* Better support for debugging with ruby-debug-ide (WIP)
+
 0.19 2019-06-12
 ---------------
 

data/Gemfile.lock

@@ -1,14 +1,17 @@
 PATH
   remote: .
   specs:
-    polyphony (0.19)
+    polyphony (0.20)
       http-2 (= 0.10.0)
       http_parser.rb (= 0.6.0)
       modulation (~> 0.25)
+      rack
 
 GEM
   remote: https://rubygems.org/
   specs:
+    ansi (1.5.0)
+    builder (3.2.3)
     hiredis (0.6.3)
     http-2 (0.10.0)
     http_parser.rb (0.6.0)
@@ -16,17 +19,24 @@ GEM
       mime-types (~> 3.0)
       multi_xml (>= 0.5.2)
     localhost (1.1.4)
-    mime-types (3.2.2)
+    mime-types (3.3)
       mime-types-data (~> 3.2015)
-    mime-types-data (3.2019.0331)
+    mime-types-data (3.2019.1009)
     minitest (5.11.3)
-    modulation (0.25)
+    minitest-reporters (1.4.2)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
+    modulation (0.34)
     multi_xml (0.6.0)
     pg (1.1.3)
-    rake (12.3.2)
+    rack (2.0.7)
+    rake (13.0.1)
     rake-compiler (1.0.5)
       rake
     redis (4.1.0)
+    ruby-progressbar (1.10.1)
     websocket (1.2.8)
 
 PLATFORMS
@@ -37,6 +47,7 @@ DEPENDENCIES
   httparty (= 0.17.0)
   localhost (= 1.1.4)
   minitest (= 5.11.3)
+  minitest-reporters (= 1.4.2)
   pg (= 1.1.3)
   polyphony!
   rake-compiler (= 1.0.5)
@@ -44,4 +55,4 @@ DEPENDENCIES
   websocket (= 1.2.8)
 
 BUNDLED WITH
-   1.17.2
+   2.1.0.pre.2

data/README.md

@@ -12,7 +12,7 @@
 > other.
 
 **Note**: Polyphony is experimental software. It is designed to work with recent
-versions of Ruby (2.5 and newer) and supports Linux and MacOS only.
+versions of Ruby (2.6 and newer) and supports Linux and MacOS only.
 
 ## What is Polyphony
 
@@ -32,7 +32,8 @@ takes care of context-switching automatically whenever a blocking call like
 ## Features
 
 - **Full-blown, integrated, high-performance HTTP 1 / HTTP 2 / WebSocket server
-  with TLS/SSL termination and automatic ALPN protocol selection**.
+  with TLS/SSL termination, automatic ALPN protocol selection, and body
+  streaming**.
 - Co-operative scheduling of concurrent tasks using Ruby fibers.
 - High-performance event reactor for handling I/O events and timers.
 - Natural, sequential programming style that makes it easy to reason about
@@ -41,15 +42,29 @@ takes care of context-switching automatically whenever a blocking call like
   coprocesses, supervisors, cancel scopes, throttling, resource pools etc.
 - Code can use native networking classes and libraries, growing support for
   third-party gems such as `pg` and `redis`.
+- Use stdlib classes such as `TCPServer`, `TCPSocket` and 
 - HTTP 1 / HTTP 2 client agent with persistent connections.
 - Competitive performance and scalability characteristics, in terms of both
   throughput and memory consumption.
 
+## Why you should not use Polyphony
+
+- Polyphony does weird things to Ruby, like patching methods like `IO.read`,
+  `Kernel#sleep`, and `Timeout.timeout` so they'll work concurrently without
+  using threads.
+- Error backtraces might look weird.
+- There's currently no support for threads - any IO operations in threads will
+  likely cause a bad crash.
+- Debugging might be confusing or not work at all.
+- The API is currently unstable.
+
 ## Prior Art
 
 Polyphony draws inspiration from the following, in no particular order:
 
 * [nio4r](https://github.com/socketry/nio4r/) and [async](https://github.com/socketry/async)
+  (Polyphony's C-extension code is largely a spinoff of
+  [nio4r's](https://github.com/socketry/nio4r/tree/master/ext))
 * [EventMachine](https://github.com/eventmachine/eventmachine)
 * [Trio](https://trio.readthedocs.io/)
 * [Erlang supervisors](http://erlang.org/doc/man/supervisor.html) (and actually,
@@ -61,16 +76,18 @@ Polyphony draws inspiration from the following, in no particular order:
 $ gem install polyphony
 ```
 
+Or add it to your Gemfile, you know the drill.
+
 ## Getting Started
 
 Polyphony is designed to help you write high-performance, concurrent code in
-Ruby. It does so by turning every call which might block, such as `sleep` or
-`read` into a concurrent operation, which yields control to an event reactor.
-The reactor, in turn, may schedule other operations once they can be resumed. In
-that manner, multiple ongoing operations may be processed concurrently.
+Ruby, without using threads. It does so by turning every call which might block,
+such as `Kernel#sleep` or `IO#read` into a concurrent operation, which yields
+control to an event reactor. The reactor, in turn, may schedule other operations
+once they can be resumed. In that manner, multiple ongoing operations may be
+processed concurrently.
 
-There are multiple ways to start a concurrent operation, the most common of
-which is `Kernel#spin`:
+The simplest way to start a concurrent operation is using `Kernel#spin`:
 
 ```ruby
 require 'polyphony'
@@ -89,38 +106,38 @@ end
 ```
 
 In the above example, both `sleep` calls will be executed concurrently, and thus
-the program will take approximately only 1 second to execute. Note the lack of
-any boilerplate relating to concurrency. Each `spin` block starts a
-*coprocess*, and is executed in sequential manner.
-
-> **Coprocesses - the basic unit of concurrency**: In Polyphony, concurrent
-> operations take place inside coprocesses. A `Coprocess` is executed on top of
-> a `Fiber`, which allows it to be suspended whenever a blocking operation is
-> called, and resumed once that operation has been completed. Coprocesses offer
-> significant advantages over threads - they consume only about 10KB, switching
-> between them is much faster than switching threads, and literally millions of
-> them can be spinned off without affecting performance*. Besides, Ruby does not
-> yet allow parallel execution of threads (courtesy of the Ruby GVL).
-> 
-> \* *This is a totally unsubstantiated claim which has not been proved in
-> practice*.
+the program will take approximately only 1 second to execute. Note how the logic
+flow inside each `spin` block is purely sequential, and how the concurrent
+nature of the two blocks is expressed simply and cleanly.
+
+## Coprocesses - Polyphony's basic unit of concurrency
+
+In Polyphony, concurrent operations take place inside coprocesses. A `Coprocess`
+is executed on top of a `Fiber`, which allows it to be suspended whenever a
+blocking operation is called, and resumed once that operation has been
+completed. Coprocesses offer significant advantages over threads - they consume
+only about 10KB, switching between them is much faster than switching threads,
+and literally millions of them can be spinned off without affecting
+performance*. Besides, Ruby does not yet allow parallel execution of threads
+(courtesy of the Ruby GVL).
+
+\* *This is a totally unsubstantiated claim and has not been proven in practice*.
 
 ## An echo server in Polyphony
 
-To take matters further, let's see how networking can be done using Polyphony.
-Here's a bare-bones echo server written using Polyphony:
+Let's now examine how networking is done using Polyphony. Here's a bare-bones
+echo server written using Polyphony:
 
 ```ruby
 require 'polyphony'
 
 server = TCPServer.open(1234)
 while client = server.accept
-  # coproc starts a new coprocess on a separate fiber
-  spin {
-    while data = client.read rescue nil
-      client.write(data)
+  spin do
+    while (data = client.gets)
+      client << data
     end
-  }
+  end
 end
 ```
 
@@ -132,12 +149,159 @@ This example demonstrates several features of Polyphony:
 - The only hint of the code being concurrent is the use of `Kernel#spin`,
   which starts a new coprocess on a dedicated fiber. This allows serving
   multiple clients at once. Whenever a blocking call is issued, such as
-  `#accept` or `#read`, execution is *yielded* to the event loop, which will
-  resume only those coprocesses which are ready to be resumed.
+  `#accept` or `#read`, execution is *yielded* to the event reactor loop, which 
+  will resume only those coprocesses which are ready to be resumed.
 - Exception handling is done using the normal Ruby constructs `raise`, `rescue`
   and `ensure`. Exceptions never go unhandled (as might be the case with Ruby
-  threads), and must be dealt with explicitly. An unhandled exception will cause
-  the Ruby process to exit.
+  threads), and must be dealt with explicitly. An unhandled exception will by
+  default cause the Ruby process to exit.
+
+## Additional concurrency constructs
+
+In order to facilitate writing concurrent code, Polyphony provides additional
+mechanisms that make it easier to create and control concurrent tasks.
+
+### Cancel scopes
+
+Cancel scopes, an idea borrowed from Python's
+[Trio](https://trio.readthedocs.io/) library, are used to cancel the execution
+of one or more coprocesses. The most common use of cancel scopes is a for 
+implementing a timeout for the completion of a task. Any blocking operation can
+be cancelled. The programmer may choose to raise a `Cancel` exception when an
+operation has been cancelled, or alternatively to move on without any exception.
+
+Cancel scopes are typically started using `Kernel#cancel_after` and 
+`Kernel#move_on_after` for cancelling with or without an exception,
+respectively. Cancel scopes will take a block of code to execute and run it, 
+providing a reference to the cancel scope:
+
+```ruby
+puts "going to sleep (but really only for 1 second)..."
+cancel_after(1) do
+  sleep(60)
+end
+```
+
+Patterns like closing a connection after X seconds of activity are greatly
+facilitated by timeout-based cancel scopes, which can be easily reset:
+
+```ruby
+def echoer(client)
+  # close connection after 10 seconds of inactivity
+  move_on_after(10) do |scope|
+    scope.when_cancelled { puts "closing connection due to inactivity" }
+    loop do
+      data = client.read
+      scope.reset_timeout
+      client.write
+    end
+  end
+  client.close
+end
+```
+
+Cancel scopes may also be manually cancelled by calling `CancelScope#cancel!`
+at any time:
+
+```ruby
+def echoer(client)
+  move_on_after(60) do |scope|
+    loop do
+      data = client.read
+      scope.cancel! if data == 'stop'
+      client.write
+    end
+  end
+  client.close
+end
+```
+
+### Resource pools
+
+A resource pool is used to control access to one or more shared, usually
+identical resources. For example, a resource pool can be used to control
+concurrent access to database connections, or to limit concurrent
+requests to an external API:
+
+```ruby
+# up to 5 concurrent connections
+Pool = Polyphony::ResourcePool.new(limit: 5) {
+  # the block sets up the resource
+  PG.connect(...)
+}
+
+1000.times {
+  spin {
+    Pool.acquire { |db| p db.query('select 1') }
+  }
+}
+```
+
+You can also call arbitrary methods on the resource pool, which will be
+delegated to the resource using `#method_missing`:
+
+```ruby
+# up to 5 concurrent connections
+Pool = Polyphony::ResourcePool.new(limit: 5) {
+  # the block sets up the resource
+  PG.connect(...)
+}
+
+1000.times {
+  spin { p Pool.query('select pg_sleep(0.01);') }
+}
+```
+
+### Supervisors
+
+A supervisor is used to control one or more coprocesses. It can be used to
+start, stop, restart and await the completion of multiple coprocesses. It is 
+normally started using `Kernel#supervise`:
+
+```ruby
+supervise { |s|
+  s.spin { sleep 1 }
+  s.spin { sleep 2 }
+  s.spin { sleep 3 }
+}
+puts "done sleeping"
+```
+
+The `Kernel#supervise` method will await the completion of all supervised 
+coprocesses. If any supervised coprocess raises an error, the supervisor will
+automatically cancel all other supervised coprocesses.
+
+### Throttlers
+
+A throttler is a mechanism for controlling the speed of an arbitrary task,
+such as sending of emails, or crawling a website. A throttler is normally
+created using `Kernel#throttle` or `Kernel#throttled_loop`, and can even be used 
+to throttle operations across multiple coprocesses:
+
+```ruby
+server = Polyphony::Net.tcp_listen(1234)
+
+# a shared throttler, up to 10 times per second
+throttler = throttle(rate: 10)
+
+while client = server.accept
+  spin do
+    throttler.call do
+      while data = client.read
+        client.write(data)
+      end
+    end
+  end
+end
+```
+
+`Kernel#throttled_loop` can be used to run throttled infinite loops:
+
+```ruby
+throttled_loop(3) do
+  STDOUT << '.'
+end
+```
 
 ## Going further
 
@@ -202,7 +366,7 @@ class IOWatcher
 end
 ```
 
-> **Running a high-performance event loop**: Polyphony  runs a libev-based event
+> **Running a high-performance event loop**: Polyphony runs a libev-based event
 > loop that watches events such as IO-readiness, elapsed timers, received
 > signals and other asynchronous happenings, and uses them to control fiber
 > execution. The event loop itself is run on a separate fiber, allowing the main
@@ -220,109 +384,6 @@ class IOWatcher
 end
 ```
 
-### Additional concurrency constructs
-
-In order to facilitate writing concurrent code, Polyphony provides additional
-constructs that make it easier to create and control concurrent tasks.
-
-`CancelScope` - an abstraction used to cancel the execution of one or more
-coprocesses or supervisors. It usually works by defining a timeout for the 
-completion of a task. Any blocking operation can be cancelled, including
-a coprocess or a supervisor. The developer may choose to cancel with or without
-an exception with `cancel` or `move_on`, respectively. Cancel scopes are
-typically started using `Kernel.cancel_after` and `Kernel.move_on`:
-
-```ruby
-def echoer(client)
-  # cancel after 10 seconds if inactivity
-  move_on_after(10) { |scope|
-    loop {
-      data = client.read
-      scope.reset_timeout
-      client.write
-    }
-  }
-}
-```
-
-`ResourcePool` - a class used to control access to shared resources. It can be
-used to control concurrent access to database connections, or to limit 
-concurrent requests to an external API:
-
-```ruby
-# up to 5 concurrent connections
-Pool = Polyphony::ResourcePool.new(limit: 5) {
-  # the block sets up the resource
-  PG.connect(...)
-}
-
-1000.times {
-  spin {
-    Pool.acquire { |db| p db.query('select 1') }
-  }
-}
-```
-
-You can also call arbitrary methods on the resource pool, which will be
-delegated to the resource using `#method_missing`:
-
-```ruby
-# up to 5 concurrent connections
-Pool = Polyphony::ResourcePool.new(limit: 5) {
-  # the block sets up the resource
-  PG.connect(...)
-}
-
-1000.times {
-  spin { p Pool.query('select 1') }
-}
-```
-
-`Supervisor` - a class used to control one or more `Coprocess`s. It can be used
-to start, stop and restart multiple coprocesses. A supervisor can also be
-used for awaiting the completion of multiple coprocesses. It is usually started
-using `Kernel.supervise`:
-
-```ruby
-supervise { |s|
-  s.spin { sleep 1 }
-  s.spin { sleep 2 }
-  s.spin { sleep 3 }
-}
-puts "done sleeping"
-```
-
-`ThreadPool` - a pool of threads used to run any operation that cannot be
-implemented using non-blocking calls, such as file system calls. The operation
-is offloaded to a worker thread, allowing the event loop to continue processing
-other tasks. For example, `IO.read` and `File.stat` are both reimplemented
-using the Polyphony thread pool. You can easily use the thread pool to run your
-own blocking operations as follows:
-
-```ruby
-result = Polyphony::ThreadPool.process { long_running_process }
-```
-
-`Throttler` - a mechanism for throttling an arbitrary task, such as sending of
-emails, or crawling a website. A throttler is normally created using 
-`Kernel.throttle`, and can even be used to throttle operations across multiple
-coprocesses:
-
-```ruby
-server = Net.tcp_listen(1234)
-throttler = throttle(rate: 10) # up to 10 times per second
-
-while client = server.accept
-  spin {
-    throttler.call {
-      while data = client.read
-        client.write(data)
-      end
-    }
-  }
-end
-```
-
 ## API Reference
 
 To be continued...
@@ -364,7 +425,7 @@ following:
 
 ```ruby
 require 'http/parser'
-require 'modulation'
+require 'polyphony'
 
 def handle_client(client)
   parser = Http::Parser.new