polyphony 0.32 → 0.33

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75e18e7719d577fc1f07679874d2c3afe23b5a6b6184c1c6723006d0f9fcdf80
-  data.tar.gz: 347608163b6d0ec934b2a70d1b28ffd1c0056b3da51f242f6619ac4a8e94a3ad
+  metadata.gz: fde67b1d9cd285b35d265f12648e48e43073fd3b8e27713f981883ab4b080c12
+  data.tar.gz: a567e1e171b4f61f5fb344b3345b4a9e6f32ec7a810258c99007a17614e5cd5e
 SHA512:
-  metadata.gz: 41cfdd7550a444c590b08eff7c2bf716ce42a19250074bca0425334be4b32b96efba4d60bbe9b1257cf3b8616be31da940695709a25af8c5d03c9803dff8fb80
-  data.tar.gz: 3a12af73aa84d4c3ae9e5c94c0dd55f99bd7eaf3ca49e1f59ab4b80d224dfe1dc068c68f4f8e09ab3d0bcc4996f61ae8d03c42158912f24458ad0ed1e09e6b2a
+  metadata.gz: 3e99f3e9f9acce3b2deadf516dc254ae6a305a64b9bd05a04e6207834f1189c61ae44481e485381fbb08eae3ee2f1da0843441ee518f64448f76c3529e1281a7
+  data.tar.gz: b6ebe93d0eb812010aafdcc2f9298e1237c14a6b0da6b3da30abe917217fb04fac24671e02792c0c3f790912660ed0b64355849e81e07bb35029dc647f413589

data/.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: Tests
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - uses: actions/setup-ruby@v1
+      with:
+        ruby-version: 2.6.5
+    - name: Install dependencies
+      run: |
+        gem install bundler
+        bundle install
+    - name: Compile C-extension
+      run: bundle exec rake compile
+    - name: Run tests
+      run:  bundle exec rake test

data/.rubocop.yml

@@ -129,4 +129,17 @@ Naming/MethodParameterName:
 
 Security/MarshalLoad:
   Exclude:
