polyphony 1.1.1 → 1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a30f7362ca02a1e3b3fe8a76394d5bca243f8dc774b3a6f3f7e9ffa81aac04f7
-  data.tar.gz: 6fa0684c3e4ddf3fe62ea6d40d5e49578e36042ff57d20848cff6da165ab6027
+  metadata.gz: d8069af9a528319585e1112ca1c1fc97981ae7106da100701691d7caf1478fdc
+  data.tar.gz: c5ec274b188332a18f8de7b595fad457f25cfc79bf903c05db0aaf7bf20507dc
 SHA512:
-  metadata.gz: 1eb08ca45b2129c25c5a1b023aea14fdbade30323a8f5db824f3c33c9b386f24cd541cfa7d536696c2ecd253dd7b4eeb976e87f53a93a59aa1ff96166e54fe05
-  data.tar.gz: 2f9145ea40f5d8aeb280cbc70249793805e770735c4758ff9f26f80138a752aacdf347e8e6705604a602ddec3216f33bc1797a00d9521585646dc2d8ccd432c4
+  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,12 @@
+## 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

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

@@ -72,6 +72,10 @@ 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
@@ -293,11 +297,15 @@ def send_compressed_chunked_response_from_io(socket, io)
   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
-data `io` into the pipe. We then serve data from the pipe to the socket using
+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

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}

data/examples/core/enumerator.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony'
+
+class ::Enumerator
+  def spin
+    map { |i| Object.spin { yield i } }
+  end
+
+  def concurrently(max_fibers: nil, &block)
+    return each_concurrently_with_fiber_pool(max_fibers, &block) if max_fibers
+
+    results = []
+    fibers = []
+    each_with_index do |i, idx|
+      fibers << Object.spin { results[idx] = block.(i) }
+    end
+    Fiber.await(fibers)
+    results
+  end
+
+  private
+
+  def each_concurrently_with_fiber_pool(max_fibers, &block)
+    fiber_count = 0
+    results = []
+    workers = []
+
+    each_with_index do |i, idx|
+      if fiber_count < max_fibers
+        workers << Object.spin do
+          loop do
+            item, idx = receive
+            break if item == :__stop__
+            results[idx] = block.(item)
+          end
+        end
+      end
+
+      fiber = workers.shift
+      fiber << [i, idx]
+      workers << fiber
+    end
+    workers.each { |f| f << :__stop__ }
+    Fiber.current.await_all_children
+    results
+  end
+end
+
+a = [1, 2, 3]
+
+# ff = a.map do |i|
+#   spin do
+#     puts "#{Fiber.current.inspect} #{i} >>"
+#     sleep rand(0.1..0.2)
+#     puts "#{Fiber.current.inspect} #{i} <<"
+#   end
+# end
+
+# Fiber.await(*ff)
+
+# puts; puts '*' * 40; puts
+
+# ff = a.each.spin do |i|
+#   puts "#{Fiber.current.inspect} #{i} >>"
+#   sleep 0.1
+#   puts "#{Fiber.current.inspect} #{i} <<"
+# end
+
+# Fiber.await(*ff)
+
+# puts; puts '*' * 40; puts
+
+# ff = a.each.concurrently do |i|
+#   puts "#{Fiber.current.inspect} #{i} >>"
+#   sleep 0.1
+#   puts "#{Fiber.current.inspect} #{i} <<"
+#   i * 10
+# end
+# p ff: ff
+
+puts; puts '*' * 40; puts
+
+ff = a.each.concurrently(max_fibers: 2) do |i|
+  puts "#{Fiber.current.inspect} #{i} >>"
+  sleep i
+  puts "#{Fiber.current.inspect} #{i} <<"
+  i * 10
+end
+
+p ff: ff

data/examples/io/https_server_sni_2.rb

@@ -28,7 +28,7 @@ server = Polyphony::Net.tcp_listen('localhost', 1234, opts)
 puts 'Serving HTTPS on port 1234'
 
 begin
-  server.accept_loop(false) do |socket|
+  server.accept_loop(ignore_errors: false) do |socket|
     spin do
       while (data = socket.gets("\n", 8192))
         if data.chomp.empty?

data/ext/polyphony/backend_common.c

@@ -8,6 +8,8 @@
 #include "ruby/io/buffer.h"
 #endif
 
+VALUE cBackend;
+
 inline void backend_base_initialize(struct Backend_base *base) {
   runqueue_initialize(&base->runqueue);
   runqueue_initialize(&base->parked_runqueue);
@@ -604,3 +606,12 @@ VALUE coerce_io_string_or_buffer(VALUE buf) {
       return StringValue(buf);
   }
 }
+
+inline VALUE Backend_for_current_thread(void) {
+  VALUE backend = rb_ivar_get(rb_thread_current(), ID_ivar_backend);
+  if (backend == Qnil) {
+    backend = rb_funcall(cBackend, ID_new, 0);
+    rb_ivar_set(rb_thread_current(), ID_ivar_backend, backend);
+  }
+  return backend;
+}

data/ext/polyphony/backend_common.h

@@ -10,6 +10,8 @@
 #include "ruby/io.h"
 #include "runqueue.h"
 
+extern VALUE cBackend;
+
 #ifndef HAVE_RB_IO_DESCRIPTOR
 static int rb_io_descriptor_fallback(VALUE io) {
   rb_io_t *fptr;

data/ext/polyphony/backend_io_uring.c

@@ -1965,7 +1965,7 @@ void Backend_unpark_fiber(VALUE self, VALUE fiber) {
 }
 
 void Init_Backend(void) {
-  VALUE cBackend = rb_define_class_under(mPolyphony, "Backend", rb_cObject);
+  cBackend = rb_define_class_under(mPolyphony, "Backend", rb_cObject);
   rb_define_alloc_func(cBackend, Backend_allocate);
 
   rb_define_method(cBackend, "initialize", Backend_initialize, 0);

data/ext/polyphony/backend_libev.c

@@ -1610,7 +1610,7 @@ void Backend_unpark_fiber(VALUE self, VALUE fiber) {
 void Init_Backend(void) {
   ev_set_allocator(xrealloc);
 
-  VALUE cBackend = rb_define_class_under(mPolyphony, "Backend", rb_cObject);
+  cBackend = rb_define_class_under(mPolyphony, "Backend", rb_cObject);
   rb_define_alloc_func(cBackend, Backend_allocate);
 
   rb_define_method(cBackend, "initialize", Backend_initialize, 0);

data/ext/polyphony/polyphony.h

@@ -25,7 +25,7 @@
   #define FIBER_TRANSFER(fiber, value) rb_funcall(fiber, ID_transfer, 1, value)
 #endif
 
-#define BACKEND() (rb_ivar_get(rb_thread_current(), ID_ivar_backend))
+#define BACKEND() Backend_for_current_thread()
 
 // SAFE is used to cast functions used in rb_ensure
 #define SAFE(f) (VALUE (*)(VALUE))(f)
@@ -95,6 +95,8 @@ VALUE Pipe_close(VALUE self);
 
 // Backend public interface
 
+VALUE Backend_for_current_thread();
+
 VALUE Backend_accept(VALUE self, VALUE server_socket, VALUE socket_class);
 VALUE Backend_accept_loop(VALUE self, VALUE server_socket, VALUE socket_class);
 VALUE Backend_connect(VALUE self, VALUE io, VALUE addr, VALUE port);