polyphony 0.27 → 0.28

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: polyphony
 version: !ruby/object:Gem::Version
-  version: '0.27'
+  version: '0.28'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-19 00:00:00.000000000 Z
+date: 2020-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: modulation
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.11.3
+        version: 5.13.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.11.3
+        version: 5.13.0
 - !ruby/object:Gem::Dependency
   name: minitest-reporters
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +94,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 0.17.1
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.79.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.79.0
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -164,6 +178,62 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.6.0
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.8.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.8.6
+- !ruby/object:Gem::Dependency
+  name: jekyll-remote-theme
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+- !ruby/object:Gem::Dependency
+  name: jekyll-seo-tag
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.6.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.6.1
+- !ruby/object:Gem::Dependency
+  name: just-the-docs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.7
 description: 
 email: ciconia@gmail.com
 executables: []
@@ -183,21 +253,30 @@ files:
 - README.md
 - Rakefile
 - TODO.md
-- docs/README.md
+- docs/_config.yml
+- docs/_includes/nav.html
+- docs/_sass/custom/custom.scss
+- docs/_sass/overrides.scss
+- docs/assets/img/echo-fibers.svg
+- docs/assets/img/sleeping-fiber.svg
+- docs/faq.md
+- docs/getting-started.md
 - docs/getting-started/installing.md
 - docs/getting-started/tutorial.md
-- docs/summary.md
+- docs/index.md
+- docs/technical-overview.md
 - docs/technical-overview/concurrency.md
 - docs/technical-overview/design-principles.md
 - docs/technical-overview/exception-handling.md
 - docs/technical-overview/extending.md
-- docs/technical-overview/faq.md
 - docs/technical-overview/fiber-scheduling.md
+- docs/user-guide.md
 - docs/user-guide/web-server.md
 - examples/core/01-spinning-up-fibers.rb
 - examples/core/02-awaiting-fibers.rb
 - examples/core/03-interrupting.rb
 - examples/core/xx-channels.rb
+- examples/core/xx-deadlock.rb
 - examples/core/xx-deferring-an-operation.rb
 - examples/core/xx-erlang-style-genserver.rb
 - examples/core/xx-extended_fibers.rb
@@ -212,6 +291,7 @@ files:
 - examples/core/xx-signals.rb
 - examples/core/xx-sleeping.rb
 - examples/core/xx-spin_error_backtrace.rb
+- examples/core/xx-state-machine.rb
 - examples/core/xx-supervisors.rb
 - examples/core/xx-thread-selector-sleep.rb
 - examples/core/xx-thread-selector-snooze.rb
@@ -220,8 +300,10 @@ files:
 - examples/core/xx-thread_pool.rb
 - examples/core/xx-throttling.rb
 - examples/core/xx-timeout.rb
+- examples/core/xx-trace.rb
 - examples/core/xx-using-a-mutex.rb
 - examples/interfaces/pg_client.rb
+- examples/interfaces/pg_notify.rb
 - examples/interfaces/pg_pool.rb
 - examples/interfaces/pg_transaction.rb
 - examples/interfaces/redis_channels.rb
@@ -239,6 +321,7 @@ files:
 - examples/io/xx-irb.rb
 - examples/io/xx-net-http.rb
 - examples/io/xx-open.rb
+- examples/io/xx-switch.rb
 - examples/io/xx-system.rb
 - examples/io/xx-tcpserver.rb
 - examples/io/xx-tcpsocket.rb
@@ -268,6 +351,7 @@ files:
 - ext/gyro/socket.c
 - ext/gyro/thread.c
 - ext/gyro/timer.c
+- ext/gyro/tracing.c
 - ext/libev/Changes
 - ext/libev/LICENSE
 - ext/libev/README
@@ -301,10 +385,12 @@ files:
 - lib/polyphony/extensions/socket.rb
 - lib/polyphony/extensions/thread.rb
 - lib/polyphony/fs.rb
+- lib/polyphony/irb.rb
 - lib/polyphony/line_reader.rb
 - lib/polyphony/net.rb
 - lib/polyphony/postgres.rb
 - lib/polyphony/redis.rb
+- lib/polyphony/trace.rb
 - lib/polyphony/version.rb
 - polyphony.gemspec
 - test/coverage.rb
@@ -323,14 +409,18 @@ files:
 - test/test_signal.rb
 - test/test_supervisor.rb
 - test/test_thread.rb
+- test/test_thread_pool.rb
 - test/test_throttler.rb
 - test/test_timer.rb
