polyphony 0.13 → 0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f95ac584e1a686e3ff45ec50878bce9cc3ea0457f2894e0839e69c79621e3ab9
-  data.tar.gz: 189eb3effd86a54ab16eec64cd4159ce851fdbd249a6b227c02ecfedfd35c987
+  metadata.gz: 78b1d2bf93b1562b6ef1010acdf4a30993d6fd8f40e001ab13a00606e0ed2137
+  data.tar.gz: ea0f410c483ee06da41e1acdd342f9fccadf87c51bbca258571d8f5d2c6048a5
 SHA512:
-  metadata.gz: e935934c596936a1fcce5ecf5f87cb288245755bd4e08f9dce6fde16cffd486134f66bc209774418b1942b00c13e015f6bfa6c55026e1233fe7a4533aa3411b6
-  data.tar.gz: a95b472caf17fa3c5a1f7afb8757e891e445a9afe7770131054a1db49c4a4529afa85acc723e1b621f4ae1200de4bfaef42a6a72b8002decbba4324be21ea3d5
+  metadata.gz: 70af3ec736856b611bd1d4242f6430761b83382f88239a31a1a7e4124fbe6804153e08d248c03c61510c272f9511cdf7f6f4ada277eab2cbd6809f2e41daaa39
+  data.tar.gz: 678dad06dab6f6dbbccc23e39ac45e8045b4fdf0b2ea29959fd34e243d9d0f19f624ef80a8022f7dde4790e080302f59b06e65ec3ca26c9fe5efc4a70856f2c2

data/.gitbook.yaml

@@ -0,0 +1,5 @@
+root: ./docs/
+structure:
+  readme: ../README.md
+  summary: ./summary.md
+  getting-started: ./getting-started.md

data/.gitignore

@@ -0,0 +1,55 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+test.rb
+.vscode
+
+lib/ev_ext.bundle

data/.rubocop.yml

@@ -0,0 +1,49 @@
+AllCops:
+  TargetRubyVersion: 2.5
+  RubyInterpreters:
+    - ruby
+  Exclude:
+    - '**/*.gemspec'
+    - 'test/**/*.rb'
+    - 'examples/**/*.rb'
+    - 'Gemfile*'
+
+Style/LambdaCall:
+  Enabled: false
+# Style/ModuleFunction:
+#   Enabled: false
+# Style/RegexpLiteral:
+#   Enabled: false
+
+# Naming/MemoizedInstanceVariableName:
+#   Enabled: false
+
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+
+Style/SpecialGlobalVars:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Style/MixinUsage:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Lint/RescueException:
+  Enabled: false
+
+Lint/InheritException:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Style/TrivialAccessors:
+  Enabled: false

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+0.14 2019-05-17
+---------------
+
+* Use chunked encoding in HTTP 1 response
+* Rewrite IO#read, #readpartial, #write in C (about 30% performance improvement)
+* Add method delegation to `ResourcePool`
+* Optimize PG::Connection#async_exec
+* Fix Coprocess#cancel!
+* Preliminary support for websocket (see `examples/io/http_ws_server.rb`)
+* Rename `Coroutine` to `Coprocess`
+
 0.13 2019-01-05
 ---------------
 
@@ -18,8 +29,8 @@
 
 * Move reactor loop to secondary fiber, allow blocking operations on main
   fiber.
