polyphony 0.28 → 0.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96b63d0e57950ea2983cfadab521cceaba97180fce4269575715a856d1beebdd
-  data.tar.gz: 42580ebe9a11620cc546474837983ae959aa239fba3a0c926eb62a40d9b66773
+  metadata.gz: fb34882b5a9cb5bbf2b1b27909795f96e5291fe953aeea53f6ebd4e95d8bd19f
+  data.tar.gz: c38af8c17d62b70fed44988182e70caba305eb9abbb3c4d1a8fdeda349031bae
 SHA512:
-  metadata.gz: b4f4f02373ff3f9f1780a90b5df09bdd8efc95dbe28bed7787915a474961fe1f687baeb6cf46431eda65a6719c9e98a46b44807d71496723d84fbe7b0841a582
-  data.tar.gz: 1582cdfa47593230dc64f1676a514cea09e36db37048e138f41f75a626a91acac0e6dd34d6962597b4016a57afb125a9913c1111474f3470543e75f1b4915b88
+  metadata.gz: ab9f3c212357aa7eedaee5f43c1b85ff28337e8bb1cc3d693fcc72ff02c49ddf55b211daccfd0eb516cfca1544e02312f10f5e59eb0903c55279cc5983a69ca3
+  data.tar.gz: 9d871f6e1c8013a13fc03f191d6e0ac7fb7766e723c73be3afcf2d870cea9595bc750c4d45c7efb1a61104ef0611e00a430baae6b3a0c5afcd4b2a859c8677f5

data/.rubocop.yml

@@ -58,10 +58,6 @@ Style/GlobalVars:
     - lib/polyphony/extensions/core.rb
     - examples/**/*.rb
 
