polyphony 1.1 → 1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61fa840f595a0e75da1d6e1b761506b18fa90d5a94b25ce5832d22aae2e08fbd
-  data.tar.gz: 7d3a79225f68bb889ff0491ced1249c2679a222a3f79a5c4cf48f9571865ebc4
+  metadata.gz: d8069af9a528319585e1112ca1c1fc97981ae7106da100701691d7caf1478fdc
+  data.tar.gz: c5ec274b188332a18f8de7b595fad457f25cfc79bf903c05db0aaf7bf20507dc
 SHA512:
-  metadata.gz: 32d61cf7e0858e704fc39fe317048e3e531afcf97da70b9b3d1e4b59a078e2f5c8c65a3f72c656b61285df9e5c99d7430938403560ca6e8e7aa5d920dada274e
-  data.tar.gz: c5c1488b1cec55810ffccf8116d70e8312ccb7d93875c1047ab7608595eb81fda9601f44ef308b3e1f35319d683b6ceda423284c9cda76c6f44882a7341e681a
+  metadata.gz: f4e8fbd79cce5062a1fa054838186c925fa626c29faf86f589889f418838b681923863d07603036c2276bd3644ce99eac1f84cdc57b7c57e97787bceec6f4cd0
+  data.tar.gz: 22dbe0e38bc0d46ac1dcd543b0ae2b5e4a282c286f6dd40d823347542cbb37e2f21cf3c7c5503389f80f4b057b644c19c683d346a3500ada6a39e83bdbd1516f

data/.github/workflows/test.yml

@@ -8,7 +8,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        ruby: ['3.0', '3.1', '3.2', 'head']
+        ruby: ['3.1', '3.2', 'head']
 
     name: >-
       ${{matrix.os}}, ${{matrix.ruby}}

data/.github/workflows/test_io_uring.yml

@@ -8,7 +8,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        ruby: ['3.0', '3.1', '3.2', 'head']
+        ruby: ['3.1', '3.2', 'head']
 
     name: >-
       ${{matrix.os}}, ${{matrix.ruby}}

data/.rubocop.yml

@@ -64,8 +64,7 @@ Layout/HashAlignment:
 
 Naming/AccessorMethodName:
   Exclude:
-    - lib/polyphony/http/server/http1.rb
-    - lib/polyphony/http/server/http2_stream.rb
+    - lib/polyphony/extensions/fiber.rb
     - examples/**/*.rb
 
 Naming/MethodName:
@@ -74,16 +73,11 @@ Naming/MethodName:
 
 Lint/SuppressedException:
   Exclude:
-    - lib/polyphony/http/server/http1.rb
-    - lib/polyphony/http/server/http2.rb
-    - lib/polyphony/http/server/http2_stream.rb
-    - lib/polyphony/http/server.rb
     - examples/**/*.rb
 
 Metrics/MethodLength:
   Max: 12
   Exclude:
-    - lib/polyphony/http/server/rack.rb
     - lib/polyphony/extensions/io.rb
     - lib/polyphony/extensions/fiber.rb
     - test/**/*.rb
@@ -96,7 +90,6 @@ Metrics/ModuleLength:
 
 Metrics/ClassLength:
   Exclude:
-    - lib/polyphony/http/server/http1.rb
     - lib/polyphony/extensions/io.rb
     - lib/polyphony/extensions/fiber.rb
     - lib/polyphony/extensions/object.rb
@@ -176,6 +169,21 @@ Lint/RaiseException:
 Lint/StructNewOverride:
   Enabled: true
 
