polyphony 0.40 → 0.41

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fac2ba159f62bc767c1c022a9ac84e0d682e9dc1cbb10f53e92ba53da376745
-  data.tar.gz: 8d43be97359735d5b7ac6b9867716c06c420385bb41f14916edd0a2d2bbca454
+  metadata.gz: ebbaa936b265f2e46ff30cab71b7c85e5ebd31396f7b8ecb8fc01156f6e35f79
+  data.tar.gz: 677c90c266a7d677f124f964775d849a350f925c0441f9aa6cba3a4745ff1e5d
 SHA512:
-  metadata.gz: 0350c4dbee7ad72ba68dfff4fc431870481f43a763d9e265e05ade0ce9545456adef2a79c5efd98ce7fc28b2314ab5558a9e69f9e9ef92759e5ae320c78435be
-  data.tar.gz: 7c7774de233962a1b06bac02623a6127f9b716e36852bc6e5849227db80fc0e910549756c83441f6d40dd75a22c26253fcfeef7e50d62482c1cc7603f6c4b2f3
+  metadata.gz: 732f1eaa117ec2483661451b98a43192ec3e757bde24b4f0eb115fee057efd55fa306af2ed484d3fa943b09e2913a76b9b34a4a8f7eed3a64ea06c27c44b3c17
+  data.tar.gz: b9a0595dbf7f338c0b1d67f121090261f0a6efb8c1cb342717a5b94b54a346e1eeadee9b62fd916c4cc3ad400d5466119b3a806f4f611b863682eef10b6b2cfe

data/.github/workflows/test.yml

@@ -4,12 +4,21 @@ on: [push]
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        ruby: [2.6, 2.7]
+
+    name: >-
+      ${{matrix.os}}, ${{matrix.ruby}}
+
+    runs-on: ${{matrix.os}}
     steps:
     - uses: actions/checkout@v1
     - uses: actions/setup-ruby@v1
       with:
-        ruby-version: 2.6.5
+        ruby-version: ${{matrix.ruby}}
     - name: Install dependencies
       run: |
         gem install bundler

data/.gitignore

@@ -52,8 +52,8 @@ build-iPhoneSimulator/
 test.rb
 .vscode
 
