polyphony 1.0.1 → 1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f60a881ccb01cfce59bb3c84420bba574c2b1cd502df987b958a02b649fb4415
-  data.tar.gz: a138759174aba3944ca5e4faedff676d9c9807a50907ee03d18b2cec50f625c5
+  metadata.gz: 61fa840f595a0e75da1d6e1b761506b18fa90d5a94b25ce5832d22aae2e08fbd
+  data.tar.gz: 7d3a79225f68bb889ff0491ced1249c2679a222a3f79a5c4cf48f9571865ebc4
 SHA512:
-  metadata.gz: 8167c82b2ebd31f4625dac5cbcf70a610b8e45d062b0ef5d4e2044493b6c9ca25a68b67d8b6948ece9ed3a414f2977c4f72175ce0fc63ce58545acc721f09d73
-  data.tar.gz: b91049699af9824aeb2fa051d859f35ff0f1b4ba289b7ea143a347a5ad8a882ec5a4fb42502742b3e4d19bf295f9a1d5bf3a9e15f38a061efdcf50a1741f0bce
+  metadata.gz: 32d61cf7e0858e704fc39fe317048e3e531afcf97da70b9b3d1e4b59a078e2f5c8c65a3f72c656b61285df9e5c99d7430938403560ca6e8e7aa5d920dada274e
+  data.tar.gz: c5c1488b1cec55810ffccf8116d70e8312ccb7d93875c1047ab7608595eb81fda9601f44ef308b3e1f35319d683b6ceda423284c9cda76c6f44882a7341e681a

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']
+        ruby: ['3.0', '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']
+        ruby: ['3.0', '3.1', '3.2', 'head']
 
     name: >-
       ${{matrix.os}}, ${{matrix.ruby}}