-    - examples/**/*.rb
+    - examples/**/*.rb
+
+Lint/ShadowedArgument:
+  Exclude:
+    - lib/polyphony/extensions/fiber.rb
+
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.33 2020-03-08
+
+* Implement `Fiber#supervise` (WIP)
+* Add `Fiber#restart` API
+* Fix race condition in `Thread#join`, `Thread#raise` (#14)
+* Add `Exception#source_fiber` - references the fiber in which an uncaught
+  exception occurred
+
 ## 0.32 2020-02-29
 
 * Accept optional throttling rate in `#spin_loop`
@@ -6,8 +14,8 @@
 * Add `#receive_pending` global API.
 * Prevent race condition in `Gyro::Queue`.
 * Improve signal handling - `INT`, `TERM` signals are now always handled in the
-  main fiber.
-* Fix adapter requires (redis and postgres).
+  main fiber
+* Fix adapter requires (redis and postgres)
 
 ## 0.31 2020-02-20
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    polyphony (0.32)
+    polyphony (0.33)
       modulation (~> 1.0)
 
 GEM

data/README.md

@@ -1,5 +1,9 @@
 # Polyphony - Fine-Grained Concurrency for Ruby
 
+[![Gem Version](https://badge.fury.io/rb/polyphony.svg)](http://rubygems.org/gems/polyphony)
+[![Modulation Test](https://github.com/digital-fabric/polyphony/workflows/Tests/badge.svg)](https://github.com/digital-fabric/polyphony/actions?query=workflow%3ATests)
+[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/digital-fabric/polyphony/blob/master/LICENSE)
+
 [DOCS](https://digital-fabric.github.io/polyphony/) |
 [EXAMPLES](examples)
 

data/TODO.md

@@ -1,4 +1,118 @@
-## 0.32 Working Sinatra application
+- Debugging
+  - Eat your own dogfood: need a good tool to check what's going on when some
+    test fails
+  - Needs to work with Pry (can write perhaps an extension for pry)
+  - First impl in Ruby using `TracePoint` API
+  - Mode of operation:
+    - Debugger runs on separate thread
+    - The `TracePoint` handler passes control to the debugger thread, and waits
+      for reply (probably using Fiber messages)
+  - Step over should return on the next line *for the same fiber*
+  - The event loop (all event loops?) should be suspended so timers are adjusted
+    accordingly, so on control passing to debugger we:
+
+    - call `ev_suspend()` for main thread ev_loop
+    - prompt and wait for input from user
+    - call `ev_resume()` for main thread ev_loop
+    - process user input
+
+    (We need to verify than `ev_suspend/resume` works for an ev_loop that's not
+    currently running.)
+  - Allow inspection of fiber tree, thread's run queue, fiber's scheduled values etc.
+
+  - UI
+    - `Kernel#breakpoint` is used to break into the debugger while running code
+
+      ```ruby
+      def test_sleep
+        f = spin { sleep 10 }
+        breakpoint
+        ...
+      end
+      ```
+
+      Hitting the breakpoint will show the current location in the source code
+      (with few lines before and after), and present a prompt for commands.
+    
+    - commands:
+      - `step` / `up` / `skip` / `continue` etc. - step into, step out, step over, run
+      - `switch` - switch fiber
+        - how do we select a fiber?
+          - from a list?
+          - from an expression: `Fiber.current.children`
+          - maybe just `select f1` (where f1 is a local var)
+
+- Fiber supervision
+  - can a fiber be restarted?
+    - Theoretically, we can take the same block and rerun it under a different
+      fiber
+  - (restart) strategy (taken from Erlang):
+    - `:one_for_one`: if a child terminates, it is restarted
+    - `:one_for_all`: if a child terminates, all other children are terminated,
+      then all are restarted
+    - `:simple_on_for_one`: same as `:one_for_one` except all children are
+      identical (run the same block)
+  - I'm not so sure this kind of supervision is what we need. We can envision
+    an API such as the following:
+
+    ```ruby
+    spin {
+      spin { do_a }
+      spin { do_b }
+      supervise(restart: :never, shutdown: :terminate)
+    }
+    ```
+
+  - The default for `#supervise` should be:
+    - wait for all fibers to terminate
+    - propagate exceptions
+    - no restart
+  
+  - `#supervise` could also take a block:
+
+    ```ruby
+    supervise do |fiber, error|
+      # this block is called when a fiber is terminated, letting the developer
+      # decide how to react.
+
+      # We can propagate the error
+      raise error if error
+
+      # We can restart the fiber (the respun fiber will have the same parent,
+      # the same caller location, the same tag)
+      fiber.respin # TODO: implement Fiber#respin
+    end
+    ```
+
+  - Another option is to pass supervision parameters to `#spin`:
+
+    ```ruby
+    spin(supervise: true) do
+
+    end
+    ```
+
+  - Or maybe:
+
+    ```ruby
+    spin_supervisor do
+      
+    end
+    ```
+
+## 0.32 Some more API work, more docs
+
+- Allow calling `cancel_after` and `move_on_after` without blocks, just return
+  the cancelling fiber:
+
+  ```ruby
+  def foo
+    f = cancel_after(10)
+    do_something_slow
+  ensure
+    f.stop
+  end
+  ```
 
 - Docs
   - landing page:
@@ -128,3 +242,4 @@ Prior art:
     do_my_thing
   end
   ```
+

data/docs/_sass/custom/custom.scss

@@ -23,4 +23,8 @@ $link-color: $blue-000;
 
 #prevnext span.clear {
   clear: both;
+}
+
+.h-align-center {
+  text-align: center;
 }

data/docs/_sass/overrides.scss

@@ -26,12 +26,6 @@ span.section-title {
       color: rgba($body-text-color, 0.3);
       content: "";
     }
-
-    &.active {
-      &::before {
-        color: $body-text-color;
-      }
-    }
   }
 }
 
@@ -40,6 +34,10 @@ a.navigation-list-link {
   font-weight: 600;
 }
 
+a.navigation-list-link.active {
+  border-right: 4px #6ae solid;
+}
+
 a.navigation-list-link:hover {
   color: $link-color;
 }

data/docs/getting-started/installing.md

@@ -5,9 +5,9 @@ nav_order: 1
 parent: Getting Started
 permalink: /getting-started/installing/
 prev_title: Home
-next_title: A Gentle Introduction to Polyphony
+next_title: Tutorial
 ---
-# Getting Started
+# Installing Polyphony
 
 ## System Requirements
 

data/docs/getting-started/tutorial.md

@@ -1,13 +1,13 @@
 ---
 layout: page
-title: A Gentle Introduction to Polyphony
+title: Tutorial
 nav_order: 2
 parent: Getting Started
 permalink: /getting-started/tutorial/
 prev_title: Installing Polyphony
 next_title: Concurrency the Easy Way
 ---
-# A Gentle Introduction to Polyphony
+# Polyphony: a Tutorial
 
 Polyphony is a new Ruby library aimed at making writing concurrent Ruby apps
 easy and fun. In this article, we'll introduce Polyphony's fiber-based
@@ -170,7 +170,7 @@ rescue Errno::ECONNRESET
 end
 ```
 
-### Adding Concurrency
+## Adding Concurrency
 
 Up until now, we did nothing about concurrency. In fact, our code will not be
 able to handle more than one client at a time, because the accept loop cannot
@@ -212,17 +212,17 @@ Let's consider the advantage of the Polyphony concurrency model:
 
 Now that we have a working concurrent echo server, let's add some bells and
 whistles. First of all, let's get rid of clients that are not active. We'll do
-this by using a Polyphony construct called a cancel scope. Cancel scopes define
-an execution context that can cancel any operation ocurring within its scope:
+this by setting up a timeout fiber that cancels the fiber dealing with the connection
 
 ```ruby
 def handle_client(client)
-  Polyphony::CancelScope.new(timeout: 10) do |scope|
-    while (data = client.gets)
-      scope.reset_timeout
-      client.write('you said: ', data.chomp, "!\n")
-    end
+  timeout = cancel_after(10)
+  while (data = client.gets)
+    timeout.reset
+    client << data
   end
+rescue Polyphony::Cancel
+  client.puts 'Closing connection due to inactivity.'
 rescue Errno::ECONNRESET
   puts 'Connection reset by client'
 ensure
@@ -252,15 +252,17 @@ server = TCPServer.open('127.0.0.1', 1234)
 puts 'Echoing on port 1234...'
 
 def handle_client(client)
-  Polyphony::CancelScope.new(timeout: 10) do |scope|
-    while (data = client.gets)
-      scope.reset_timeout
-      client.write('you said: ', data.chomp, "!\n")
-    end
+  timeout = cancel_after(10)
+  while (data = client.gets)
+    timeout.reset
+    client << data
   end
+rescue Polyphony::Cancel
+  client.puts 'Closing connection due to inactivity.'
 rescue Errno::ECONNRESET
   puts 'Connection reset by client'
 ensure
+  timeout.stop
   client.close
 end
 

data/docs/index.md

@@ -8,45 +8,40 @@ next_title: Installing Polyphony
 
 # Polyphony - fine-grained 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.
+implements a comprehensive
+[fiber](https://ruby-doc.org/core-2.5.1/Fiber.html)-based concurrency model,
+using [libev](https://github.com/enki/libev) as a high-performance event reactor
+for I/O, timers, and other asynchronous events.
+
+[Take the tutorial](getting-started/tutorial){: .btn .btn-blue .text-gamma }
+{: .mt-6 .h-align-center }
 
 ## Focused on Developer Happiness
 
 Polyphony is designed to make concurrent Ruby programming feel natural and
-fluent. Polyphony reduces the boilerplate usually associated with concurrent
-programming, and introduces concurrency primitives that are easy to use, easy to
-understand, and above all idiomatic.
+fluent. The Polyphony API is easy to use, easy to understand, and above all
+idiomatic.
 
 ## Optimized for High Performance
 
 Polyphony offers high performance for I/O bound Ruby apps. Distributing
-concurrent tasks over fibers, instead of threads or processes, minimizes memory
-consumption and reduces the cost of context-switching.
+concurrent operations over fibers, instead of threads or processes, minimizes
+memory consumption and reduces the cost of context-switching.
 
 ## Designed for Interoperability
 
-Polyphony makes it possible to use normal Ruby built-in classes like `IO`, and
-`Socket` in a concurrent multi-fiber environment. Polyphony takes care of
-context-switching automatically whenever a blocking call like `Socket#accept`,
-`IO#read` or `Kernel#sleep` is issued.
+With Polyphony you can use any of the stock Ruby classes and modules like `IO`,
+`Process`, `Socket` and `OpenSSL` in a concurrent multi-fiber environment. In
+addition, Polyphony provides a structured model for exception handling that
+builds on and enhances Ruby's exception handling system.
 
 ## A Growing Ecosystem
 
 Polyphony includes a full-blown HTTP server implementation with integrated
-support for HTTP 1, HTTP 2 and WebSockets, TLS/SSL termination, automatic
-ALPN protocol selection, and body streaming. Polyphony also includes fiber-aware
-extensions for PostgreSQL and Redis. More databases and services are forthcoming.
+support for HTTP 2, WebSockets, TLS/SSL termination and more. Polyphony also
+provides fiber-aware adapters for connecting to PostgreSQL and Redis. More
+adapters are being developed.
 
 ## Features
 

data/docs/main-concepts/concurrency.md

@@ -4,7 +4,7 @@ title: Concurrency the Easy Way
 nav_order: 1
 parent: Main Concepts
 permalink: /main-concepts/concurrency/
-prev_title: A Gentle Introduction to Polyphony
+prev_title: Tutorial
 next_title: How Fibers are Scheduled
 ---
 # Concurrency the Easy Way

data/ext/gyro/async.c

@@ -121,6 +121,33 @@ VALUE Gyro_Async_await(VALUE self) {
   }
 }
 
+VALUE Gyro_Async_await_no_raise(VALUE self) {
+  struct Gyro_Async *async;
+  VALUE ret;
+  
+  GetGyro_Async(self, async);
+
+  async->fiber = rb_fiber_current();
+  if (!async->active) {
+    async->active = 1;
+    async->ev_loop = Gyro_Selector_current_thread_ev_loop();
+    ev_async_start(async->ev_loop, &async->ev_async);
+  }
+
+  ret = Fiber_await();
+  RB_GC_GUARD(ret);
+
+  if (async->active) {
+    async->active = 0;
+    async->fiber = Qnil;
+    ev_async_stop(async->ev_loop, &async->ev_async);
+    async->value = Qnil;
+  }
+
+  return ret;
+}
+
+
 void Init_Gyro_Async() {
   cGyro_Async = rb_define_class_under(mGyro, "Async", rb_cData);
   rb_define_alloc_func(cGyro_Async, Gyro_Async_allocate);