-lib/gyro_ext.bundle
-lib/gyro_ext.so
+lib/*.bundle
+lib/*.so
 
 _site
 .sass-cache

data/.rubocop.yml

@@ -143,3 +143,33 @@ Style/HashTransformKeys:
 
 Style/HashTransformValues:
   Enabled: true
+
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+
+Lint/DeprecatedOpenSSLConstant:
+  Enabled: true
+
+Lint/MixedRegexpCaptureTypes:
+  Enabled: true
+
+Lint/RaiseException:
+  Enabled: true
+
+Lint/StructNewOverride:
+  Enabled: true
+
+Style/ExponentialNotation:
+  Enabled: true
+
+Style/RedundantRegexpCharacterClass:
+  Enabled: true
+
+Style/RedundantRegexpEscape:
+  Enabled: true
+
+Style/SlicingWithRange:
+  Enabled: true

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.41 2020-06-27
+
+* Introduce System Agent design, remove all `Gyro` classes
+
 ## 0.40 2020-05-04
 
 * More improvements to stability after fork
@@ -21,13 +25,13 @@
 
 * Rename `Fiber#cancel!` to `Fiber#cancel`
 * Rename `Gyro::Async#signal!` to `Gyro::Async#signal`
-* Use `Fiber#auto_async` in thread pool, thread extension
+* Use `Fiber#auto_watcher` in thread pool, thread extension
 * Implement `Fiber#auto_io` for reusing IO watcher instances
 * Refactor C code
 
 ## 0.34 2020-03-25
 
-* Add `Fiber#auto_async` mainly for use in places like `Gyro::Queue#shift`
+* Add `Fiber#auto_watcher` mainly for use in places like `Gyro::Queue#shift`
 * Refactor C extension
 * Improved GC'ing for watchers
 * Implement process supervisor (`Polyphony::ProcessSupervisor`)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    polyphony (0.40)
+    polyphony (0.41)
 
 GEM
   remote: https://rubygems.org/
@@ -27,7 +27,6 @@ GEM
       multi_xml (>= 0.5.2)
     i18n (0.9.5)
       concurrent-ruby (~> 1.0)
-    jaro_winkler (1.5.4)
     jekyll (3.8.6)
       addressable (~> 2.4)
       colorator (~> 1.0)
@@ -88,16 +87,20 @@ GEM
     rb-inotify (0.10.1)
       ffi (~> 1.0)
     redis (4.1.0)
+    regexp_parser (1.7.1)
     rexml (3.2.4)
     rouge (3.15.0)
-    rubocop (0.80.0)
-      jaro_winkler (~> 1.5.1)
+    rubocop (0.85.1)
       parallel (~> 1.10)
       parser (>= 2.7.0.1)
       rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.7)
       rexml
+      rubocop-ast (>= 0.0.3)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (0.0.3)
+      parser (>= 2.7.0.1)
     ruby-progressbar (1.10.1)
     rubyzip (2.0.0)
     safe_yaml (1.0.5)
@@ -131,7 +134,7 @@ DEPENDENCIES
   polyphony!
   rake-compiler (= 1.0.5)
   redis (= 4.1.0)
-  rubocop (= 0.80.0)
+  rubocop (= 0.85.1)
   simplecov (= 0.17.1)
 
 BUNDLED WITH

data/Rakefile

@@ -4,8 +4,8 @@ require "bundler/gem_tasks"
 require "rake/clean"
 
 require "rake/extensiontask"
-Rake::ExtensionTask.new("gyro_ext") do |ext|
-  ext.ext_dir = "ext/gyro"
+Rake::ExtensionTask.new("polyphony_ext") do |ext|
+  ext.ext_dir = "ext/polyphony"
 end
 
 task :recompile => [:clean, :compile]

data/TODO.md

@@ -1,42 +1,8 @@
-- Would it be possible to spin up a fiber on another thread?
-  
-  The use case is being able to supervise fibers that run on separate threads.
-  This might be useful for distributing jobs (such as handling HTTP connections)
-  over multiple threads.
+## 0.42 Update docs
 
-  For this we need:
+- 
 
-  - A way to communicate to a thread that it needs to spin up a fiber, the
-    simplest solution is to start a fiber accepting spin requests for each
-    thread (in `Thread#initialize`).
-  - An API:
-
-    ```ruby
-    spin(on_thread: thread) { do_something_important }
-    ```
-
-  An alternative is to turn the main fiber of spawned threads into a child of
-  the spawning fiber. But since a lot of people might start threads without any
-  regard to fibers, it might be better to implement this in a new API. An
-  example of the top of my head for threads that shouldn't be children of the
-  spawning fiber is our own test helper, which kills all child fibers after each
-  test. MiniTest has some threads it spawns for running tests in parallel, and
-  we don't want to stop them after each test!
-
-  So, a good solution would be:
-
-  ```ruby
-  t = Thread.new { do_stuff }
-  t.parent_fiber = Fiber.current
-  # or otherwise:
-  Fiber.current.add_child_fiber(t.main_fiber)
-  ```
-
-
-
-
-
-## 0.40 Some more API work, more docs
+## 0.43 Some more API work, more docs
 
 - Debugging
   - Eat your own dogfood: need a good tool to check what's going on when some
@@ -148,13 +114,9 @@
     - links to the interesting stuff
       - benchmarks
   - explain difference between `sleep` and `suspend`
-  - add explanation about async vs sync, blocking vs non-blocking
   - discuss using `snooze` for ensuring responsiveness when executing CPU-bound work
 
-- Check why first call to `#sleep` returns too early in tests. Check the
-  sleep behaviour in a spawned thread.
-
-## 0.41 Sinatra / Sidekiq
+## 0.44 Sinatra / Sidekiq
 
 - sintra app with database access (postgresql)
 
@@ -164,13 +126,11 @@
   - test performance
   - proceed from there
 
-## 0.42 Testing && Docs
+## 0.45 Testing && Docs
 
 - Pull out redis/postgres code, put into new `polyphony-xxx` gems
 
-## 0.43 Integration
-
-## 0.44 Real IO#gets and IO#read
+## 0.46 Real IO#gets and IO#read
 
 - More tests
 - Implement some basic stuff missing:
@@ -180,11 +140,11 @@
   - `IO.foreach`
   - `Process.waitpid`
 
-## 0.45 Rails
+## 0.47 Rails
 
 - Rails?
 
-## 0.46 DNS
+## 0.48 DNS
 
 ### DNS client
 
@@ -217,56 +177,17 @@ Prior art:
 
 - https://github.com/socketry/async-dns
 
-### Work on API
-
-  - Introduce mailbox limiting:
-    - add API for limiting mailbox size:
-
-      ```ruby
-      Fiber.current.mailbox_limit = 1000
-      ```
-
-    - Add the limit for `Gyro::Queue`
-
-      ```ruby
-      Gyro::Queue.new(1000)
-      ```
-
-    - Pushing to a limited queue will block if limit is reached
-
-  - Introduce selective receive:
-
-    ```ruby
-    # returns (or waits for) the first message for which the block returns true
-    (_, item) = receive { |msg| msg.first == ref }
-    ```
-
-    Possible implementation:
-
-    ```ruby
-    def receive
-      return @mailbox.shift unless block_given?
-      
-      loop
-        msg = @mailbox.shift
-        return msg if yield(msg)
-
-        # message didn't match condition, put it back in queue
-        @mailbox.push msg
-      end
-    end
-    ```
+## Work on API
 
 - Add option for setting the exception raised on cancelling using `#cancel_after`:
 
-  ```ruby
-  cancel_after(3, with_error: MyErrorClass) do
-    do_my_thing
-  end
-
-  # or a RuntimeError with message
-  cancel_after(3, with_error: 'Cancelling due to timeout') do
-    do_my_thing
-  end
-  ```
+```ruby
+cancel_after(3, with_error: MyErrorClass) do
+  do_my_thing
+end
+# or a RuntimeError with message
+cancel_after(3, with_error: 'Cancelled due to timeout') do
+  do_my_thing
+end
+```
 

data/docs/_includes/head.html

@@ -0,0 +1,40 @@
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=Edge">
+
+  {% if site.plugins.jekyll-seo == nil %}
+    <title>{{ page.title }} - {{ site.title }}</title>
+
+    {% if page.description %}
+      <meta name="Description" content="{{ page.description }}">
+    {% endif %}
+  {% endif %}
+
+  <link rel="shortcut icon" href="{{ '/favicon.ico' | relative_url }}" type="image/x-icon">
+
+  <link rel="stylesheet" href="{{ '/assets/css/just-the-docs.css' | relative_url }}">
+
+  {% if site.ga_tracking != nil %}
+    <script async src="https://www.googletagmanager.com/gtag/js?id={{ site.ga_tracking }}"></script>
+    <script>
+      window.dataLayer = window.dataLayer || [];
+      function gtag(){dataLayer.push(arguments);}
+      gtag('js', new Date());
+
+      gtag('config', "{{ site.ga_tracking }}");
+    </script>
+
+  {% endif %}
+
+  {% if site.search_enabled != false %}
+    <script type="text/javascript" src="{{ '/assets/js/vendor/lunr.min.js' | relative_url }}"></script>
+  {% endif %}
+  <script type="text/javascript" src="{{ '/assets/js/just-the-docs.js' | relative_url }}"></script>
+
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+
+  {% seo %}
+
+  {% include head_custom.html %}
+
+</head>

data/docs/_includes/nav.html

@@ -9,12 +9,12 @@
                      {% if node.section %}section-title{% endif %}
                     ">
             {%- if page.parent == node.title or page.grand_parent == node.title -%}
-              {%- assign first_level_url = node.section_link | node.url | absolute_url -%}
+              {%- assign first_level_url = node.section_link | node.url | relative_url -%}
             {%- endif -%}
             {%- if node.section -%}
               <span class="section-title">{{ node.title }}</span>
             {%- else -%}
-              <a href="{{ node.url | absolute_url }}" class="navigation-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
+              <a href="{{ node.url | relative_url }}" class="navigation-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
             {%- endif -%}
             {%- if node.has_children -%}
               {%- if node.alphabetical_order -%}
@@ -26,15 +26,15 @@
                 {%- for child in children_list -%}
                   <li class="navigation-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
                     {%- if page.url == child.url or page.parent == child.title -%}
-                      {%- assign second_level_url = child.url | absolute_url -%}
+                      {%- assign second_level_url = child.url | relative_url -%}
                     {%- endif -%}
-                    <a href="{{ child.url | absolute_url }}" class="navigation-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
+                    <a href="{{ child.url | relative_url }}" class="navigation-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
                     {%- if child.has_children -%}
                         {%- assign grand_children_list = site.html_pages | where: "parent", child.title | sort:"nav_order" -%}
                         <ul class="navigation-list-child-list">
                         {%- for grand_child in grand_children_list -%}
                           <li class="navigation-list-item {% if page.url == grand_child.url %} active{% endif %}">
-                            <a href="{{ grand_child.url | absolute_url }}" class="navigation-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
+                            <a href="{{ grand_child.url | relative_url }}" class="navigation-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
                           </li>
                         {%- endfor -%}
                       </ul>

data/docs/api-reference/fiber.md

@@ -71,7 +71,7 @@ f << 2
 result = receive #=> 20
 ```
 
-### #auto_async → async
+### #auto_watcher → async
 
 Returns a reusable `Gyro::Async` watcher instance associated with the fiber.
 This method provides a way to minimize watcher allocation. Instead of allocating
@@ -84,7 +84,7 @@ def work(async)
   async.signal
 end
 
-async = Fiber.current.auto_async
+async = Fiber.current.auto_watcher
 spin { work(async) }
 async.await
 ```

data/docs/main-concepts/design-principles.md

@@ -1,18 +1,76 @@
 ---
 layout: page
-title: Design Principles
+title: The Design of Polyphony
 nav_order: 5
 parent: Main Concepts
 permalink: /main-concepts/design-principles/
 prev_title: Extending Polyphony
 ---
-# Design Principles
+# The Design of Polyphony 
+
+Polyphony is a new gem that aims to enable developing high-performance
+concurrent applications in Ruby using a fluent, compact syntax and API.
+Polyphony enables fine-grained concurrency - the splitting up of operations into
+a large number of concurrent tasks, each concerned with small part of the whole
+and advancing at its own pace. Polyphony aims to solve some of the problems
+associated with concurrent Ruby programs using a novel design that sets it apart
+from other approaches currently being used in Ruby.
+
+## Origins
+
+The Ruby core language (at least in its MRI implementation) currently provides
+two main constructs for performing concurrent work: threads and fibers. While
+Ruby threads are basically wrappers for OS threads, fibers are essentially
+continuations, allowing pausing and resuming distinct computations. Fibers have
+been traditionally used mostly for implementing enumerators and generators.
+
+In addition to the core Ruby concurrency primitives, some Ruby gems have been
+offering an alternative solution to writing concurrent Ruby apps, most notably
+[EventMachine](https://github.com/eventmachine/eventmachine/), which implements
+an event reactor and offers an asynchronous callback-based API for writing
+concurrent code.
+
+In the last couple of years, however, fibers have been receiving more attention
+as a possible constructs for writing concurrent programs. In particular, the
+[Async](https://github.com/socketry/async) framework, created by [Samuel
+Williams](https://github.com/ioquatix), offering a comprehensive set of
+libraries, employs fibers in conjunction with an event reactor provided by the
+[nio4r](https://github.com/socketry/nio4r) gem, which wraps the C
+library [libev](http://software.schmorp.de/pkg/libev.html).
+
+In addition, recently some effort was undertaken to provide a way to
+[automatically switch between fibers](https://bugs.ruby-lang.org/issues/13618)
+whenever a blocking operation is performed, or to [integrate a fiber
+scheduler](https://bugs.ruby-lang.org/issues/16786) into the core Ruby code.
+
+Nevertheless, while work is being done to harness fibers for providing a better
+way to do concurrency in Ruby, fibers remain a mistery for most Ruby
+programmers, a perplexing unfamiliar corner right at the heart of Ruby.
+
+## Design Principles
+
+Polyphony started as an experiment, but over about two years of slow, jerky
+evolution turned into something I'm really excited to share with the Ruby
+community. Polyphony's design is both similar and different than the projects
+mentioned above.
+
+Polyphony today as nothing like the way it began. A careful examination of the
+[CHANGELOG](https://github.com/digital-fabric/polyphony/blob/master/CHANGELOG.md)
+would show how Polyphony explored not only different event reactor designs, but
+also different API designs incorporating various concurrent paradigms such as
+promises, async/await, fibers, and finally structured concurrency. 
+
+While Polyphony, like nio4r or EventMachine, uses an event reactor to turn
+blocking operations into non-blocking ones, it completely embraces fibers and in
+fact does not provide any callback-based APIs. Furthermore, Polyphony provides
+fullblown fiber-aware implementations of blocking operations, such as
+`read/write`, `sleep` or `waitpid`, instead of just event watching primitives.
+
+Throughout the development process, it was my intention to create a programming
+interface that would make highly-concurrent 
+
+
 
-Polyphony was created in order to enable developing high-performance concurrent
-applications in Ruby using a fluent, compact syntax and API. Polyphony enables
-fine-grained concurrency - the splitting up of operations into a large number of
-concurrent tasks, each concerned with small part of the whole and advancing at
-its own pace.
 
 
 
@@ -46,8 +104,8 @@ library. Polyphony's design is based on the following principles:
   async callback-style APIs.
 
   ```ruby
-  # in Polyphony, I/O ops block the current fiber, but implicitly yield to other
-  # concurrent fibers:
+  # in Polyphony, I/O ops might block the current fiber, but implicitly yield to
+  # other concurrent fibers:
   clients.each { |client|
     spin { client.puts 'Elvis has left the chatroom' }
   }