polyphony 0.41 → 0.42

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebbaa936b265f2e46ff30cab71b7c85e5ebd31396f7b8ecb8fc01156f6e35f79
-  data.tar.gz: 677c90c266a7d677f124f964775d849a350f925c0441f9aa6cba3a4745ff1e5d
+  metadata.gz: e284cae2a5eb2332bc8671090412bbe0cf7d57dbc163d68ba387f4d9635a8adf
+  data.tar.gz: 58eba5a2607df83c7471b1a6b72cc350aa468e9a562e3d1e8f7451eaae12d068
 SHA512:
-  metadata.gz: 732f1eaa117ec2483661451b98a43192ec3e757bde24b4f0eb115fee057efd55fa306af2ed484d3fa943b09e2913a76b9b34a4a8f7eed3a64ea06c27c44b3c17
-  data.tar.gz: b9a0595dbf7f338c0b1d67f121090261f0a6efb8c1cb342717a5b94b54a346e1eeadee9b62fd916c4cc3ad400d5466119b3a806f4f611b863682eef10b6b2cfe
+  metadata.gz: 10b7bcf9240ea8f7355c75d025bd6c5e1bd00c86e7985f71440091cc149c629279b16eaf1c863d85de29e278739926b499625c77238db8eb803aa235395771a4
+  data.tar.gz: 9001df441fdc058a3234bca05f6cca55d3a27edcf0b5b0d126a9c371d37bd0ffecc4d13d8f13c614d9b7182630f94d54481035f6d83fb044aebdf3238f83b03a

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 0.42 2020-07-03
+
+* Improve documentation
+* Fix backtrace on SIGINT
+* Implement LibevAgent#accept_loop, #read_loop
+* Move ref counting from thread to agent
+* Short circuit switchpoint if continuing with the same fiber
+* Always do a switchpoint in #read, #write, #accept
+
 ## 0.41 2020-06-27
 
 * Introduce System Agent design, remove all `Gyro` classes

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    polyphony (0.41)
+    polyphony (0.42)
 
 GEM
   remote: https://rubygems.org/
@@ -51,10 +51,10 @@ GEM
     jekyll-watch (2.2.1)
       listen (~> 3.0)
     json (2.3.0)
-    just-the-docs (0.2.7)
-      jekyll (~> 3.8.5)
+    just-the-docs (0.3.0)
+      jekyll (>= 3.8.5)
       jekyll-seo-tag (~> 2.0)
-      rake (~> 12.3.1)
+      rake (>= 12.3.1, < 13.1.0)
     kramdown (1.17.0)
     liquid (4.0.3)
     listen (3.2.1)
@@ -126,7 +126,7 @@ DEPENDENCIES
   jekyll (~> 3.8.6)
   jekyll-remote-theme (~> 0.4.1)
   jekyll-seo-tag (~> 2.6.1)
-  just-the-docs (~> 0.2.7)
+  just-the-docs (~> 0.3.0)
   localhost (= 1.1.4)
   minitest (= 5.13.0)
   minitest-reporters (= 1.4.2)

data/Rakefile

@@ -20,7 +20,7 @@ task :stress_test do
 end
 
 task :docs do
-  exec 'RUBYOPT=-W0 jekyll serve -s docs'
+  exec 'RUBYOPT=-W0 jekyll serve -s docs -H ec2-35-158-110-38.eu-central-1.compute.amazonaws.com'
 end
 
 CLEAN.include "**/*.o", "**/*.so", "**/*.bundle", "**/*.jar", "pkg", "tmp"

data/TODO.md

@@ -1,9 +1,11 @@
-## 0.42 Update docs
+## 0.42
 
-- 
-
-## 0.43 Some more API work, more docs
+- Reimplement ResourcePool, Channel, Mutex using LibevQueue
+-- Add `Fiber#schedule_with_priority` method, aliased by `Fiber#wakeup`
+- Implement agent interface is virtual function table
+- Implement proxy agent for plugging in a user-provided agent class
 
+## 0.43 
 - Debugging
   - Eat your own dogfood: need a good tool to check what's going on when some
     test fails
@@ -116,7 +118,10 @@
   - explain difference between `sleep` and `suspend`
   - discuss using `snooze` for ensuring responsiveness when executing CPU-bound work
 
-## 0.44 Sinatra / Sidekiq
+
+## 0.44
+
+### Some more API work, more docs
 
 - sintra app with database access (postgresql)
 
@@ -126,11 +131,16 @@
   - test performance
   - proceed from there
 
-## 0.45 Testing && Docs
+
+## 0.45
+
+### Sinatra / Sidekiq
 
 - Pull out redis/postgres code, put into new `polyphony-xxx` gems
 
-## 0.46 Real IO#gets and IO#read
+## 0.46
+
+### Testing && Docs
 
 - More tests
 - Implement some basic stuff missing:
