polyphony 1.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e77c3b4fdef702445591a87298738cd5201bd958f3726b3815b7e31730466310
-  data.tar.gz: c7b88896b567c385793c8c6b5d4bbe2348bbb79d0a01cc6ef45779279337dc55
+  metadata.gz: f60a881ccb01cfce59bb3c84420bba574c2b1cd502df987b958a02b649fb4415
+  data.tar.gz: a138759174aba3944ca5e4faedff676d9c9807a50907ee03d18b2cec50f625c5
 SHA512:
-  metadata.gz: 86cb07f96328a3b40fcfda0d68653a9da06056d1a71c5e92fa29dc634e20c8a70b2c442a93983b5a3392197321474db68f4a8f3f74ac6072dbeb60e5215d63b6
-  data.tar.gz: ef502cd41765f9985add2e3a72de9fad3e5a13b26d737322c81b24972ec6f426cb3915397ae052700f5a84319b8493cc93827f7f4c7886f418ef7a464805504b
+  metadata.gz: 8167c82b2ebd31f4625dac5cbcf70a610b8e45d062b0ef5d4e2044493b6c9ca25a68b67d8b6948ece9ed3a414f2977c4f72175ce0fc63ce58545acc721f09d73
+  data.tar.gz: b91049699af9824aeb2fa051d859f35ff0f1b4ba289b7ea143a347a5ad8a882ec5a4fb42502742b3e4d19bf295f9a1d5bf3a9e15f38a061efdcf50a1741f0bce

data/.yardopts

@@ -20,6 +20,7 @@
 docs/readme.md
 docs/overview.md
 docs/tutorial.md