data/.yardopts

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

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 1.1 2023-06-08
+
+- Add advanced I/O doc page
+- Add `Fiber#receive_loop` API
+
+## 1.0.2 2023-05-28
+
+- Remove liburing man files from gemspec (#103)
+
 ## 1.0.1 2023-05-14
 
 - Add cheat-sheet

data/README.md

@@ -77,6 +77,7 @@ $ gem install polyphony
 
 - [Overview](docs/overview.md)
 - [Tutorial](docs/tutorial.md)
+- [Advanced I/O with Polyphony](docs/advanced-io.md)
 - [Cheat-Sheet](docs/cheat-sheet.md)
 - [FAQ](docs/faq.md)
 

data/TODO.md

@@ -1,3 +1,6 @@
+- Look at RPC benchmark more closely: is there a way to reduce the overhead of
+  the `backend_base_switch_fiber` function?
+
 - io_uring backend:
   - if `io_uring_get_sqe` returns null, call `io_uring_submit`, (snooze fiber)?
     and try again
@@ -11,24 +14,14 @@
 - Add support for IPv6:
   https://www.reddit.com/r/ruby/comments/lyen23/understanding_ipv6_and_why_its_important_to_you/
 
-- Check why `throttled_loop` inside of `move_on_after` fails to stop
-
 - Override stock `::SizedQueue` impl with Queue with capacity
 
-- Add support for `break` and `StopIteration` in all loops (with tests)
-
 - More tight loops
   - `IO#gets_loop`, `Socket#gets_loop`, `OpenSSL::Socket#gets_loop` (medium effort)
-  - `Fiber#receive_loop` (very little effort, should be implemented in C)
 
 - Add support for `close` to io_uring backend
 
-## Roadmap for Polyphony 1.0
-
-- Add test that mimics the original design for Monocrono:
-  - 256 fibers each waiting for a message
-  - When message received do some blocking work using a `ThreadPool`
-  - Send messages, collect responses, check for correctness
+## Roadmap for Polyphony 1.1
 
 - io_uring
   - Use playground.c to find out why we when submitting and waiting for
@@ -113,7 +106,7 @@
 
 - Allow locking the scheduler on to one fiber
   - Add instance var `@fiber_lock`
-  - API is `Thread#fiber_lock` which sets the fiber_lock instance varwhile
+  - API is `Thread#fiber_lock` which sets the fiber_lock instance var while
     running the block:
 
     ```ruby
@@ -123,6 +116,7 @@
       end
     end
     ```
+
   - When `@fiber_lock` is set, it is considered as the only one in the run
     queue:
 

data/docs/advanced-io.md

@@ -0,0 +1,224 @@
+# @title 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
+descriptors without copying data between kernel-space and user-space. This is
+not only useful for copying data between two files, but also for implementing
+things such as web servers, where you might need to serve files of an arbitrary
+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.
+
+Here's how we do splicing using Polyphony:
+
+```ruby
+def send_file_using_splice(src, dest)
+  # create a pipe. Polyphony::Pipe encapsulates a kernel pipe in a single
+  # IO-like object, but we can also use the stock IO.pipe method call that
+  # returns two separate pipe fds.
+  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
+
+    # splices data from the pipe to the dest
+    IO.splice(pipe, dest, bytes_spliced)
+  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?
+
+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:
+
+```ruby
+IO.splice(src, pipe, -2**14)
+```
+
+Secondly, we can perform the two splice operations concurrently, by spinning up
+a separate fiber that performs one of the splice operations, which gives us the
+following:
+
+```ruby
+def send_file_using_splice(src, dest)
+  pipe = Polyphony::Pipe.new
+  spin do
+    IO.splice(src, pipe, -2**14)
+    # We need to close the pipe in order to signal EOF for the 2nd splice call.
+    pipe.close
+  end
+  IO.splice(pipe, dest, -2**14)
+end
+```
+
+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
+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
+destination concurrently, and we got back-pressure propagation for free. Can we
+do any better than that?
+
+Actually, we can! Polyphony also provides an API that does all of the above in a
+single method call:
+
+```ruby
+def send_file_using_splice(src, dest)
+  IO.double_splice(src, dest)
+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.
+
+## 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:
+
+```ruby
+def serve_compressed_file(socket, file)
+  # we leave aside sending the HTTP headers and dealing with transfer encoding
+  compressed = Zlib.gzip(file.read)
+  socket << compressed
+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
+more pressure on the Ruby GC. How can we improve this?
+
+One way would be to utilise Zlib's `GzipWriter` class:
+
+```ruby
+def serve_compressed_file(socket, file)
+  # we leave aside sending the HTTP headers and dealing with transfer encoding
+  compressor = Zlib::GzipWriter.new(socket)
+  while (data = file.read(2**14))
+    compressor << data
+  end
+end
+```
+
+In the above code, we instantiate a `Zlib::GzipWriter`, which we then feed with
+data from the file, with the compressor object writing the compressed data to
+the socket. Notice how we still need to read the file contents into a Ruby
+string and then pass it to the compressor. Could we avoid this? With Polyphony
+the answer is yes we can!
+
+Polyphony provides a number of APIs for compressing and decompressing data on
+the fly between two file descriptors (i.e. `IO` instances), namely: `IO.gzip`,
+`IO.gunzip`, `IO.deflate` and `IO.inflate`. Let's see how this can be used to
+serve gzipped data to an HTTP client:
+
+```ruby
+def serve_compressed_file(socket, file)
+  IO.gzip(file, socket) # and that's it!
+end
+```
+
+Using the `IO.gzip` API provided by Polyphony, we completely avoid instantiating
+Ruby strings into which data is read, and in fact we avoid allocating any
+buffers on the heap (apart from what `zlib` might be doing). *And* we get to
+move data *and compress it* between the given file and the socket using a single
+method call!
+
+## Feeding data from a file descriptor to a parser
+
+Some times we want to process data from a given file or socket by passing
+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:
+
+```ruby
+def with_message_pack_data_from_io(io, &block)
+  unpacker = MessagePack::Unpacker.new
+  while (data = io.read(2**14))
+    unpacker.feed_each(data, &block)
+  end
+end
+
+# Which we can use as follows:
+with_message_pack_data_from_io(socket) do |o|
+  puts "got: #{o.inspect}"
+end
+```
+
+Polyphony provides some APIs that help us write less code, and even optimize the
+performance of our code. Let's look at the `IO#read_loop` (or `IO#recv_loop` for
+sockets) API:
+
+```ruby
+def with_message_pack_data_from_io(io, &block)
+  unpacker = MessagePack::Unpacker.new
+  io.read_loop do |data|
+    unpacker.feed_each(data, &block)
+  end
+end
+```
+
+In the above code, we replaced our `while` loop with a call to `IO#read_loop`,
+which yields read data to the block given to it. In the block, we pass the data
+to the MessagePack unpacker. While this does not like much different than the
+previous implementation, the `IO#read_loop` API implements a tight loop at the
+C-extension level, that provides slightly better performance.
+
+But Polyphony goes even further than that and provides a `IO#feed_loop` API that
+lets us feed read data to a given parser or processor object. Here's how we can
+use it:
+
+```ruby
+def with_message_pack_data_from_io(io, &block)
+  unpacker = MessagePack::Unpacker.new
+  io.feed_loop(unpacker, :feed_each, &block)
+end
+```
+
+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.
+
+## 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)
+included in Polyphony.

data/docs/cheat-sheet.md