@@ -140,9 +150,9 @@
   - `IO.foreach`
   - `Process.waitpid`
 
-## 0.47 Rails
+## 0.47
 
-- Rails?
+### Real IO#gets and IO#read
 
 ## 0.48 DNS
 

data/docs/_config.yml

@@ -1,15 +1,64 @@
 title: "Polyphony"
+description: Fine-grained concurrency for Ruby
 
+plugins:
+  - jekyll-remote-theme
+
+permalink: pretty
 remote_theme: pmarsceill/just-the-docs
-color_scheme: nil
+color_scheme: light
 
 search_enabled: true
-# Enable support for hyphenated search words:
-search_tokenizer_separator: /[\s/]+/
-
-plugins:
-  - jekyll-remote-theme
+search:
+  # Split pages into sections that can be searched individually
+  # Supports 1 - 6, default: 2
+  heading_level: 2
+  # Maximum amount of previews per search result
+  # Default: 3
+  previews: 3
+  # Maximum amount of words to display before a matched word in the preview
+  # Default: 5
+  preview_words_before: 5
+  # Maximum amount of words to display after a matched word in the preview
+  # Default: 10
+  preview_words_after: 10
+  # Set the search token separator
+  # Default: /[\s\-/]+/
+  # Example: enable support for hyphenated search words
+  tokenizer_separator: /[\s/]+/
+  # Display the relative url in search results
+  # Supports true (default) or false
+  rel_url: true
+  # Enable or disable the search button that appears in the bottom right corner of every page
+  # Supports true or false (default)
+  button: false
 
 aux_links:
   "Polyphony on GitHub":
-    - "//github.com/digital-fabric/polyphony"
+    - "//github.com/digital-fabric/polyphony"
+
+# Makes Aux links open in a new tab. Default is false
+aux_links_new_tab: false
+
+# Enable or disable heading anchors
+heading_anchors: true
+
+back_to_top: true
+back_to_top_text: "Back to top"
+
+footer_content: "Copyright &copy; 2018-2020 Sharon Rosner. Distributed by an <a href=\"https://github.com/digital-fabric/polyphony/tree/master/LICENSE.txt\">MIT license.</a>"
+
+# Footer "Edit this page on GitHub" link text
+gh_edit_link: true # show or hide edit this page link
+gh_edit_link_text: "Edit this page on GitHub"
+gh_edit_repository: "https://github.com/digital-fabric/polyphony" # the github URL for your repo
+gh_edit_branch: "master" # the branch that your docs is served from
+gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
+
+compress_html:
+  clippings: all
+  comments: all
+  endings: all
+  startings: []
+  blanklines: false
+  profile: false

data/docs/_sass/custom/custom.scss

@@ -1,30 +0,0 @@
-$nav-child-link-color: #9d9b9e;
-$link-color: $blue-000;
-
-.img-figure {
-  text-align: center;
-}
-
-#prevnext {
-  padding-top: 1em;
-}
-
-#prevnext span {
-}
-
-#prevnext span.prev {
-  float: left;
-  padding-right: 4em;
-}
-
-#prevnext span.next {
-  float: right;
-}
-
-#prevnext span.clear {
-  clear: both;
-}
-
-.h-align-center {
-  text-align: center;
-}

data/docs/_sass/overrides.scss

@@ -1,46 +0,0 @@
-.navigation-list-item.section-title {
-  padding-top: 0.75em;
-  padding-bottom: 0.75em;
-}
-
-span.section-title {
-  text-transform: uppercase;
-  font-weight: bold;
-  color: #888;
-}
-
-.navigation-list-item .navigation-list-child-list {
-  display: block;
-}
-
-.navigation-list-child-list {
-  padding-left: 0;
-
-  .navigation-list-item {
-    position: relative;
-
-    &::before {
-      position: absolute;
-      margin-top: 0.3em;
-      margin-left: -0.8em;
-      color: rgba($body-text-color, 0.3);
-      content: "";
-    }
-  }
-}
-
-a.navigation-list-link {
-  margin-left: 4px;
-  padding-left: 4px;
-  color: $nav-child-link-color;
-  font-weight: 600;
-}
-
-a.navigation-list-link.active {
-  margin-left: 0;
-  border-left: 4px #6ae solid;
-}
-
-a.navigation-list-link:hover {
-  color: $link-color;
-}

data/docs/_user-guide/index.md

@@ -0,0 +1,9 @@
+---
+layout: page
+title: User Guide
+has_children: true
+nav_order: 4
+---
+
+# User Guide
+{: .no_toc }

data/docs/api-reference/index.md

@@ -0,0 +1,9 @@
+---
+layout: page
+title: API Reference
+has_children: true
+nav_order: 5
+---
+
+# API Reference
+{: .no_toc }