-* Example implementation of erlang-style generic server pattern (implement
-  async API to a coroutine)
+* Example implementation of erlang-style generic server pattern (implement async
+  API to a coroutine)
 * Implement coroutine mailboxes, Coroutine#<<, Coroutine#receive, Kernel.receive
   for message passing
 * Add Coroutine.current for getting current coroutine

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,31 @@
+PATH
+  remote: .
+  specs:
+    polyphony (0.14)
+      http-2 (= 0.10.0)
+      http_parser.rb (= 0.6.0)
+      modulation (= 0.23)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    http-2 (0.10.0)
+    http_parser.rb (0.6.0)
+    localhost (1.1.4)
+    minitest (5.11.3)
+    modulation (0.23)
+    rake (12.3.2)
+    rake-compiler (1.0.5)
+      rake
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  localhost (= 1.1.4)
+  minitest (= 5.11.3)
+  polyphony!
+  rake-compiler (= 1.0.5)
+
+BUNDLED WITH
+   1.17.2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Sharon Rosner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -19,7 +19,7 @@ supports Linux and MacOS only. This software is currently at the alpha stage.
 Polyphony is a library for building concurrent applications in Ruby. Polyphony
 harnesses the power of
 [Ruby fibers](https://ruby-doc.org/core-2.5.1/Fiber.html) to provide a
-cooperative, sequential coroutine-based concurrency model. Under the hood,
+cooperative, sequential coprocess-based concurrency model. Under the hood,
 Polyphony uses [libev](https://github.com/enki/libev) as a high-performance event
 reactor that provides timers, I/O watchers and other asynchronous event
 primitives.
@@ -31,16 +31,18 @@ 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**.
 - 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
   concurrent code.
-- Higher-order constructs for controlling the execution of concurrent code:
+- Abstractions and constructs for controlling the execution of concurrent code:
   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`.
-- Comprehensive HTTP 1.0 / 1.1 / 2 client and server APIs.
-- Excellent performance and scalability characteristics, in terms of both
+- HTTP 1 / HTTP 2 client
+- Competitive performance and scalability characteristics, in terms of both
   throughput and memory consumption.
 
 ## Prior Art
@@ -89,12 +91,12 @@ 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 `spawn` block starts a
-*coroutine*, and is executed in sequential manner.
+*coprocess*, and is executed in sequential manner.
 
-> **Coroutines - the basic unit of concurrency**: In Polyphony, concurrent
-> operations take place inside coroutines. A `Coroutine` 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. Coroutines offer
+> **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 spawned without affecting performance*. Besides, Ruby does not yet
@@ -113,7 +115,7 @@ require 'polyphony'
 
 server = TCPServer.open(1234)
 while client = server.accept
-  # spawn starts a new coroutine on a separate fiber
+  # spawn starts a new coprocess on a separate fiber
   spawn {
     while data = client.read rescue nil
       client.write(data)
@@ -128,10 +130,10 @@ This example demonstrates several features of Polyphony:
   server. The result of `server.accept` is also a native `TCPSocket` object.
   There are no wrapper classes being used.
 - The only hint of the code being concurrent is the use of `Kernel#spawn`,
-  which starts a new coroutine on a dedicated fiber. This allows serving
+  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 coroutines which are ready to be resumed.
+  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
@@ -224,9 +226,9 @@ In order to facilitate writing concurrent code, Polyphony provides additional
 constructs that make it easier to spawn concurrent tasks and to control them.
 
 `CancelScope` - an abstraction used to cancel the execution of one or more
-coroutines or supervisors. It usually works by defining a timeout for the 
+coprocesses or supervisors. It usually works by defining a timeout for the 
 completion of a task. Any blocking operation can be cancelled, including
-a coroutine or a supervisor. The developer may choose to cancel with or without
+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`:
 
@@ -261,9 +263,24 @@ Pool = Polyphony::ResourcePool.new(limit: 5) {
 }
 ```
 
-`Supervisor` - a class used to control one or more `Coroutine`s. It can be used
-to start, stop and restart multiple coroutines. A supervisor can also be
-used for awaiting the completion of multiple coroutines. It is usually started
+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 {
+  spawn { 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
@@ -289,7 +306,7 @@ 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
-coroutines:
+coprocesses:
 
 ```ruby
 server = Net.tcp_listen(1234)

data/Rakefile

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

data/TODO.md

@@ -0,0 +1,49 @@
+## Testing
+
+- test IO
+- test TCP server / client
+- test thread / thread_pool modules
+
+## UDP socket
+
+```ruby
+socket = UDPSocket.new
+socket.bind("127.0.0.1", 1234)
+
+socket.send "message-to-self", 0, "127.0.0.1", 1234
+p socket.recvfrom(10)
+#=> ["message-to", ["AF_INET", 4913, "localhost", "127.0.0.1"]]
+```
+
+## DNS client
+
+```ruby
+ip_address = DNS.lookup('google.com', 'A')
+```
+
+Prior art:
+
+- https://github.com/alexdalitz/dnsruby
+- https://github.com/eventmachine/eventmachine/blob/master/lib/em/resolver.rb
+- https://github.com/gmodarelli/em-resolv-replace/blob/master/lib/em-dns-resolver.rb
+- https://github.com/socketry/async-dns
+
+### DNS server
+
+```ruby
+Server = import('../../lib/polyphony/dns/server')
+
+server = Server.new do |transaction|
+  puts "got query from #{transaction.info[:client_ip_address]}"
+  transaction.questions.each do |q|
+    respond(transaction, q[:domain], q[:resource_class])
+  end
+end
+
+server.listen(port: 5300)
+puts "listening on port 5300"
+```
+
+Prior art:
+
+- https://github.com/socketry/async-dns

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

@@ -0,0 +1,10 @@
+# Installing
+
+## Installing
+
+```bash
+$ gem install polyphony
+```
+
+## Tutorial
+

data/docs/getting-started/tutorial.md

@@ -0,0 +1,2 @@
+# Tutorial
+

data/docs/summary.md

@@ -0,0 +1,9 @@
+# Table of contents
+
+* [Introduction](../README.md)
+
+## Getting Started
+
+* [Installing](getting-started/getting-started.md)
+* [Tutorial](getting-started/tutorial.md)
+

data/examples/core/cancel.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'modulation'
+
+Polyphony = import('../../lib/polyphony')
+
+puts "going to sleep..."
+cancel_after(1) do
+  sleep(60)
+end

data/examples/core/channel_echo.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'modulation'
+
+Polyphony = import('../../lib/polyphony')
+
+def echo(rchan, wchan)
+  puts "start echoer"
+  while msg = rchan.receive
+    wchan << "you said: #{msg}"
+  end
+ensure
+  puts "echoer stopped"
+end
+
+chan1, chan2 = Polyphony::Channel.new, Polyphony::Channel.new
+
+echoer = spawn { echo(chan1, chan2) }
+
+spawn do
+  puts "start receiver"
+  while msg = chan2.receive
+    puts msg
+    $main.resume if msg =~ /world/
+  end
+ensure
+  puts "receiver stopped"
+end
+
+$main = spawn do
+  t0 = Time.now
+  puts "send hello"
+  chan1 << "hello"
+  puts "send world"
+  chan1 << "world"
+
+  suspend
+  
+  puts "closing channels"
+  chan1.close
+  chan2.close
+  puts "done #{Time.now - t0}"
+end