+docs/cheat-sheet.md
 docs/faq.md
 docs/concurrency.md
 docs/fiber-scheduling.md

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 1.0.1 2023-05-14
+
+- Add cheat-sheet
+- Improve and bring up to date doc files: overview, tutorial, FAQ
+- Fix image refs in docs (#99) (thanks @paulhenrich)
+
 ## 1.0 2023-05-11
 
 - More work on docs.
@@ -288,7 +294,8 @@
 
 ## 0.53.0 2021-04-23
 
-- Implement `Backend#splice`, `Backend#splice_to_eof`, along with `IO#splice`, `IO#splice_to_eof`
+- Implement `Backend#splice`, `Backend#splice_to_eof`, along with `IO#splice`,
+  `IO#splice_to_eof`
 
 ## 0.52.0 2021-02-28
 
@@ -530,7 +537,8 @@
 
 ## 0.38 2020-04-13
 
-- Fix post-fork segfault if parent process has multiple threads with active watchers
+- Fix post-fork segfault if parent process has multiple threads with active
+  watchers
 
 ## 0.37 2020-04-07
 
@@ -764,7 +772,8 @@
 ## 0.14 2019-05-17
 
 - Use chunked encoding in HTTP 1 response
-- Rewrite `IO#read`, `#readpartial`, `#write` in C (about 30% performance improvement)
+- Rewrite `IO#read`, `#readpartial`, `#write` in C (about 30% performance
+  improvement)
 - Add method delegation to `ResourcePool`
 - Optimize PG::Connection#async_exec
 - Fix `Coprocess#cancel!`

data/README.md

@@ -77,6 +77,7 @@ $ gem install polyphony
 
 - [Overview](docs/overview.md)
 - [Tutorial](docs/tutorial.md)
+- [Cheat-Sheet](docs/cheat-sheet.md)
 - [FAQ](docs/faq.md)
 
 ## Technical Discussion

data/TODO.md

@@ -37,9 +37,7 @@
 
 -----------------------------------------------------
 
-- Adapter for io/console (what does `IO#raw` do?)
-- Adapter for Pry and IRB (Which fixes #5 and #6)
-- allow backend selection at runtime
+- allow backend selection at runtime?
 - Debugging
   - Eat your own dogfood: need a good tool to check what's going on when some
     test fails
@@ -138,20 +136,10 @@
     }
     ```
 
-
-
-
-
-
-
 - Docs
-  - landing page:
-    - links to the interesting stuff
-      - benchmarks
   - explain difference between `sleep` and `suspend`
   - discuss using `snooze` for ensuring responsiveness when executing CPU-bound work
 
-
 ### Some more API work, more docs
 
 - sintra app with database access (postgresql)

data/docs/cheat-sheet.md

@@ -0,0 +1,248 @@
+# @title Cheat Sheet
+
+# Cheat Sheet
+
+## Fibers
+
+### Start a fiber
+
+```ruby
+fiber = spin do
+  do_some_work
+end
+```
+
+### Run a loop in a fiber
+
+```ruby
+fiber = spin_loop do
+  iterate_on_something
+end
+```
+
+### Stop a fiber
+
+```ruby
+fiber.stop
+# or:
+fiber.interrupt
+```
+
+### Wait for a fiber to terminate
+
+```ruby
+fiber.await
+# or:
+fiber.join
+```
+
+### Wait for multiple fibers to terminate
+
+```ruby
+Fiber.await(fiber1, fiber2, ...)
+# or:
+Fiber.join(fiber1, fiber2, ...)
+```
+
+### Raise an exception in a fiber
+
+```ruby
+fiber.raise(SomeException)
+# or:
+fiber.raise(SomeException, 'Exception message')
+```
+
+### Restart a fiber
+
+```ruby
+fiber.restart
+# or:
+fiber.reset
+```
+
+## Control Fiber Scheduling
+
+### Yield to other fibers during a lengthy CPU-bound operation
+
+```ruby
+def calculate_some_stuff(n)
+  acc = 0
+  n.times do |i|
+    acc += big_calc(acc, i)
+    snooze if (i % 1000) == 0
+  end
+end 
+```
+
+### Suspend fiber
+
+```ruby
+suspend
+```
+
+### Schedule fiber
+
+```ruby
+fiber.schedule
+# or:
+fiber.schedule(some_value)
+```
+
+## Message Passing
+
+### Send a message to a fiber
+
+```ruby
+fiber << message
+# or:
+fiber.send << message
+```
+### Receive a message
+
+```ruby
+message = receive
+# or, using deconstructing assign
+a, b, c = receive
+```
+
+## Using Timers and Sleeping
+
+### Sleep for a specific duration
+
+```ruby
+sleep 1 # sleeps for 1 second
+```
+
+### Sleep infinitely
+
+```ruby
+sleep
+# or:
+suspend
+```
+
+### Perform an operation repeatedly with a given time interval
+
+```ruby
+every(10) { do_something } # perform an operation once every 10 seconds
+```
+
+### Perform an operation repeatedly with a given frequency
+
+```ruby
+throttled_loop(10) { do_something } # perform an operation 10 times per second
+```
+
+### Timeout, raising an exception
+
+```ruby
+# On timeout, a Polyphony::Cancel exception is raised
+cancel_after(10) { do_something_slow } # timeout after 10 seconds
+
+# Or, using the stock Timeout API, raising a Timeout::Error
+Timeout.timeout(10) { do_something_slow }
+```
+
+### Timeout without raising an exception
+
+```ruby
+# On timeout, result will be set to nil
+result = move_on_after(10) { do_something_slow }
+
+# Or, with a specific value:
+result = move_on_after(10, with_value: 'foo') { do_something_slow }
+```
+
+### Resettable timeout
+
+```ruby
+# works with move_on_after as well
+cancel_after(10) do |timeout|
+  while (data = client.gets)
+    timeout&.reset
+    do_something_with_data(client)
+  end
+end
+```
+
+## Advanced I/O
+
+### Splice data between two file descriptors
+
+```ruby
+# At least one file descriptor should be a pipe
+dest.splice_from(source, 8192) #=> returns number of bytes spliced
+# or:
+IO.splice(src, dest, 8192)
+```
+
+### Splice data to EOF
+
+```ruby
+dest.splice_from(source, -8192) #=> returns number of bytes spliced
+# or:
+IO.splice(src, dest, -8192)
+```
+
+### Tee data between two file descriptors (allowing splicing data twice)
+
+```ruby
+dest2.tee_from(source, 8192)
+dest1.splice_from(source, 8192)
+# or:
+IO.tee(src, dest2)
+IO.splice(src, dest2)
+```
+
+### Splice data between two arbitrary file descriptors, without creating a pipe
+
+```ruby
+# This will automatically create a pipe, and splice data from source to
+# destination until EOF is encountered.
+IO.double_splice(src, dest)
+```
+
+### Create a pipe
+
+A `Polyphony::Pipe` instance encapsulates a pipe with two file descriptors. It
+can be used just like any other IO instance for reading, writing, splicing etc.
+
+```ruby
+pipe = Polyphony::Pipe.new
+# or:
+pipe = Polyphony.pipe
+```
+
+### Compress/uncompress data between two IOs
+
+```ruby
+IO.gzip(src, dest)
+IO.gunzip(src, dest)
+IO.deflate(src, dest)
+IO.inflate(src, dest)
+```
+
+### Accept connections in a loop
+
+```ruby
+server_socket.accept_loop do |conn|
+  handle_connection(conn)
+end
+```
+
+### Read data in a loop until EOF
+
+```ruby
+connection.read_loop do |data|
+  handle_data(data)
+end
+```
+
+### Read data in a loop and feed it to a parser
+
+```ruby
+unpacker = MessagePack::Unpacker.new
+reader = spin do
+  io.feed_loop(unpacker, :feed_each) { |msg| handle_msg(msg) }
+end
+```

data/docs/design-principles.md

@@ -43,12 +43,12 @@ programmers, a perplexing unfamiliar corner right at the heart of Ruby.
 
 ## The History of Polyphony
 
-Polyphony started as an experiment, but over about two years of slow, jerky
+Polyphony started as an experiment, but over about three 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
+community. Polyphony's design is both similar to and different than the projects
 mentioned above.
 
-Polyphony today as nothing like the way it began. A careful examination of the
+Polyphony today looks 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
@@ -153,3 +153,59 @@ Polyphony's design is based on the following principles:
     }
   end
   ```
+
+- Enhance Ruby's I/O capabilities by providing [additional
+  APIs](./advanced-io.md) for splicing (on Linux) and moving data between file
+  descriptors. Polyphony provides APIs for compressing / uncompressing data on
+  the fly between file descriptors. This in turn enables the creation of
+  arbitrarily-complex data manipulation pipelines that maximize performance and
+  provide automatic backpressure.
+
+## Emergent Patterns for Ruby Apps Using Polyphony
+
+During the development of Polyphony and its usage in a few small- and
+medium-size custom Ruby apps, a few patterns have emerged. We belive embracing
+these patterns will lead to better-written concurrent programs that take
+advantage of all the benefits provided by Polyphony. Here are some of them:
+
+- Infinite loops make sense for fibers: normally, developers are taught to avoid
+  writing infinite loops, and to make sure any loop will be ended at one point.
+  With Polyphony, however, a fiber can run an infinite loop, performing work
+  such as responding to messages received on its mailbox, without the programmer
+  having to worry about it blocking the entire program:
+
+  ```ruby
+  server = spin do
+    loop do
+      client, data = receive
+      result = do_something_with_data(data)
+      client << result
+    end
+  end
+  ```
+
+  In the above example, a `server` of some sorts runs an infinite loop, taking
+  messages off its mailbox and handling them, sending the result back to the
+  corresponding client fiber. The programmer does not need to worry about
+  signalling the `server` fiber when it's time to finish its work. A simple call
+  to `server.stop` will stop it, as of course will its parent fiber stopping.
+
+- Message passing between fibers as a means to synchronize and pass data between
+  different parts of the application. The message passing ability integrated
+  into Polyphony allows writing programs where each fiber is responsible for a
+  single task, and receives its work by popping messages off its mailbox. If we
+  reconsider the above example, here's how a client might talk to the `server`
+  fiber:
+
+  ```ruby
+  results = incoming_data.map do |data|
+    server << [Fiber.current, data]
+    receive
+  end
+  ```
+
+  Look at all the things we don't need to do: we don't need to worry about
+  synchronizing access to shared variables between the different parts of the
+  app, and we also don't need to worry about how to handle backpressure - the
+  work will progress as fast as the slowest part in the app, without any
+  requests accumulating unnecessarily.