+Style/NegatedIf:
+  Enabled: false
+
+Style/NegatedWhile:
+  Enabled: false
+
+Style/CombinableLoops:
+  Enabled: false
+
+Style/InfiniteLoop:
+  Enabled: false
+
+Style/RedundantReturn:
+  Enabled: false
+
 Style/ExponentialNotation:
   Enabled: true
 

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 1.2 2023-06-17
+
+- Require Ruby 3.1 or newer
+- Add cancellation doc page
+- Cleanup code
+- Accept array of fiber in `Fiber.await` (in addition to accepting multiple fibers)
+- Automatically create backend for thread if not already created (#100)
+- Fix trap API when used with debug gem (#100)
+
+## 1.1.1 2023-06-08
+
+- Minor improvements to documentation
+
 ## 1.1 2023-06-08
 
 - Add advanced I/O doc page

data/README.md

@@ -51,7 +51,7 @@ the hood, Polyphony uses
 In order to use Polyphony you need to have:
 
 - Linux or MacOS (support for Windows will come at a later stage)
-- Ruby (MRI) 3.0 or newer
+- Ruby (MRI) 3.1 or newer
 
 ### Installing the Polyphony Gem
 
@@ -77,6 +77,7 @@ $ gem install polyphony
 
 - [Overview](docs/overview.md)
 - [Tutorial](docs/tutorial.md)
+- [All About Cancellation: How to Stop Concurrent Operations](docs/cancellation.md)
 - [Advanced I/O with Polyphony](docs/advanced-io.md)
 - [Cheat-Sheet](docs/cheat-sheet.md)
 - [FAQ](docs/faq.md)

data/docs/advanced-io.md

@@ -1,5 +1,7 @@
 # @title Advanced I/O with Polyphony
 
+# Advanced I/O with Polyphony
+
 ## Using splice for moving data between files and sockets
 
 Splice is linux-specific API that lets you move data between two file
@@ -10,12 +12,15 @@ size. Using splice, you can avoid the cost of having to load a file's content
 into memory, in order to send it to a TCP connection.
 
 In order to use `splice`, at least one of the file descriptors involved needs to
-be a pipe. This is because in Linux, pipes are actually kernel buffers. The
-normal way of using splice is that first you splice data from the source fd to
-the pipe (to its *write* fd), and then you splice data from the pipe (from its
-*read* fd) to the destination fd.
+be a pipe. This is because in Linux, pipes are actually kernel buffers. The idea
+is that you first move data from a source fd into a kernel buffer, then you move
+data from the kernel buffer to the destination fd. In some cases, this lets the
+Linux kernel completely avoid having to copy data in order to move it from the
+source to the destination. So the normal way of using splice is that first you
+splice data from the source fd to the pipe (to its *write* fd), and then you
+splice data from the pipe (from its *read* fd) to the destination fd.
 
-Here's how we do splicing using Polyphony:
+Here's how you can use splice with Polyphony:
 
 ```ruby
 def send_file_using_splice(src, dest)
@@ -25,24 +30,29 @@ def send_file_using_splice(src, dest)
   pipe = Polyphony::Pipe.new
   loop do
     # splices data from src to the pipe
-    bytes_spliced = IO.splice(src, pipe, 2**14)
-    break if bytes_spliced == 0 # EOF
+    bytes_available = IO.splice(src, pipe, 2**14)
+    break if bytes_available == 0 # EOF
 
     # splices data from the pipe to the dest
-    IO.splice(pipe, dest, bytes_spliced)
+    while (bytes_avilable > 0)
+      written = IO.splice(pipe, dest, bytes_avilable)
+      bytes_avilable -= written
+    end
   end
 end
 ```
 
 Let's examine the code above. First of all, we have a loop that repeatedly
-splices data in chunks of 16KB. We break from the loop once EOF is encountered.
-Secondly, on each iteration of the loop we perform two splice operations
-sequentially. So, we need to repeatedly perform two splice operations, one after
-the other. Would there be a better way to do this?
+splices data in chunks of 16KB, using the `IO.splice` API provided by Polyphony.
+We break from the loop once EOF is encountered. Secondly, for moving data from
+the pipe to the destination, we need to make sure *all* data made avilable on
+the pipe has been spliced to the destination, since the call to `IO.splice` can
+actually write fewer bytes than specified. So, we need to repeatedly perform two
+splice operations, one after the other, and we need to make sure all data is
+spliced to the destination. Would there be a better way to do this?
 
-Fortunately, Polyphony provides just the tools needed to do that. Firstly, we
-can tell Polyphony to splice data repeatedly until EOF is encountered by passing
-a negative max size:
+Fortunately, with Polyphony there is! Firstly, we can tell Polyphony to splice
+data repeatedly until EOF is encountered by passing a negative max size:
 
 ```ruby
 IO.splice(src, pipe, -2**14)
@@ -62,25 +72,29 @@ def send_file_using_splice(src, dest)
   end
   IO.splice(pipe, dest, -2**14)
 end
+
+# +----+  IO.splice()  +------+  IO.splice()  +--------+
+# | io |-------------->| pipe |-------------->| socket |
+# +----+               +------+               +--------+
 ```
 
 There are a few things to notice here: While we have two concurrent operations
-running in two separate fibers, their are still inter-dependent in their
-individual progress, as one is filling a kernel buffer, and the other is
-flushing it, and thus the progress of whole will be bound by the slowest
-operation.
-
-Imagine an HTTP server that serves a large file to a slow client, or a client
-with a bad network connection. The web server is perfectly capable of reading
-the file from its disk very fast, but sending data to the HTTP client can be
-much much slower. The second splice operation, splicing from the pipe to the
-destination, will flush the kernel much more slowly that it is being filled. At
-a certain point, the buffer is full, and the first splice operation from the
-source to the pipe cannot continue. It will need to wait for the other splice
-operation to progress, in order to continue filling the buffer. This is called
-back-pressure propagation, and we get it automatically.
-
-So let's look at all the things we didn't need to do: we didn't need to read
+running in two separate fibers, they are still inter-dependent in their
+progress, as one is filling a kernel buffer, and the other is flushing it, and
+thus the progress of the whole will be bound by the slowest operation.
+
+Take an HTTP server that serves a large file to a slow client, or a client with
+a bad network connection. The web server is perfectly capable of reading the
+file from its disk very fast, but sending data to the HTTP client can be much
+much slower. The second splice operation, splicing from the pipe to the
+destination, will flush the kernel buffer much more slowly that it is being
+filled. At a certain point, the buffer is full, and the first splice operation
+from the source to the pipe cannot continue. It will need to wait for the other
+splice operation to progress, in order to continue filling the buffer. This is
+called back-pressure propagation, it's a good thing, and we get it
+automatically.
+
+Let's now look at all the things we didn't need to do: we didn't need to read
 data into a Ruby string (which is costly in CPU time, in memory, and eventually
 in GC pressure), we didn't need to manage a buffer and take care of
 synchronizing access to the buffer. We got to move data from the source to the
@@ -97,17 +111,17 @@ end
 ```
 
 The `IO.double_splice` creates a pipe and repeatedly splices data concurrently
-from the source to pipe and from the pipe to the destination until the source is
-exhausted. All this, without needing to instantiate a `Polyphony::Pipe` object,
-and without needing to spin up a second fiber, further minimizing memory use and
-GC pressure.
+from the source to the pipe and from the pipe to the destination until the
+source is exhausted. All this, without needing to instantiate a
+`Polyphony::Pipe` object, and without needing to spin up a second fiber, further
+minimizing memory use and GC pressure.
 
 ## Compressing and decompressing in-flight data
 
 You might be familiar with Ruby's [zlib](https://github.com/ruby/zlib) gem (docs
 [here](https://rubyapi.org/3.2/o/zlib)), which can be used to compress and
 uncompress data using the popular gzip format. Imagine we want to implement an
-HTTP server that can serve files compresszed using gzip:
+HTTP server that can serve files compressed using gzip:
 
 ```ruby
 def serve_compressed_file(socket, file)
@@ -117,10 +131,10 @@ def serve_compressed_file(socket, file)
 end
 ```
 
-In the above example, we have read the file contents into a Ruby string, then
-passed the contents to `Zlib.gzip`, which returned the compressed contents in
-another Ruby string, then wrote the compressed data to the socket. We can see
-how this can lead to large allocations of memory (if the file is large), and
+In the above example, we read the file contents into a Ruby string, then pass
+the contents to `Zlib.gzip`, which returns the compressed contents in another
+Ruby string, then write the compressed data to the socket. We can see how this
+can lead to lots of memory allocations (especially if the file is large), and
 more pressure on the Ruby GC. How can we improve this?
 
 One way would be to utilise Zlib's `GzipWriter` class:
@@ -165,7 +179,7 @@ through some object that parses the data, or otherwise manipulates it. Normally,
 we would write a loop that repeatedly reads the data from the source, then
 passes it to the parser object. Imagine we have data transmitted using the
 `MessagePack` format that we need to convert back into its original form. We
-might do something like this:
+might do something like the folowing:
 
 ```ruby
 def with_message_pack_data_from_io(io, &block)
@@ -215,10 +229,93 @@ With `IO#feed_loop` we get to write even less code, and as with `IO#read_loop`,
 `IO#feed_loop` is implemented at the C-extension level using a tight loop that
 maximizes performance.
 
+## Fast and easy chunked transfer-encoding in HTTP/1
+
+[Chunked transfer
+encoding](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) is a great
+way to serve HTTP responses of arbitrary size, because we don't need to know
+their size in advance, which means we don't necessarily need to hold them in
+memory, or perform expensive fstat calls to get file metadata. Sending HTTP
+responses in chunked transfer encoding is simple enough:
+
+```ruby
+def send_chunked_response_from_io(socket, io)
+  while true
+    chunk = io.read(MAX_CHUNK_SIZE)
+    socket << "#{chunk.bytesize.to_s(16)}\r\n#{chunk}\r\n"
+    break if chunk.empty?
+  end
+end
+```
+
+Note how we read the chunk into memory and then send it on to the client. Would
+it be possible to splice the data instead? Let's see how that would look:
+
+```ruby
+def send_chunked_response_from_io(socket, io)
+  pipe = Polyphony::Pipe.new
+  while true
+    bytes_spliced = IO.splice(io, pipe, MAX_CHUNK_SIZE)
+    socket << "#{bytes_spliced.to_s(16)}\r\n"
+    IO.splice(pipe, socket, bytes_spliced) if bytes_spliced > 0
+    socket << "\r\n"
+    break if bytes_spliced == 0
+  end
+end
+```
+
+In the code above, while we avoid having to read chunks of the source data into
+Ruby strings, we now perform 3 I/O operations for each chunk: writing the chunk
+size, splicing the data from the pipe (the kernel buffer), and finally writing
+the `"\r\n"` delimiter. We can probably write some more complex logic to reduce
+this to 2 operations (coalescing the two write operations into one), but still
+this implementation involves a lot of back and forth between our code, the
+Polyphony I/O backend, and the operating system.
+
+Fortunately, Polyphony provides a special API for sending HTTP chunked
+responses:
+
+```ruby
+def send_chunked_response_from_io(socket, io)
+  IO.http1_splice_chunked(io, socket, MAX_CHUNK_SIZE)
+end
+```
+
+A single method call replaces the whole mechanism we devised above, and in
+addition Polyphony makes sure to perform it with the minimum possible number of
+I/O operations!
+
+# Sending compressed data using chunked transfer encoding
+
+We can now combine the different APIs discussed above to create even more
+complex behaviour. Let's see how we can send an HTTP response using compressed
+content encoding and chunked transfer encoding:
+
+```ruby
+def send_compressed_chunked_response_from_io(socket, io)
+  pipe = Polyphony::Pipe.new
+  spin { IO.gzip(io, pipe) }
+  IO.http1_splice_chunked(pipe, socket, MAX_CHUNK_SIZE)
+end
+
+# +----+  IO.gzip()  +------+  IO.http1_splice_chunked()  +--------+
+# | io |------------>| pipe |---------------------------->| socket |
+# +----+             +------+                             +--------+
+```
+
+The code above looks simple enough, but it actually packs a lot of power in just
+3 lines of code: we create a pipe, then spin up a fiber that compresses data
+from `io` into the pipe. We then splice data from the pipe to the socket using
+chunked transfer encoding. As discussed above, we do this without actually
+allocating any Ruby strings for holding the data, we take maximum advantage of
+kernel buffers (a.k.a. pipes) and we perform the two operations - compressing
+the data and sending it to the client - concurrently.
+
 ## Conclusion
 
 In this article we have looked at some of the advanced I/O functionality
-provided by Polyphony, which lets us write less code, have it run faster, and
-minimize memory allocations and pressure on the Ruby GC. Feel free to browse the
-[IO examples](https://github.com/digital-fabric/polyphony/tree/master/examples/io)
+provided by Polyphony, which lets us write less code, have it run faster, have
+it run concurrently, and minimize memory allocations and pressure on the Ruby
+GC. Feel free to browse the [IO
+examples](https://github.com/digital-fabric/polyphony/tree/master/examples/io)
 included in Polyphony.

data/docs/cancellation.md

@@ -0,0 +1,213 @@
+# @title All About Cancellation: How to Stop Concurrent Operations
+
+# All About Cancellation: How to Stop Concurrent Operations
+
+## The Problem of Cancellation
+
+Being able to cancel an operation is an important aspect of concurrent
+programming. When you have multiple operations going on at the same time, you
+want to be able to stop an operation in certain circumstances. Imagine sending a
+an HTTP request to some server, and waiting for it to respond. We can wait
+forever, or we can use some kind of mechanism for stopping the operation and
+declaring it a failure. This mechanism, which is generally called cancellation,
+plays a crucial part in how Polyphony works. Let's examine how operations are
+cancelled in Polyphony.
+
+## Cancellation in Polyphony
+
+In Polyphony, every operation can be cancelled in the same way, using the same
+APIs. Polyphony provides multiple APIs that can be used to stop an ongoing
+operation, but the underlying mechanism is always the same: the fiber running
+the ongoing operation is scheduled with an exception.
+
+Let's revisit how fibers are run in Polyphony (this is covered in more detail in
+the overview document). When a waiting fiber is ready to continue, it is
+scheduled with the result of the operation which it was waiting for. If the
+waiting fiber is scheduled with an exception *before* the operation it is
+waiting for is completed, the operation is stopped, and the exception is raised
+in the context of the fiber once it is switched to. What this means is that any
+fiber waiting for a long-running operation to complete can be stopped at any
+moment, with Polyphony taking care of actually stopping the operation, whether
+it is reading from a file, or from a socket, or waiting for a timer to elapse.
+
+On top of this general mechanism of cancellation, Polyphony provides
+cancellation APIs with differing semantics that can be employed by the
+developer. For example, `move_on_after` can be used to stop an operation after a
+timeout without raising an exception, while `cancel_after` can be used to raise
+an exception that must be handled. There's also the `Fiber#restart` API which,
+as its name suggests, allows one to restart any fiber, which might be very
+useful for retrying complex operations.
+
+Let's examine how a concurrent operation is stopped in Polyphony:
+
+```ruby
+sleeper = spin { sleep 1 }
+sleep 0.5
+sleeper.raise 'Foo'
+```
+
+In the example above, we spin up a fiber that sleeps for 1 second, we then sleep
+for half a second, and cancel `sleeper` by raising an exception in its context.
+This causes the sleep operation to be cancelled and the fiber to be stopped. The
+exception is further propagated to the context of the main fiber, and the
+program finally exits with an exception message.
+
+Another way to stop a concurrent operation is to use the `Fiber#move_on` method,
+which causes the fiber to stop, but without raising an exception:
+
+```ruby
+sleeper = spin { sleep 1; :foo }
+sleep 0.5
+sleeper.move_on :bar
+result = sleeper.await #=> :bar
+```
+
+Using `Fiber#move_on`, we avoid raising an exception which then needs to be
+rescued, and instead cause the fiber to stop, with its return value being the
+value given to `Fiber#move_on`. In the code above, the fiber's result will be
+set to `:bar` instead of `:foo`.
+
+## Using Timeouts
+
+Timeouts are probably the most common reason for cancelling an operation. While
+different Ruby gems provide their own APIs and mechanisms for setting timeouts
+(core Ruby has also recently introduced timeout settings for IO operations),
+Polyphony provides a uniform interface for stopping *any* long-running operation
+based on a timeout, using either the core ruby `Timeout` class, or the
+`move_on_after` and `cancel_after` that Polyphony provides.
+
+Before we discuss the different timeout APIs, we can first explore how to create
+a timeout mechanism from scratch in Polyphony:
+
+```ruby
+class MyTimeoutError < RuntimeError
+end
+
+def with_timeout(duration)
+  timeout_fiber = spin do
+    sleep duration
+    raise MyTimeoutError
+  end
+  yield
+ensure
+  timeout_fiber.stop # this is the same as timeout_fiber.move_on
+end
+
+# Usage example:
+with_timeout(5) { sleep 1; :foo } #=> :foo
+with_timeout(5) { sleep 10; :bar } #=> MyTimeoutError raised!
+```
+
+In the code above, we create a `with_timeout` method that takes a duration
+argument. It starts by spinning up a fiber that will sleep for the given
+duration, then raise a custom exception. It then runs the given block by calling
+`yield`. If the given block stops running before the timeout, it exists
+normally, not before making sure to stop the timeout fiber. If the given block
+runs longer than the timeout, the exception raised by the timeout fiber will be
+propagated to the fiber running the block, causing it to be stopped.
+
+Now that we have an idea of how we can construct timeouts, let's look at the
+different timeout APIs included in Polyphony:
+
+```ruby
+# Timeout without raising an exception
+move_on_after(5) { ... }
+
+# Timeout without raising an exception, returning an arbitrary value
+move_on_after(5, with_value: :foo) { ... } #=> :foo (in case of a timeout)
+
+# Timeout raising an exception
+cancel_after(5) { ... } #=> raises a Polyphony::Cancel exception
+
+# Timeout raising a custom exception
+cancel_after(5, with_exception: MyExceptionClass) { ... } #=> raises the given exception
+
+# Timeout using the Timeout API
+Timeout.timeout(5) { ... } #=> raises Timeout::Error
+```
+
+## Resetting Ongoing Operations
+
+In addition to offering a uniform API for cancelling operations and setting
+timeouts, Polyphony also allows you to reset, or restart, ongoing operations.
+Let's imagine an active search feature that shows the user search results while
+they're typing their search term. How we go about implementing this? We would
+like to show the user search results, but if the user hits another key before
+the results are received from the database, we'd like to cancel the operation
+and relaunch the search. Let's see how Polyphony let's us do this:
+
+```ruby
+searcher = spin do
+  peer, term = receive
+  results = get_search_results_from_db(term)
+  peer << results
+end
+
+def search_term_updated(term)
+  spin do
+    searcher.restart
+    searcher << [Fiber.current, term]
+    results = receive
+    update_search_results(results)
+  end
+end
+```
+
+In the example above we use fiber message passing in order to communicate
+between two concurrent operations. Each time `search_term_updated` is called, we
+*restart* the `searcher` fiber, send the term to it, wait for the results and
+them update them in the UI.
+
+## Resettable Timeouts
+
+Here's another example of restarting: we have a TCP server that accepts
+connection but would like to close connections after one minute of inactivity.
+We can use a timeout for that, but each time we receive data from the client, we
+need to reset the timeout. Here's how we can do this:
+
+```ruby
+def handle_connection(conn)
+  timeout = spin do
+    sleep 60
+    raise Polyphony::Cancel
+  end
+  conn.recv_loop do |msg|
+    timeout.reset # same as timeout.restart
+    handle_message(msg)
+  end
+rescue Polyphony::Cancel
+  puts 'Closing connection due to inactivity!'
+ensure
+  timeout.stop
+end
+
+server.accept_loop { |conn| handle_connection(conn) }
+```
+
+In the code above, we create a timeout fiber that sleeps for one minute, then
+raises an exception. We then run a loop waiting for messages from the client,
+and each time a message arrives we reset the timeout. In fact, the standard
+`#move_on_after` and `#cancel_after` APIs also propose a way to reset timeouts.
+Let's examine how to do just that:
+
+```ruby
+def handle_connection(conn)
+  cancel_after(60) do |timeout|
+    conn.recv_loop do |msg|
+      timeout.reset
+      handle_message(msg)
+    end
+  end
+rescue Polyphony::Cancel
+  puts 'Closing connection due to inactivity!'
+end
+
+server.accept_loop { |conn| handle_connection(conn) }
+```
+
+Here, instead of hand-rolling our own timeout mechanism, we use `#cancel_after`
+but give it a block that takes an argument. When the block is called, this
+argument is actually the timeout fiber that `#cancel_after` spins up, which lets
+us reset it just like in the example before. Also notice how we don't need to
+cleanup the timeout in the ensure block, as `#cancel_after` takes care of it by
+itself.

data/docs/readme.md

@@ -53,7 +53,7 @@ the hood, Polyphony uses
 In order to use Polyphony you need to have:
 
 - Linux or MacOS (support for Windows will come at a later stage)
-- Ruby (MRI) 3.0 or newer
+- Ruby (MRI) 3.1 or newer
 
 ### Installing the Polyphony Gem
 
@@ -79,6 +79,7 @@ $ gem install polyphony
 
 - {file:/docs/overview.md           Overview}
 - {file:/docs/tutorial.md           Tutorial}
+- {file:/docs/cancellation.md       All About Cancellation: How to Stop Concurrent Operations}
 - {file:/docs/advanced-io.md        Advanced I/O with Polyphony}
 - {file:/docs/cheat-sheet.md        Cheat-Sheet}
 - {file:/docs/faq.md                FAQ}