-Style/ClassVars:
-  Exclude:
-    - lib/polyphony/core/coprocess.rb
-
 Layout/HashAlignment:
   EnforcedColonStyle: table
   EnforcedHashRocketStyle: table

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+0.29 2020-02-02
+---------------
+
+* Pass SignalException to main fiber
+* Add (restore) default thread pool
+* Prevent race condition in Thread#join
+* Add support for cross-thread fiber scheduling
+* Remove `#defer` global method
+* Prevent starvation of waiting fibers when using snooze (#7)
+* Improve tracing
+* Fix IRB adapter
+
 0.28 2020-01-27
 ---------------
 

data/Gemfile.lock

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

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 Sharon Rosner
+Copyright (c) 2020 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

data/README.md

@@ -1,15 +1,22 @@
-# Polyphony - Easy Concurrency for Ruby
+# Polyphony - Fine-Grained Concurrency for Ruby
 
-[DOCS](https://dfab.gitbook.io/polyphony) |
+[DOCS](https://digital-fabric.github.io/polyphony/) |
 [EXAMPLES](examples)
 
-> Polyphony \| pəˈlɪf\(ə\)ni \| _Music_ - the style of simultaneously combining a number of parts, each forming an individual melody and harmonizing with each other.
+> 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.
 
 ## What is Polyphony
 
-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 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.
-
-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.
+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.
 
 ## Features
 
@@ -18,26 +25,21 @@ Polyphony makes it possible to use normal Ruby built-in classes like `IO`, and `
 * Natural, sequential programming style that makes it easy to reason about
   concurrent code.
 * Abstractions and constructs for controlling the execution of concurrent code:
-  coprocesses, supervisors, cancel scopes, throttling, resource pools etc.
+  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`, `TCPSocket` and 
+* Use stdlib classes such as `TCPServer`, `TCPSocket` and
+  `OpenSSL::SSL::SSLSocket`.
 * 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)
-
 ## Documentation
 
 The complete documentation for Polyphony could be found on the
-[Polyphony website](https://dfab.gitbook.io/polyphony).
+[Polyphony website](https://digital-fabric.github.io/polyphony).
+
+## Contributing to Polyphony
+
+Issues and pull requests will be gladly accepted. Please use the [Polyphony git
+repository](https://github.com/digital-fabric/polyphony) as your primary point
+of departure for contributing.

data/Rakefile

@@ -10,6 +10,8 @@ Rake::ExtensionTask.new("gyro_ext") do |ext|
   ext.ext_dir = "ext/gyro"
 end
 
+task :recompile => [:clean, :compile]
+
 task :default => [:compile, :test]
 task :test do
   exec 'ruby test/run.rb'

data/TODO.md

@@ -1,9 +1,6 @@
 ## 0.29 Multithreaded fiber scheduling - some rough corners
 
 - Docs: explain difference between `sleep` and `suspend`
-- Write about threads: scheduling, etc
-- `Gyro_schedule_fiber` - schedule using fiber's associated thread (store thread
-  ref in fiber), instead of current thread
 - Check why first call to `#sleep` returns too early in tests. Check the
   sleep behaviour in a spawned thread.
 

data/docs/_includes/prevnext.html

@@ -0,0 +1,17 @@
+{%- for node in site.html_pages -%}
+  {%- if page.prev_title == node.title -%}
+    {%- assign prev_url = node.url -%}
+  {%- endif -%}
+  {%- if page.next_title == node.title -%}
+    {%- assign next_url = node.url -%}
+  {%- endif -%}
+{%- endfor -%}
+<div id="prevnext">
+  {%- if prev_url -%}
+    <span class="prev"><a href="{{prev_url | relative_url}}">☜ {{page.prev_title}}</a></span>
+  {%- endif -%}
+  {%- if next_url -%}
+    <span class="next"><a href="{{next_url | relative_url}}">{{page.next_title}} ☞</a></span>
+  {%- endif -%}
+  <span class="clear">&nbsp;</span>
+</div>

data/docs/_layouts/default.html

@@ -0,0 +1,106 @@
+---
+layout: table_wrappers
+---
+
+<!DOCTYPE html>
+
+<html lang="{{ site.lang | default: "en-US" }}">
+{% include head.html %}
+<body>
+  <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+    <symbol id="link" viewBox="0 0 16 16">
+      <title>Link</title>
+      <path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
+    </symbol>
+  </svg>
+
+  <div class="page-wrap">
+    <div class="side-bar">
+      <div class="site-header">
+        <a href="{{ site.url }}{{ site.baseurl }}" class="site-title lh-tight">{% include title.html %}</a>
+        <button class="menu-button fs-3 js-main-nav-trigger" data-text-toggle="Hide" type="button">Menu</button>
+      </div>
+
+      <div class="navigation main-nav js-main-nav">
+        {% include nav.html %}
+      </div>
+      <footer class="site-footer">
+        <p class="text-small text-grey-dk-000 mb-4">This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.</p>
+      </footer>
+    </div>
+    <div class="main-content-wrap js-main-content" tabindex="0">
+      <div class="main-content">
+        <div class="page-header js-page-header">
+          {% if site.search_enabled != false %}
+          <div class="search">
+            <div class="search-input-wrap">
+              <input type="text" class="js-search-input search-input" tabindex="0" placeholder="Search {{ site.title }}" aria-label="Search {{ site.title }}" autocomplete="off">
+              <svg width="14" height="14" viewBox="0 0 28 28" xmlns="http://www.w3.org/2000/svg" class="search-icon"><title>Search</title><g fill-rule="nonzero"><path d="M17.332 20.735c-5.537 0-10-4.6-10-10.247 0-5.646 4.463-10.247 10-10.247 5.536 0 10 4.601 10 10.247s-4.464 10.247-10 10.247zm0-4c3.3 0 6-2.783 6-6.247 0-3.463-2.7-6.247-6-6.247s-6 2.784-6 6.247c0 3.464 2.7 6.247 6 6.247z"/><path d="M11.672 13.791L.192 25.271 3.02 28.1 14.5 16.62z"/></g></svg>
+            </div>
+            <div class="js-search-results search-results-wrap"></div>
+          </div>
+          {% endif %}
+          {% if site.aux_links != nil %}
+            <ul class="list-style-none text-small aux-nav">
+              {% for link in site.aux_links %}
+                <li class="d-inline-block my-0{% unless forloop.last %} mr-2{% endunless %}"><a href="{{ link.last }}">{{ link.first }}</a></li>
+              {% endfor %}
+            </ul>
+          {% endif %}
+        </div>
+        <div class="page">
+          {% unless page.url == "/" %}
+            {% if page.parent %}
+              <nav class="breadcrumb-nav">
+                <ol class="breadcrumb-nav-list">
+                  {% if page.grand_parent %}
+                    <li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.grand_parent }}</a></li>
+                    <li class="breadcrumb-nav-list-item"><a href="{{ second_level_url }}">{{ page.parent }}</a></li>
+                  {% else %}
+                    <li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.parent }}</a></li>
+                  {% endif %}
+                  <li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
+                </ol>
+              </nav>
+            {% endif %}
+          {% endunless %}
+          <div id="main-content" class="page-content" role="main">
+            {% if site.heading_anchors != false %}
+              {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><use xlink:href=\"#link\"></use></svg>" anchorClass="anchor-heading" %}
+            {% else %}
+              {{ content }}
+            {% endif %}
+
+            {% if page.prev_title or page.next_title %}
+              {% include prevnext.html %}
+            {% endif %}
+
+          {% if page.has_children == true and page.has_toc != false %}
+            <hr>
+            <h2 class="text-delta">Table of contents</h2>
+            {% assign children_list = site.pages | sort:"nav_order" %}
+            <ul>
+              {% for child in children_list %}
+                {% if child.parent == page.title and child.title != page.title %}
+                <li>
+                  <a href="{{ child.url | absolute_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
+                </li>
+                {% endif %}
+              {% endfor %}
+            </ul>
+          {% endif %}
+
+          {% if site.footer_content != nil %}
+            <hr>
+            <footer role="contentinfo">
+              <p class="text-small text-grey-dk-000 mb-0">{{ site.footer_content }}</p>
+            </footer>
+          {% endif %}
+
+        </div>
+      </div>
+    </div>
+  </div>
+
+</body>
+</html>