data/docs/faq.md

@@ -115,7 +115,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 reimplement 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
@@ -123,20 +123,21 @@ 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?
+# Does Polyphony implement the FiberScheduler API?
 
-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
-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.
+`FiberScheduler` is an API that was added to Ruby 3.0. It's not an
+implementation, only an interface. There are several implementations of the
+`FiberScheduler` API, with varying levels of maturity. Polyphony has a very
+opinionated design that does not really parallel the `FiberScheduler` API. It
+might be possible, though, to develop a compatibility layer on top of Polyphony
+that implements the `FiberScheduler` API at some point in the future.
 
 ## 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
-concurrency model, which is highly beneficial for I/O-bound workloads, such as
-web servers and web apps.
+Yes. Polyphony fully supports multi-threaded programs, and implements per-thread
+fiber-scheduling. It is 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
@@ -145,25 +146,6 @@ 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
-
-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
-[guilds](https://olivierlacan.com/posts/concurrency-in-ruby-3-with-guilds/).
-While the auto-fibers proposal introduces an event reactor into Ruby and
-automates waiting for file descriptors to become ready, allowing scheduling
-other fibers meanwhile. It is still too early to see how Polyphony can coexist
-with that. Another proposal is the addition of a fiber-aware [event
-selector](https://bugs.ruby-lang.org/issues/14736). It is our intention to
-eventually contribute to the discussion in this area by proposing a uniform
-fiber scheduler interface that could be implemented in pure Ruby in order to
-support all platforms and multiple Ruby runtimes.
-
-The guilds proposal, on the other hand, promises to be a perfect match for
-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?
 
 We haven't yet tested Rails with Polyphony, but most probably not. We do plan to
@@ -178,5 +160,6 @@ Feel free to create issues and contribute pull requests.
 ## Who is behind this project?
 
 I'm Sharon Rosner, an independent software developer living in France. Here's my
-[github profile](https://github.com/noteflakes). You can contact me by writing to
-[sharon@noteflakes.com](mailto:sharon@noteflakes.com).
+[github profile](https://github.com/noteflakes). You can sponsor my open source
+work [here](https://github.com/sponsors/noteflakes). You can contact me by
+writing to [sharon@noteflakes.com](mailto:sharon@noteflakes.com).

data/docs/fiber-scheduling.md

@@ -66,29 +66,31 @@ Switchpoint will also occur when the currently running fiber has terminated.
 
 ## Scheduler-less scheduling
 
-Polyphony relies on [libev](http://software.schmorp.de/pkg/libev.html) for
-handling events such as I/O readiness, timers and signals. In most event
-reactor-based libraries and frameworks, such as `nio4r`, `EventMachine` or
-`node.js`, the entire application is run inside of a reactor loop, and event
-callbacks are used to schedule user-supplied code *from inside the loop*.
+Polyphony relies on [io_uring](https://man.archlinux.org/man/io_uring.7) or
+[libev](http://software.schmorp.de/pkg/libev.html) for handling I/O operations
+such as reading or writing to file descriptors, waiting for timers or processes.
+In most event reactor-based libraries and frameworks, such as `nio4r`,
+`EventMachine` or `node.js`, the entire application is run inside of a reactor
+loop, and event callbacks are used to schedule user-supplied code *from inside
+the loop*.
 
 In Polyphony, however, we have chosen a concurrency model that does not use a
 loop to schedule fibers. In fact, in Polyphony there's no outer reactor loop,
 and there's no *scheduler* per se running on a separate execution context.
 
 Instead, Polyphony maintains for each thread a run queue, a list of `:runnable`
-fibers. If no fiber is `:runnable`, Polyphony will run the libev event loop until
-at least one event has occurred. Events are handled by adding the corresponding
-fibers onto the run queue. Finally, control is transferred to the first fiber on
-the run queue, which will run until it blocks or terminates, at which point
-control is transferred to the next runnable fiber.
+fibers. If no fiber is `:runnable`, Polyphony will run the underlying event
+reactor (using io_uring or libev) until at least one event has occurred. Events
+are handled by adding the corresponding fibers onto the run queue. Finally,
+control is transferred to the first fiber on the run queue, which will run until
+it blocks or terminates, at which point control is transferred to the next
+runnable fiber.
 
 This approach has numerous benefits:
 
 - No separate reactor fiber that needs to be resumed on each blocking operation,
   leading to less context switches, and less bookkeeping.
-- Clear separation between the reactor code (the `libev` code) and the fiber
-  scheduling code.
+- Clear separation between the I/O backend code and the fiber scheduling code.
 - Much less time is spent in event loop callbacks, letting the event loop run
   more efficiently.
 - Fibers are switched outside of the event reactor code, making it easier to