@@ -71,7 +71,7 @@ def calculate_some_stuff(n)
     acc += big_calc(acc, i)
     snooze if (i % 1000) == 0
   end
-end 
+end
 ```
 
 ### Suspend fiber
@@ -191,7 +191,7 @@ dest2.tee_from(source, 8192)
 dest1.splice_from(source, 8192)
 # or:
 IO.tee(src, dest2)
-IO.splice(src, dest2)
+IO.splice(src, dest1)
 ```
 
 ### Splice data between two arbitrary file descriptors, without creating a pipe

data/docs/readme.md

@@ -79,6 +79,7 @@ $ gem install polyphony
 
 - {file:/docs/overview.md           Overview}
 - {file:/docs/tutorial.md           Tutorial}
+- {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/debug.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'debug'
+require 'polyphony'
+
+puts 'starting'
+binding.break
+sleep 1
+puts 'hello'
+sleep 1
+puts 'bye'

data/examples/core/rpc_benchmark.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony'
+require "benchmark/ips"
+
+class Fiber
+  def call(*a, **b)
+    self << [Fiber.current, a, b]
+    Fiber.current.receive
+  end
+
+  def respond
+    peer, a, b = receive
+    result = yield(*a, **b)
+    (peer << result) rescue nil
+  rescue
+    peer.raise(result)
+  end
+
+  def respond_loop(&b)
+    while true
+      respond(&b)
+    end
+  end
+end
+
+$server = spin do
+  Fiber.current.respond_loop do |x, y|
+    x * y
+  end
+end
+
+$server_optimized = spin do
+  while true
+    fiber, x, y = receive
+    fiber << (x * y)
+  end
+end
+
+peer = Fiber.current
+$server_single = spin do
+  while true
+    x = receive
+    peer << x * 4
+  end
+end
+
+$server_schedule = spin do
+  while true
+    x = suspend
+    peer.schedule x * 4
+  end
+end
+
+$server_raw = Fiber.new do |x|
+  while true
+    x = peer.transfer x * 4
+  end
+end
+
+def calc(x, y)
+  x * y
+end
+
+def bm_raw
+  calc(3, 4)
+end
+
+def bm_send
+  send(:calc, 3, 4)
+end
+
+def bm_fiber
+  $server.call(3, 4)
+end
+
+def bm_fiber_optimized
+  $server_optimized << [Fiber.current, 3, 4]
+  receive
+end
+
+def bm_fiber_single
+  $server_single << 3
+  receive
+end
+
+def bm_fiber_schedule
+  $server_schedule.schedule(3)
+  suspend
+end
+
+def bm_fiber_raw
+  $server_raw.transfer 3
+end
+
+# p bm_raw
+# p bm_send
+# p bm_fiber
+# p bm_fiber_optimized
+# p bm_fiber_single
+p bm_fiber_raw
+p bm_fiber_schedule
+
+def warmup_jit
+  10000.times do
+    bm_raw
+    bm_send
+    bm_fiber
+    bm_fiber_optimized
+    bm_fiber_single
+    bm_fiber_raw
+    bm_fiber_schedule
+  end
+end
+
+puts "warming up JIT..."
+
+# 3.times do
+#   warmup_jit
+#   sleep 1
+# end
+
+Benchmark.ips do |x|
+  # x.report("raw") { bm_raw }
+  # x.report("send") { bm_send }
+  # x.report("fiber") { bm_fiber }
+  # x.report("fiber_optimized") { bm_fiber_optimized }
+  # x.report("fiber_single") { bm_fiber_single }
+  x.report("fiber_raw") { bm_fiber_raw }
+  x.report("fiber_schedule") { bm_fiber_schedule }
+  x.compare!
+end
+
+# p call_result: server.call(3, 4)
+

data/examples/core/stream_mockup.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony'
+
+class Stream
+  def initialize(io)
+    @io = io
+    @buffer = +''
+    @length = 0
+    @pos = 0
+  end
+
+  def getbyte
+    if @pos == @length
+      return nil if !fill_buffer
+    end
+    byte = @buffer[@pos].getbyte(0)
+    @pos += 1
+    byte
+  end
+
+  def getc
+    if @pos == @length
+      return nil if !fill_buffer
+    end
+    char = @buffer[@pos]
+    @pos += 1
+    char
+  end
+
+  def ungetc(c)
+    @buffer.insert(@pos, c)
+    @length += 1
+    c
+  end
+
+  def gets
+  end
+
+  def read
+  end
+
+  def readpartial
+  end
+
+  private
+
+  def fill_buffer
+    Polyphony.backend_read(@io, @buffer, 8192, false, -1)
+    @length = @buffer.size
+  end
+end
+
+i, o = IO.pipe
+s = Stream.new(i)
+
+f = spin do
+  loop do
+    b = s.getbyte
+    p getbyte: b
+    s.ungetc(b.to_s) if rand > 0.5
+  end
+end
+
+o << 'hello'
+sleep 0.1
+

data/examples/core/throttled_loop_inside_move_on_after.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony'
+
+i = 0
+value = move_on_after(1, with_value: 42) do
+  throttled_loop(20) do
+    p (i += 1)
+  end
+end
+
+p value: value

data/ext/polyphony/backend_common.c

@@ -389,12 +389,12 @@ inline void set_fd_blocking_mode(int fd, int blocking) {
 #endif
 }
 
-inline void io_verify_blocking_mode(rb_io_t *fptr, VALUE io, VALUE blocking) {
+inline void io_verify_blocking_mode(VALUE io, int fd, VALUE blocking) {
   VALUE blocking_mode = rb_ivar_get(io, ID_ivar_blocking_mode);
   if (blocking == blocking_mode) return;
 
   rb_ivar_set(io, ID_ivar_blocking_mode, blocking);
-  set_fd_blocking_mode(fptr->fd, blocking == Qtrue);
+  set_fd_blocking_mode(fd, blocking == Qtrue);
 }
 
 inline void backend_run_idle_tasks(struct Backend_base *base) {
@@ -455,9 +455,7 @@ VALUE Backend_stats(VALUE self) {
 }
 
 VALUE Backend_verify_blocking_mode(VALUE self, VALUE io, VALUE blocking) {
-  rb_io_t *fptr;
-  GetOpenFile(io, fptr);
-  io_verify_blocking_mode(fptr, io, blocking);
+  io_verify_blocking_mode(io, rb_io_descriptor(io), blocking);
   return self;
 }
 

data/ext/polyphony/backend_common.h

@@ -10,6 +10,15 @@
 #include "ruby/io.h"
 #include "runqueue.h"
 
+#ifndef HAVE_RB_IO_DESCRIPTOR
+static int rb_io_descriptor_fallback(VALUE io) {
+  rb_io_t *fptr;
+  GetOpenFile(io, fptr);
+  return fptr->fd;
+}
+#define rb_io_descriptor rb_io_descriptor_fallback
+#endif
+
 struct backend_stats {
   unsigned int runqueue_size;
   unsigned int runqueue_length;
@@ -145,7 +154,7 @@ VALUE Backend_stats(VALUE self);
 VALUE Backend_verify_blocking_mode(VALUE self, VALUE io, VALUE blocking);
 void backend_run_idle_tasks(struct Backend_base *base);
 void set_fd_blocking_mode(int fd, int blocking);
-void io_verify_blocking_mode(rb_io_t *fptr, VALUE io, VALUE blocking);
+void io_verify_blocking_mode(VALUE io, int fd, VALUE blocking);
 void backend_setup_stats_symbols();
 int backend_getaddrinfo(VALUE host, VALUE port, struct sockaddr **ai_addr);
 VALUE name_to_addrinfo(void *name, socklen_t len);

data/ext/polyphony/backend_io_uring.c

@@ -28,9 +28,9 @@ VALUE SYM_write;
 VALUE eArgumentError;
 
 #ifdef POLYPHONY_UNSET_NONBLOCK
-#define io_unset_nonblock(fptr, io) io_verify_blocking_mode(fptr, io, Qtrue)
+#define io_unset_nonblock(io, fd) io_verify_blocking_mode(io, fd, Qtrue)
 #else
-#define io_unset_nonblock(fptr, io)
+#define io_unset_nonblock(io, fd)
 #endif
 
 typedef struct Backend_t {
@@ -389,10 +389,10 @@ static inline int fd_from_io(VALUE io, rb_io_t **fptr, int write_mode, int recti
     if (underlying_io != Qnil) io = underlying_io;
 
     GetOpenFile(io, *fptr);
-    io_unset_nonblock(*fptr, io);
+    int fd = rb_io_descriptor(io);
+    io_unset_nonblock(io, fd);
     if (rectify_file_pos) rectify_io_file_pos(*fptr);
-
-    return (*fptr)->fd;
+    return fd;
   }
 }
 
@@ -1376,7 +1376,7 @@ VALUE Backend_wait_io(VALUE self, VALUE io, VALUE write) {
 
 //   if (fd < 0) return Qnil;
 
-//   io_unset_nonblock(fptr, io);
+//   io_unset_nonblock(io, fd);
 
 //   ctx = context_store_acquire(&backend->store, OP_CLOSE);
 //   sqe = io_uring_backend_get_sqe(backend);