data/docs/_sass/custom/custom.scss

@@ -1,5 +1,26 @@
+$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;
 }

data/docs/faq.md

@@ -14,8 +14,10 @@ base their entire API on the callback pattern.
 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 implementation of an echo server using
-EventMachine:
+code. It also often means having to write elaborate state machines to keep track
+of events happening at different points in time. Using fibers allows you to keep
+state in local variables. Consider the following implementation of an echo
+server using EventMachine:
 
 ```ruby
 require 'eventmachine'
@@ -139,12 +141,12 @@ however important to note that Polyphony places the emphasis on a multi-fiber
 concurrency model, which is highly beneficial for I/O-bound workloads, such as
 web servers and web apps.
 
-Because of Ruby's [global interpreter lock](https://en.wikipedia.org/wiki/Global_interpreter_lock),
-multiple threads can not in fact run in parallel, and this is actually one of
-the reasons fibers 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.
+Because of Ruby's [global interpreter
+lock](https://en.wikipedia.org/wiki/Global_interpreter_lock), multiple threads
+can not in fact run in parallel, and this is actually one of the reasons fibers
+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
 
@@ -172,8 +174,9 @@ support running Rails in an eventual release.
 
 ### 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.
+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?
 

data/docs/getting-started/installing.md

@@ -4,6 +4,8 @@ title: Installing Polyphony
 nav_order: 1
 parent: Getting Started
 permalink: /getting-started/installing/
+prev_title: Home
+next_title: A Gentle Introduction to Polyphony
 ---
 # Getting Started
 

data/docs/getting-started/tutorial.md

@@ -4,6 +4,8 @@ title: A Gentle Introduction to Polyphony
 nav_order: 2
 parent: Getting Started
 permalink: /getting-started/tutorial/
+prev_title: Installing Polyphony
+next_title: Design Principles
 ---
 # A Gentle Introduction to Polyphony
 
@@ -369,9 +371,9 @@ machine's location). Also notice how we just used `httparty` with fiber-level
 concurrency, without any boilerplate or employing special wrapper classes.
 
 Just as before, we suspend the main fiber after spinning off the worker fibers,
-in order to wait for everything else to be done. But if we needed to do other
-work? For example, we might want to collect the different local times into a
-hash to be processed later. In that case, we can use a `Supervisor`:
+in order to wait for everything else to be done. But what if we needed to do
+other work? For example, we might want to collect the different local times into
+a hash to be processed later. In that case, we can use a `Supervisor`:
 
 ```ruby
 def get_times(zones)