data/docs/api-reference/polyphony-process.md

@@ -23,6 +23,6 @@ shell command. If a block is given, the child process is started using
 [`Polyphony#fork`](../polyphony/#fork-block---pid).
 
 ```ruby
-Polyphony::Process.watch('echo "Hello World"; sleep 1')
+spin { Polyphony::Process.watch('echo "Hello World"; sleep 1') }
 supervise(restart: :always)
 ```

data/docs/api-reference/thread.md

@@ -12,7 +12,7 @@ Polyphony enhances the core `Thread` class with APIs for switching and
 scheduling fibers, and reimplements some of its APIs such as `Thread#raise`
 using fibers which, incidentally, make it safe.
 
-Each thread has its own run queue and its own event selector. While running
+Each thread has its own run queue and its own system agent. While running
 multiple threads does not result in true parallelism in MRI Ruby, sometimes
 multithreading is inevitable, for instance when using third-party gems that
 spawn threads, or when calling blocking APIs that are not fiber-aware.

data/docs/faq.md

@@ -3,9 +3,19 @@ layout: page
 title: Frequently Asked Questions
 nav_order: 100
 ---
+
 # Frequently Asked Questions
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+- TOC
+{:toc}
+
+---
 
-### Why not just use callbacks instead of fibers?
+## 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
@@ -87,7 +97,7 @@ In conclusion:
 * Callbacks often lead to code bloat.
 * Callbacks are harder to debug.
 
-### If callbacks suck, why not use promises?
+## 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
@@ -96,7 +106,7 @@ 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?
+## 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
@@ -108,7 +118,7 @@ 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`?
+## 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
@@ -118,7 +128,7 @@ 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 does Polyphony reimplements core APIs such as `IO#read` and `Kernel#sleep`?
+## Why does Polyphony reimplements core APIs such as `IO#read` and `Kernel#sleep`?
 
 Polyphony "patches" some Ruby core and stdlib APIs, providing behavioraly
 compatible fiber-aware implementations. We believe Polyphony has the potential
@@ -126,7 +136,7 @@ to profoundly change the way concurrent Ruby apps are written. Polyphony is
 therefore designed to feel as much as possible like an integral part of the Ruby
 runtime.
 
-### Why is Polyphony not split into multiple gems?
+## 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
@@ -134,7 +144,7 @@ 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?
+## Can I use Polyphony in a multithreaded program?
 
 Yes, as of version 0.27 Polyphony implements per-thread fiber-scheduling. It is
 however important to note that Polyphony places the emphasis on a multi-fiber
@@ -148,7 +158,7 @@ are such a better fit for I/O bound Ruby programs. Threads should really be used
 when performing synchronous operations that are not fiber-aware, such as running
 an expensive SQLite query, or some other expensive system call.
 
-### How Does Polyphony Fit Into the Ruby's Future Concurrency Plans
+## How Does Polyphony Fit Into the Ruby's Future Concurrency Plans
 
 To our understanding, two things are currently on the horizon when it comes to
 concurrency in Ruby: [auto-fibers](https://bugs.ruby-lang.org/issues/13618), and
@@ -167,18 +177,18 @@ Polyphony's fiber-based concurrency model. Guilds will allow true parallelism
 and together with Polyphony will allow taking full advantage of multiple CPU
 cores in a single Ruby process.
 
-### Can I run Rails using Polyphony?
+## Can I run Rails using Polyphony?
 
 We haven't yet tested Rails with Polyphony, but most probably not. We do plan to
 support running Rails in an eventual release.
 
-### How can I contribute to Polyphony?
+## How can I contribute to Polyphony?
 
 The Polyphony repository is at
 [https://github.com/digital-fabric/polyphony](https://github.com/digital-fabric/polyphony).
 Feel free to create issues and contribute pull requests.
 
-### Who is behind this project?
+## 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

data/docs/getting-started/index.md

@@ -0,0 +1,10 @@
+---
+layout: page
+title: Getting Started
+description: Getting started with Polyphony
+has_children: true
+nav_order: 2
+---
+
+# Getting Started
+{: .no_toc }

data/docs/getting-started/installing.md

@@ -1,11 +1,8 @@
 ---
 layout: page
 title: Installing Polyphony
-nav_order: 1
 parent: Getting Started
-permalink: /getting-started/installing/
-prev_title: Home
-next_title: Tutorial
+nav_order: 1
 ---
 # Installing Polyphony
 
@@ -13,8 +10,7 @@ next_title: Tutorial
 
 In order to use Polyphony you need to have:
 
-- Linux or MacOS (sorry, there are no plans to support Windows for the time
-  being)
+- Linux or MacOS (support for Windows will come at a later stage)
 - Ruby (MRI) 2.6 or newer
 
 ## Installing the Polyphony Gem