+- test/test_trace.rb
 homepage: https://dfab.gitbook.io/polyphony/
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/digital-fabric/polyphony
-  documentation_uri: https://dfab.gitbook.io/polyphony/
+  documentation_uri: https://digital-fabric.github.io/polyphony/
+  homepage_uri: https://digital-fabric.github.io/polyphony/
+  changelog_uri: https://github.com/digital-fabric/polyphony/blob/master/CHANGELOG.md
 post_install_message: 
 rdoc_options:
 - "--title"
@@ -350,7 +440,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: 'Polyphony: Fiber-based Concurrency for Ruby'

data/docs/README.md

@@ -1,36 +0,0 @@
-# Polyphony - Easy Concurrency for Ruby
-
-> Polyphony \| pəˈlɪf\(ə\)ni \|
-> 1. _Music_ the style of simultaneously combining a number of parts, each forming an individual melody and harmonizing with each other.
-> 2. _Programming_ a Ruby gem for concurrent programming focusing on performance and developer happiness.
-
-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, 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.
-
-Polyphony makes it possible to use normal Ruby built-in classes like `IO`, and `Socket` in a concurrent fashion without having to resort to threads. Polyphony takes care of context-switching automatically whenever a blocking call like `Socket#accept` or `IO#read` is issued.
-
-## Features
-
-* 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.
-* Abstractions and constructs for controlling the execution of concurrent code: 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` and `TCPSocket` and `Net::HTTP`.
-* Competitive performance and scalability characteristics, in terms of both throughput and memory consumption.
-
-## 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, Erlang in general)
-
-## Going further
-
-To learn more about using Polyphony to build concurrent applications, read the technical overview below, or look at the [included examples](https://github.com/digital-fabric/polyphony/tree/9e0f3b09213156bdf376ef33684ef267517f06e8/examples/README.md). A thorough reference is forthcoming.
-
-## Contributing to Polyphony
-
-Issues and pull requests will be gladly accepted. Please use the git repository at https://github.com/digital-fabric/polyphony as your primary point of departure for contributing.

data/docs/summary.md

@@ -1,60 +0,0 @@
-# Table of contents
-
-* [Polyphony - Easy Concurrency for Ruby](../README.md)
-
-## Getting Started
-
-* [Installing](getting-started/installing.md)
-* [Tutorial](getting-started/tutorial.md)
-
-## Technical overview
-
-* [Design Principles](technical-overview/design-principles.md)
-* [Concurrency the Easy Way](technical-overview/concurrency.md)
-* [How Fibers are Scheduled](technical-overview/fiber-scheduling.md)
-* [Exception Handling](technical-overview/exception-handling.md)
-* [Frequently Asked Questions](technical-overview/faq.md)
-
-## How To
-
-* [Make an echo server](howto/echo-server.md)
-* [Make an HTTP server](howto/http-server.md)
-* [Make a Websocket server](howto/websocket-server.md)
-* [Use timers](howto/timers.md)
-* [Throttle recurrent operations](howto/throttle.md)
-* [Cancel ongoing operations](howto/cancel.md)
-* [Control fibers](howto/fibers.md)
-* [Synchronize concurrent operations](howto/synchronize.md)
-* [Perform CPU-bound operations](howto/cpu-bound.md)
-* [Control backpressure](howto/backpressure.md)
-* [Fork worker processes](howto/worker-processes.md)
-
-## Polyphony extensions
-
-* [Postgresql](extensions/pg)
-* [Redis](extensions/redis)
-* [IRB](extensions/irb)
-* [Throttlers](#)
-* [Resource Pools](#)
-* [Synchronisation](#)
-* [Web Server](user-guide/web-server.md)
-* [Websocket Server](#)
-* [Reactor API](#)
-
-## API Reference
-
-* [Fiber](#)
-* [Gyro](#)
-* [Gyro::Async](#)
-* [Gyro::Child](#)
-* [Gyro::IO](#)
-* [Gyro::Timer](#)
-* [Kernel](#)
-* [Polyphony](#)
-* [Polyphony::CancelScope](#)
-* [Polyphony::Mutex](#)
-* [Polyphony::Pulser](#)
-* [Polyphony::ResourcePool](#)
-* [Polyphony::Throttler](#)
-
-## [Contributing to Polyphony](contributing.md)

data/docs/technical-overview/faq.md

@@ -1,97 +0,0 @@
-# Frequently Asked Questions
-
-## Why not just use callbacks instead of fibers?
-
-It is true that reactor engines such as libev use callbacks to handle events. There's also programming platforms such as [node.js](https://nodejs.org/) that base their entire API on the callback pattern. [EventMachine](https://www.rubydoc.info/gems/eventmachine/1.2.7) is a popular reactor library for Ruby that uses callbacks for handling events.
-
-Using callbacks means splitting your application logic into disjunct pieces of code. Consider the following example:
-
-```ruby
-require 'eventmachine'
-
-module EchoServer
-  def post_init
-    puts '-- someone connected to the echo server!'
-  end
-
-  def receive_data data
-    send_data ">>>you sent: #{data}"
-    close_connection if data =~ /quit/i
-  end
-
-  def unbind
-    puts '-- someone disconnected from the echo server!'
-  end
-end
-
-# Note that this will block current thread.
-EventMachine.run {
-  EventMachine.start_server '127.0.0.1', 8081, EchoServer
-}
-```
-
-The client-handling code is split across three different callback methods. Compare this to the following equivalent using Polyphony:
-
-```ruby
-require 'polyphony/auto_run'
-
-server = TCPServer.open('127.0.0.1', 8081)
-while (client = server.accept)
-  spin do
-    puts '-- someone connected to the echo server!'
-    while (data = client.gets)
-      client << ">>>you sent: #{data}"
-      break if data =~ /quit/i
-    end
-  ensure
-    client.close
-    puts '-- someone disconnected from the echo server!'
-  end
-end
-```
-
-The Polyphony version is both more terse and explicit at the same time. It explicitly accepts connections on the server port, and the entire logic handling each client connection is contained in a single block. The order of the different actions - printing to the console, then echoing client messages, then finally closing the client connection and printing again to the console - is easy to grok. The echoing of client messages is also explicit: a simple loop waiting for a message, then responding to the client. In addition, we can use an `ensure` block to correctly cleanup even if exceptions are raised while handling the client.
-
-Using callbacks also makes it much more difficult to debug your program. when callbacks are used to handle events, the stack trace will necessarily start at the reactor, and thus lack any information about how the event came to be in the first place. Contrast this with Polyphony, where stack traces show the entire _sequence of events_ leading up to the present point in the code.
-
-In conclusion:
-
-* Callbacks cause the splitting of logic into disjunct chunks.
-* Callbacks do not provide a good error handling solution.
-* Callbacks often lead to code bloat.
-* Callbacks are harder to debug.
-
-## If callbacks suck, why not use promises?
-
-Promises have gained a lot of traction during the last few years as an  
-alternative to callbacks, above all in the Javascript community. While promises have been at a certain point considered for use in Polyphony, they were not found to offer enough of a benefit. Promises still cause split logic, are quite verbose and provide a non-native exception handling mechanism. In addition, they do not make it easier to debug your code.
-
-## Why is awaiting implicit? Why not use explicit async/await?
-
-Actually, async/await was contemplated while developing Polyphony, but at a certain point it was decided to abandon these methods / decorators in favor of a more implicit approach. The most crucial issue with async/await is that it prevents the use of anything from Ruby's stdlib. Any operation involving stdlib classes needs to be wrapped in boilerplate.
-
-Instead, we have decided to make blocking operations implicit and thus allow the use of common APIs such as `Kernel#sleep` or `IO.popen` in a transparent manner. After all, these APIs in their stock form block execution just as well.
-
-## Why use `Fiber#transfer` and not `Fiber#resume`?
-
-The API for `Fiber.yield`/`Fiber#resume` is stateful and is intended for the asymmetric execution of coroutines. This is useful when using generators, or other cases where one coroutine acts as a "server" and another as a "client". In Polyphony's case, all fibers are equal, and control can be transferred freely between them, which is much easier to achieve using `Fiber#transfer`. In addition, using `Fiber#transfer` allows us to perform blocking operations from the main fiber, which is not possible when using `Fiber#resume`.
-
-## Why is Polyphony not split into multiple gems?
-
-Polyphony is currently at an experimental stage, and its different APIs are still in flux. For that reason, all the different parts of Polyphony are currently kept in a single gem. Once things stabilize, and as Polyphony approaches version 1.0, it will be split into separate gems, each with its own functionality.
-
-## Can I use Polyphony in a multithreaded program?
-
-Not yet. We plan to support multiple threads when Ruby 3.0 is ready.
-
-## Can I run Rails using Polyphony?
-
-Not yet. We do plan to support running Rails when our multithreaded support is ready (see above).
-
-## How can I contribute to Polyphony?
-
-The Polyphony repository is at https://github.com/digital-fabric/polyphony. Feel free to create issues and contribute pull requests.
-
-## Who is behind this project?
-
-I'm Sharon Rosner, an independent software developer living in France. Here's my [github profile](https://github.com/ciconia). You can contact me by writing to [noteflakes@gmail.com](mailto:ciconia@gmail.com).