data/docs/index.md

@@ -2,8 +2,8 @@
 layout: page
 title: Home
 nav_order: 1
-description: Lorem ipsum
 permalink: /
+next_title: Installing Polyphony
 ---
 
 # Polyphony - fine-grained concurrency for Ruby
@@ -21,7 +21,6 @@ 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.
 
-
 ## Focused on Developer Happiness
 
 Polyphony is designed to make concurrent Ruby programming feel natural and
@@ -86,6 +85,6 @@ 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.
+Issues and pull requests will be gladly accepted. Please use the [Polyphony git
+repository](https://github.com/digital-fabric/polyphony) as your primary point
+of departure for contributing.

data/docs/technical-overview/concurrency.md

@@ -4,6 +4,8 @@ title: Concurrency the Easy Way
 nav_order: 2
 parent: Technical Overview
 permalink: /technical-overview/concurrency/
+prev_title: Design Principles
+next_title: How Fibers are Scheduled
 ---
 # Concurrency the Easy Way
 
@@ -36,37 +38,37 @@ resumed once the database has sent back its reply. Meanwhile, another
 computation is started that opens a socket to a remote service, and then
 suspends itself, waiting for the connection to be established.
 
-This form of concurrency, called cooperative concurrency \(in contrast to
-pre-emptive concurrency, like threads and processes\), offers many advantages,
+This form of concurrency, called cooperative concurrency (in contrast to
+pre-emptive concurrency, like in threads and processes), offers many advantages,
 especially for applications that are [I/O
 bound](https://en.wikipedia.org/wiki/I/O_bound). Fibers are very lightweight
-\(starting at about 20KB\), can be context-switched faster than threads or
+(starting at about 10KB), can be context-switched faster than threads or
 processes, and literally millions of them can be created on a single system -
 the only limiting factor is available memory.
 
-Polyphony takes Ruby's fibers and adds a way to schedule and switch between
-fibers automatically whenever a blocking operation is started, such as waiting
-for a TCP connection to be established, or waiting for an I/O object to be
-readable, or waiting for a timer to elapse. In addition, Polyphony patches the
-stock Ruby classes to support its concurrency model, letting developers use all
-of Ruby's stdlib, for example `Net::HTTP` and `Mail` while reaping the benefits
-of lightweight, highly performant, fiber-based concurrency.
+Polyphony takes Ruby's fibers and adds a way to schedule and switch between them
+automatically whenever a blocking operation is started, such as waiting for a
+TCP connection to be established, for incoming data on an HTTP conection, or for
+a timer to elapse. In addition, Polyphony patches the stock Ruby classes to
+support its concurrency model, letting developers use all of Ruby's stdlib, for
+example `Net::HTTP` and `Mail` while reaping the benefits of lightweight,
+fine-grained, performant, fiber-based concurrency.
 
 Writing concurrent applications using Polyphony's fiber-based concurrency model
-offers a significant performance advantage. Computational tasks can be broken
-down into many fine-grained concurrent operations that cost very little in
-memory and context-switching time. More importantly, this concurrency model lets
-developers express their ideas in a sequential manner, leading to source code
-that is easy to read and reason about.
+offers a significant performance advantage. Complex concurrent tasks can be
+broken down into many fine-grained concurrent operations with very low overhead.
+More importantly, this concurrency model lets developers express their ideas in
+a sequential fashion, leading to source code that is much easier to read and
+understand, compared to callback-style programming.
 
 ## Fibers - Polyphony's basic unit of concurrency
 
 Polyphony extends the core `Fiber` class with additional functionality that
 allows scheduling, synchronizing, interrupting and otherwise controlling running
-fibers. Polyphony makes sure any exception raised while a is running is [handled
-correctly](exception-handling.md). Moreover, fibers can communicate with each
-other using message passing, turning them into autonomous actors in a
-fine-grained concurrent environment.
+fibers. Polyphony makes sure any exception raised while a fiber is running is
+[handled correctly](exception-handling.md). Moreover, fibers can communicate
+with each other using message passing, turning them into autonomous actors in a
+highly concurrent environment.
 
 ## Higher-Order Concurrency Constructs
 

data/docs/technical-overview/design-principles.md

@@ -4,6 +4,8 @@ title: Design Principles
 nav_order: 1
 parent: Technical Overview
 permalink: /technical-overview/design-principles/
+prev_title: A Gentle Introduction to Polyphony
+next_title: Concurrency the Easy Way
 ---
 # Design Principles
 
@@ -13,9 +15,10 @@ applications in Ruby, by utilizing Ruby fibers together with the
 library. Polyphony's design is based on the following principles:
 
 - Polyphony's concurrency model should feel "baked-in". The API should allow
-  concurrency with minimal effort. Polyphny should allow creating small
-  concurrent programs with as little boilerplate code as possible. There
-  should be no calls to initialize the event reactor, or other ceremonial code:
+  concurrency with minimal effort. Polyphony should facilitate writing both
+  large apps and small scripts with as little boilerplate code as possible.
+  There should be no calls to initialize the event reactor, or other ceremonial
+  code:
 
   ```ruby
   require 'polyphony'
@@ -25,12 +28,12 @@ library. Polyphony's design is based on the following principles:
 
   puts 'going to sleep now'
   # wait for other fibers to terminate
-  sleep
+  suspend
   ```
 
 - Blocking operations should yield to other concurrent tasks without any
   decoration or wrapper APIs. This means no `async/await` notation, and no
-  built-in concept of deferred computation.
+  async callback-style APIs.
 
   ```ruby
   # in Polyphony, I/O ops block the current fiber, but implicitly yield to other
@@ -53,6 +56,7 @@ library. Polyphony's design is based on the following principles:
     }
   }
   ```
+
 - Polyphony should embrace Ruby's standard `raise/rescue/ensure` exception
   handling mechanism:
 
@@ -81,20 +85,8 @@ library. Polyphony's design is based on the following principles:
   }
   ```
 
-- The internal reactor design should embrace fibers rather than be based on
-  invoking callbacks. The internal design of most reactor libraries is based on
-  callbacks. The design for Polyphony should center on suspending and resuming
-  fibers:
-
-  ```ruby
-  # psuedo-code for Gyro::Timer, the internal timer class
-  def Gyro::Timer.await
-    @fiber = Fiber.current
-    # the libev event reactor uses callbacks for handling events, Polyphony uses
-    # callbacks for switching between fibers
-    EV.start_timer(@interval) { @fiber.transfer }
-  end
-  ```
+- The entire design should embrace fibers. There should be no callback-based
+  asynchronous APIs.
 
 - Use of extensive monkey patching of Ruby core modules and classes such as
   `Kernel`, `Fiber`, `IO` and `Timeout`. This allows porting over non-Polyphony
@@ -115,5 +107,5 @@ library. Polyphony's design is based on the following principles:
   end
   ```
 
-- Development of techniques and tools for coverting callback-based APIs to
+- Development of techniques and tools for converting callback-based APIs to
   fiber-based ones.

data/docs/technical-overview/exception-handling.md

@@ -4,6 +4,8 @@ title: Exception Handling
 nav_order: 4
 parent: Technical Overview
 permalink: /technical-overview/exception-handling/
+prev_title: How Fibers are Scheduled
+next_title: Extending Polyphony
 ---
 # Exception Handling
 
@@ -75,7 +77,28 @@ Exception.__disable_sanitized_backtrace__ = true
 ...
 ```
 
-## Cleaning up after exceptions
+## Exceptions and Fiber Scheduling
+
+Polyphony takes advantages of Ruby's `Fiber#transfer` API to allow interrupting
+fiber execution and raise cross-fiber exceptions. This is done by inspecting the
+return value of `Fiber#transfer`, which returns when the fiber resumes, at every
+[switchpoint](../fiber-scheduling/#switchpoints). If the return value is an
+exception, it is raised in the context of the resumed fiber, and is then subject
+to any `rescue` statements in the context of that fiber.
+
+Exceptions can be passed to arbitrary fibers by using `Fiber#raise`. They can also be manually raised in fibers by using `Fiber#schedule`:
+
+```ruby
+f = spin do
+  suspend
+rescue => e
+  puts e.message
+end
+
+f.schedule(RuntimeError.new('foo')) #=> will print 'foo'
+```
+
+## Cleaning Up After Exceptions - Using Ensure
 
 A major issue when handling exceptions is cleaning up - freeing up resources
 that have been allocated, cancelling ongoing operations, etc. Polyphony allows
@@ -133,3 +156,49 @@ will bubble up through the different enclosing fibers, until reaching the
 top-most level, that of the root fiber, at which point the exception will cause
 the program to halt and print an error message.
 
+## MoveOn and Cancel - Interrupting Fiber Execution
+
+In addition to enhancing Ruby's normal exception-handling mechanism, Polyphony
+provides two exception classes that used exclusively to interrupt fiber
+execution: `MoveOn` and `Cancel`. Both of these classes are used in various
+fiber-control APIs, and `MoveOn` exceptions in particular are handled in a
+particular manner by Polyphony. The difference between `MoveOn` and `Cancel` is
+that `MoveOn` stops fiber execution without the exception bubbling up. It can
+optionally provide an arbitrary return value for the fiber. `Cancel` will bubble
+up like all exceptions.
+
+The `MoveOn` and `Cancel` classes are normally used indirectly, through the
+`Fiber#interrupt` and `Fiber#cancel` APIs, and also through the use of [cancel
+scopes](#):
+
+```ruby
+f1 = spin { sleep 100; return 'foo' }
+f2 = spin { f1.await }
+...
+f1.interrupt('bar')
+f2.result #=> 'bar'
+
+f3 = spin { sleep 100 }
+...
+f3.cancel #=> will raise a Cancel exception
+```
+
+## Signal Handling and Termination
+
+Polyphony does not normally intercept process signals, though it is possible to
+intercept them using `Gyro::Signal` watchers. It is, however, recommended for
+the time being to not interfere with Ruby's normal signal processing.
+
+In Ruby there are three core exception classes are related to signal handling
+and process termination: `Interrupt` - raised upon receiving an `INT` signal;
+`SystemExit` - raised upon calling `Kernel#exit`; and `SignalException` - raised
+upon receiving other signals.
+
+These exceptions are raised on the main thread and in a multi-fiber environment
+can occur in any fiber, as long as it is the currently running fiber. In
+Polyphony, when these exceptions are raised in a fiber other than the main
+fiber, they will be effectively tranferred to the main fiber for processing.
+
+This means that any handlers for these three exception classes should be put
+only in the main fiber. This mechanism also helps with showing a correct
+backtrace for these exceptions.

data/docs/technical-overview/extending.md

@@ -4,6 +4,7 @@ title: Extending Polyphony
 nav_order: 5
 parent: Technical Overview
 permalink: /technical-overview/extending/
+prev_title: Exception Handling
 ---
 # Extending Polyphony