uringmachine 0.29.1 → 0.30.0

data/grant-2025/final-report.md

@@ -0,0 +1,267 @@
+# Final Report for Ruby Association Grant Program 2025
+
+## Project Summary
+
+Io_uring is a relatively new Linux API, permitting the asynchronous invocation
+of Linux system calls. UringMachine is a gem that brings low-level access to the
+io_uring interface to Ruby programs, and permits not only asynchronous I/O on
+files and sockets, but also timeouts, futex wait/wake, statx and other system
+calls, for use with fiber-based concurrency. This project aims to enhance
+UringMachine to include a fiber scheduler implementation for usage with the
+standard Ruby I/O classes, to have builtin support for SSL, to support more
+io_uring ops such as writev, splice, fsync, mkdir, fadvise, etc.
+
+I'd like to express my deep gratitude to Samuel Williams for his help and
+guidance throughout this project.
+
+## About UringMachine
+
+UringMachine provides an API that closely follows the shape of various Linux
+system calls for I/O operations, such as `open`, `read`, `accept`, `setsockopt`
+etc. Behind the scenes, UringMachine uses io_uring to submit I/O operations and
+automatically switch between fibers when waiting for those operations to
+complete. Here's a simple example of an echo server using UringMachine:
+
+```ruby
+require 'uringmachine'
+
+machine = UM.new
+server_fd = machine.socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
+machine.bind(server_fd, '0.0.0.0', 1234)
+machine.listen(server_fd, UM::SOMAXCONN)
+
+def handle_connection(machine, fd)
+  buf = +''
+  while true
+    res = machine.recv(fd, buf, 8192, 0)
+    break if res == 0
+
+    machine.send(fd, buf, res, 0)
+  end
+ensure
+  machine.close(fd)
+end
+
+while true
+  fd = machine.accept(server_fd)
+  machine.spin(fd) {
+    handle_connection(machine, it)
+  }
+end
+```
+
+UringMachine also provides some higher-level methods and abstractions that make
+use of more advanced io_uring features such as [multishot
+operations](https://man.archlinux.org/man/io_uring_multishot.7.en) (e.g.
+`UM#accept_each`) and [provided buffer
+rings](https://man.archlinux.org/man/io_uring_provided_buffers.7.en) (the
+`UM::Stream` class). This not only results in more concise code, but also has
+[performance](#benchmarking) benefits. In addition, UringMachine provides some
+convenience methods, such as `tcp_listen` which returns a TCP socket fd bound to
+the given address and ready for accepting incoming connections.
+
+Here's the same echo server program but using UringMachine's more advanced
+features:
+
+```ruby
+require 'uringmachine'
+
+machine = UM.new
+# Combined socket, bind, listen
+server_fd = machine.tcp_listen('0.0.0.0', 1234)
+
+def handle_connection(machine, fd)
+  stream = machine.stream(fd)
+  stream.each { |buf| machine.send(fd, buf, buf.size, 0) }
+ensure
+  machine.close(fd)
+end
+
+machine.accept_each(server_fd) do |fd|
+  machine.spin(fd) {
+    handle_connection(machine, it)
+  }
+end
+```
+
+UringMachine also includes a fiber scheduler implementation that effectively
+provides an alternative backend for performing I/O operations while still using
+the same familiar API of `IO`, `Socket` and related standard classes:
+
+```ruby
+machine = UM.new
+scheduler = UM::FiberScheduler.new(machine)
+Fiber.set_scheduler(scheduler)
+
+Fiber.schedule {
+  puts('Hello from UringMachine!')
+}
+
+# await all pending fibers
+scheduler.join
+```
+
+## The Work Done
+
+### Improvements to the Ruby `Fiber::Scheduler` interface
+
+- [PR](https://github.com/ruby/ruby/pull/15213) to expose
+  `rb_process_status_new` internal Ruby C API
+  (https://bugs.ruby-lang.org/issues/21704). This is needed in order to allow
+  FiberScheduler implementations to instantiate `Process::Status` objects in the
+  `#process_wait` hook. This PR is still not merged.
+
+- [PR](https://github.com/ruby/ruby/pull/15385) to cleanup FiberScheduler and
+  fiber state in a forked process (https://bugs.ruby-lang.org/issues/21717).
+  This was merged into Ruby 4.0.
+
+- [PR](https://github.com/ruby/ruby/pull/15609) to invoke FiberScheduler
+  `io_write` hook on IO flush (https://bugs.ruby-lang.org/issues/21789). This
+  was merged into Ruby 4.0.
+
+- Found an issue while implementing the `#io_pwrite` hook, which resulted in a
+  [PR](https://github.com/ruby/ruby/pull/15428) submitted by Samuel Williams,
+  and merged into Ruby 4.0.
+
+- Worked with Samuel Williams on how to implement the `#io_close` hook, which
+  resulted in a [PR](https://github.com/ruby/ruby/pull/15434) submitted by
+  Samuel and merged into Ruby 4.0.
+
+- [PR](https://github.com/ruby/ruby/pull/15865) to add socket I/O hooks to the
+  FiberScheduler interface (https://bugs.ruby-lang.org/issues/21837). This PR is
+  currently in draft phase, waiting input from Samuel Williams.
+
+### UringMachine `Fiber::Scheduler` Implementation
+
+- I developed a [full
+  implementation](https://github.com/digital-fabric/uringmachine/blob/main/lib/uringmachine/fiber_scheduler.rb)
+  of the `Fiber::Scheduler` interface using UringMachine, with methods for all
+  hooks:
+
+  - `#scheduler_close`
+  - `#fiber`, `#yield`
+  - `#blocking_operation_wait`, `#block`, `#unblock`, `#fiber_interrupt`
+  - `#kernel_sleep`, `#timeout_after`
+  - `#io_read`, `#io_write`, `#io_pread`, `#io_pwrite`, `#io_close`
+  - `#io_wait`, `#io_select`
+  - `#process_wait` (relies on the `rb_process_status_new` PR)
+  - `#address_resolve`
+
+- Wrote [extensive
+  tests](https://github.com/digital-fabric/uringmachine/blob/main/test/test_fiber_scheduler.rb)
+  for the UringMachine fiber scheduler.
+
+### SSL Integration
+
+- I've added UringMachine method that installs a [custom OpenSSL
+  BIO](https://github.com/digital-fabric/uringmachine/blob/main/ext/um/um_ssl.c)
+  on the given SSLSocket, as well as read/write methods that provide higher
+  throughput on SSL connections:
+
+  ```ruby
+  ssl = OpenSSL::SSL::SSLSocket.new(sock, OpenSSL::SSL::SSLContext.new)
+  machine.ssl_set_bio(ssl)
+  msg = 'foo'
+  ssl.write(msg) # Performs IO using the UringMachine BIO
+
+  # Or: bypass the OpenSSL gem, directly invoking SSL_write and using the
+  # UringMachine BIO
+  machine.ssl_write(ssl, msg, msg.bytesize)
+  ```
+
+- I've also submitted a [PR to the OpenSSL
+  gem](https://github.com/ruby/openssl/pull/1000) that adds support for using a
+  custom BIO method for reading and writing on SSL connections.
+
+### Buffered Reads Using io_uring Provided Buffers
+
+- I developed the `Stream` API that uses io_uring [provided
+  buffers](https://man.archlinux.org/man/io_uring_provided_buffers.7.en) to
+  allow buffered reads (e.g. similar behavior to `IO#gets`, `IO#readpartial`)
+  while minimizing copying of data.
+- The [buffer
+  pool](https://github.com/digital-fabric/uringmachine/blob/main/ext/um/um_buffer_pool.c):
+  UringMachine allocates and provides buffers for kernel usage in multishot
+  read/recv operations. An adaptive algorithm ensures that the kernel always has
+  enough buffer space for reading data. When a buffer is no longer used by the
+  kernel or the stream, it is recycled and eventually provided back to the
+  kernel.
+- Streams are
+  [implemented](https://github.com/digital-fabric/uringmachine/blob/main/ext/um/um_stream.c)
+  as a linked list of buffer segments, directly referencing the buffers shared
+  with the kernel and referenced in CQEs.
+- Stream read methods suitable for both line-based protocols and binary
+  protocols.
+- An `:ssl` stream mode allows reading from a `SSLSocket` instead of from an fd,
+  using the custom SSL BIO discussed above.
+
+### Other Improvements to UringMachine
+
+- Improved various internal aspects of the C-extension: performance and
+  correctness of mutex and queue implementations.
+
+- Added support for accepting instances of `IO::Buffer` as buffer for the
+  various I/O operations, in order to facilitate the `Fiber::Scheduler`
+  implementation.
+
+- Added various methods for working with processes:
+
+  - `UringMachine#waitid`
+  - `UringMachine.pidfd_open`
+  - `UringMachine.pidfd_send_signal`
+
+- Added detailed internal metrics.
+
+- Added support for vectorized write/send using io_uring: `UringMachine#writev`
+  and `UringMachine#sendv`.
+
+- Added support for `SQPOLL` mode - this io_uring mode lets us avoid entering
+  the kernel when submitting I/O operations as the kernel is busy polling the SQ
+  ring.
+
+- Added support for sidecar mode: an auxiliary thread is used to enter the
+  kernel and wait for CQE's (I/O operation completion entries), letting the Ruby
+  thread avoid entering the kernel in order to wait for CQEs.
+
+- Added support for watching file system events using the `inotify` interface.
+- Methods for low-level work with `inotify`:
+
+  ```ruby
+  fd = UM.inotify_init
+  wd = UM.inotify_add_watch(fd, '/tmp', UM::IN_CLOSE_WRITE)
+  IO.write('/tmp/foo.txt', 'foofoo')
+  events = machine.inotify_get_events(fd)
+  #=> { wd: wd, mask: UM::IN_CLOSE_WRITE, name: 'foo.txt' }
+  ```
+
+- A higher-level API for watching directories:
+
+  ```ruby
+  mask = UM::IN_CREATE | UM::IN_DELETE | UM::IN_CLOSE_WRITE
+  machine.file_watch(FileUtils.pwd, mask) { handle_fs_event(it) }
+  ```
+
+- Added more low-level methods for performing I/O operations supported by
+  io_uring: `splice`, `tee`, `fsync`.
+
+### Benchmarking
+
+- I did extensive benchmarking comparing different solutions for performing
+  concurrent I/O in Ruby:
+
+  - Using normal Ruby threads
+  - Using Samuel's [Async](https://github.com/socketry/async/) gem which
+    implements a `Fiber::Scheduler`
+  - Using the UringMachine `Fiber::Scheduler`
+  - Using the UringMachine low-level API
+
+- The benchmarks simulate different kinds of workloads:
+
+  - Writing and reading from pipes
+  - Writing and reading from sockets
+  - Doing CPU-bound work synchronized by mutex
+  - Doing I/O-bound work synchronized by mutex
+  - Pushing and pulling items from queues
+  - Running queries on a PostgreSQL database
+
+- The results are here: https://github.com/digital-fabric/uringmachine/blob/main/benchmark/README.md

data/lib/uringmachine/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class UringMachine
-  VERSION = '0.29.1'
+  VERSION = '0.30.0'
 end

data/lib/uringmachine.rb

@@ -194,6 +194,56 @@ class UringMachine
     close_async(fd)
   end
 
+  # call-seq:
+  #   machine.stream(fd, mode = nil) -> stream
+  #   machine.stream(fd, mode = nil) { |stream| }
+  #
+  # Creates a stream for reading from the given target fd or other object. The
+  # mode indicates the type of target and how it is read from:
+  #
+  # - :bp_read - read from the given fd using the buffer pool (default mode)
+  # - :bp_recv - receive from the given socket fd using the buffer pool
+  # - :ssl - read from the given SSL connection
+  #
+  # If a block is given, the block will be called with the stream object and the
+  # method will return the block's return value.
+  #
+  # @param target [Integer, OpenSSL::SSL::SSLSocket] fd or ssl connection
+  # @param mode [Symbol, nil] stream mode
+  # @return [UringMachine::Stream] stream object
+  def stream(target, mode = nil)
+    stream = UM::Stream.new(self, target, mode)
+    return stream if !block_given?
+
+    res = yield(stream)
+    stream.clear
+    res
+  end
+
+  # Creates, binds and sets up a TCP socket for listening on the given host and
+  # port.
+  #
+  # @param host [String] host IP address
+  # @param port [Integer] TCP port
+  # @return [Integer] socket fd
+  def tcp_listen(host, port)
+    fd = socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
+    bind(fd, host, port)
+    listen(fd, UM::SOMAXCONN)
+    fd
+  end
+
+  # Creates and connects a TCP socket to the given host and port.
+  #
+  # @param host [String] host IP address
+  # @param port [Integer] TCP port
+  # @return [Integer] socket fd
+  def tcp_connect(host, port)
+    fd = socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
+    connect(fd, host, port)
+    fd
+  end
+
   private
 
   # @param block [Proc]

data/test/test_ssl.rb

@@ -82,4 +82,31 @@ class SSLTest < UMBaseTest
     sock1&.close rescue nil
     sock2&.close rescue nil
   end
+
+  def test_ssl_write_0
+    sock1, sock2 = UNIXSocket.pair
+
+    s1 = OpenSSL::SSL::SSLSocket.new(sock1, @server_ctx)
+    s1.sync_close = true
+    s2 = OpenSSL::SSL::SSLSocket.new(sock2, OpenSSL::SSL::SSLContext.new)
+    s2.sync_close = true
+
+    @machine.ssl_set_bio(s2)
+    assert_equal true, s2.instance_variable_get(:@__um_bio__)
+
+    t = Thread.new { s1.accept rescue nil }
+
+    assert_equal 0, @machine.metrics[:total_ops]
+    s2.connect
+    refute_equal 0, @machine.metrics[:total_ops]
+
+    assert_equal 6, @machine.ssl_write(s1, 'foobar', 0)
+    buf = +''
+    assert_equal 6, @machine.ssl_read(s2, buf, 6)
+    assert_equal 'foobar', buf
+  ensure
+    t&.join(0.1)
+    sock1&.close rescue nil
+    sock2&.close rescue nil
+  end
 end

data/test/test_stream.rb

@@ -221,6 +221,16 @@ class StreamTest < StreamBaseTest
     assert_nil stream.get_string(-3)
   end
 
+  def test_stream_skip
+    machine.write(@wfd, "foobarbaz")
+
+    stream.skip(2)
+    assert_equal 'obar', stream.get_string(4)
+
+    stream.skip(1)
+    assert_equal 'az', stream.get_string(0)
+  end
+
   def test_stream_big_data
     data = SecureRandom.random_bytes(300_000)
     fiber = machine.spin {
@@ -241,6 +251,39 @@ class StreamTest < StreamBaseTest
     assert_equal 9, received.size
     assert_equal data, received.join
   end
+
+  def test_stream_each
+    bufs = []
+    f = machine.spin do
+      bufs << :ready
+      stream.each {
+        assert_kind_of IO::Buffer, it
+        bufs << it.get_string
+      }
+      bufs << :done
+    rescue => e
+      p e
+      p e.backtrace
+    end
+
+    machine.snooze
+    assert_equal [:ready], bufs
+
+    machine.write(@wfd, 'foo')
+    machine.snooze
+    assert_equal [:ready, 'foo'], bufs
+
+    machine.write(@wfd, 'barb')
+    machine.snooze
+    assert_equal [:ready, 'foo', 'barb'], bufs
+
+    machine.close(@wfd)
+    machine.snooze
+    assert_equal [:ready, 'foo', 'barb', :done], bufs
+  ensure
+    machine.terminate(f)
+    machine.join(f)
+  end
 end
 
 class StreamRespTest < StreamBaseTest
@@ -593,3 +636,36 @@ class StreamModeTest < UMBaseTest
     sock2&.close rescue nil
   end
 end
+
+class StreamByteCountsTest < StreamBaseTest
+  def test_stream_byte_counts
+    machine.write(@wfd, "foobar")
+
+    assert_equal 0, stream.consumed
+    assert_equal 0, stream.pending
+
+    buf = stream.get_string(2)
+    assert_equal 'fo', buf
+    assert_equal 2, stream.consumed
+    assert_equal 4, stream.pending
+
+    buf = stream.get_string(3)
+    assert_equal 'oba', buf
+    assert_equal 5, stream.consumed
+    assert_equal 1, stream.pending
+
+    machine.write(@wfd, "abc\ndef")
+    machine.snooze
+    assert_equal 5, stream.consumed
+    assert_equal 1, stream.pending
+
+    buf = stream.get_line(0)
+    assert_equal 'rabc', buf
+    assert_equal 10, stream.consumed
+    assert_equal 3, stream.pending
+
+    stream.clear
+    assert_equal 10, stream.consumed
+    assert_equal 0, stream.pending
+  end
+end

data/test/test_um.rb

@@ -3505,3 +3505,212 @@ class SetChildSubreaperTest < Minitest::Test
     assert_equal grand_child_pid, res
   end
 end
+
+class StreamMethodTest < UMBaseTest
+  def setup
+    super
+    @rfd, @wfd = UM.pipe
+  end
+
+  def teardown
+    @stream = nil
+    machine.close(@rfd) rescue nil
+    machine.close(@wfd) rescue nil
+    super
+  end
+
+  def test_stream_method
+    machine.write(@wfd, "foobar")
+    machine.close(@wfd)
+
+    stream = machine.stream(@rfd)
+    assert_kind_of UM::Stream, stream
+
+    buf = stream.get_string(3)
+    assert_equal 'foo', buf
+
+    buf = stream.get_string(-6)
+    assert_equal 'bar', buf
+    assert stream.eof?
+
+    stream.clear
+  end
+
+  def test_stream_method_with_block
+    machine.write(@wfd, "foobar")
+    machine.close(@wfd)
+
+    bufs = []
+    stream_obj = nil
+    res = machine.stream(@rfd) do |s|
+      stream_obj = s
+
+      bufs << s.get_string(3)
+      bufs << s.get_string(-6)
+
+      :foo
+    end
+
+    assert_kind_of UM::Stream, stream_obj
+    assert stream_obj.eof?
+    assert_equal ['foo', 'bar'], bufs
+    assert_equal :foo, res
+  end
+end
+
+class TCPHelperMethodsTest < UMBaseTest
+  def setup
+    super
+    @port = assign_port
+  end
+
+  def test_tcp_listen
+    server_fd = machine.tcp_listen('0.0.0.0', @port)
+    assert_kind_of Integer, server_fd
+
+    fd_c = machine.socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
+    machine.connect(fd_c, '127.0.0.1', @port)
+
+    fd_s = machine.accept(server_fd)
+    assert_equal 3, machine.send(fd_s, 'foo', 3, 0)
+
+    buf = +''
+    machine.recv(fd_c, buf, 8192, 0)
+    assert_equal 'foo', buf
+  ensure
+    machine.close(fd_s) rescue nil
+    machine.close(fd_c) rescue nil
+    machine.close(server_fd) rescue nil
+  end
+
+  def test_tcp_listen_invalid_args
+    assert_raises(TypeError) { machine.tcp_listen('0.0.0.0', :foo) }
+    assert_raises(TypeError) { machine.tcp_listen(1234, 5678) }
+  end
+
+  def test_tcp_connect
+    server_fd = machine.tcp_listen('0.0.0.0', @port)
+    assert_kind_of Integer, server_fd
+
+    fd_c = machine.tcp_connect('127.0.0.1', @port)
+    assert_kind_of Integer, fd_c
+
+    fd_s = machine.accept(server_fd)
+    assert_equal 3, machine.send(fd_s, 'foo', 3, 0)
+
+    buf = +''
+    machine.recv(fd_c, buf, 8192, 0)
+    assert_equal 'foo', buf
+  ensure
+    machine.close(fd_s) rescue nil
+    machine.close(fd_c) rescue nil
+    machine.close(server_fd) rescue nil
+  end
+
+  def test_tcp_connect_invalid_args
+    server_fd = machine.tcp_listen('0.0.0.0', @port)
+
+    assert_raises(Errno::ECONNREFUSED) {
+      machine.tcp_connect('127.0.0.1', @port + 1)
+    }
+    assert_raises(TypeError) { machine.tcp_connect('127.0.0.1', :foo) }
+    assert_raises(TypeError) { machine.tcp_connect(1234, 5678) }
+  ensure
+    machine.close(server_fd)
+  end
+end
+
+class SpliceTest < UMBaseTest
+  def test_splice
+    i1, o1 = UM.pipe
+    i2, o2 = UM.pipe
+    len = nil
+
+    f = machine.spin do
+      len = machine.splice(i1, o2, 1000)
+    ensure
+      machine.close(o2)
+    end
+
+    machine.write(o1, 'foobar')
+    buf = +''
+    machine.read(i2, buf, 1000)
+
+    assert_equal 'foobar', buf
+    assert_equal 6, len
+  ensure
+    machine.terminate(f)
+    machine.join(f)
+    [i1, o1, i2, o2].each { machine.close(it) rescue nil }
+  end
+
+  def test_splice_bad_args
+    fn = "/tmp/um_#{SecureRandom.hex}"
+    IO.write(fn, 'foo')
+    f1 = machine.open(fn, UM::O_RDWR)
+    f2 = machine.open(fn, UM::O_RDWR)
+    assert_raises(Errno::EINVAL) { machine.splice(f1, f2, 1000) }
+
+    i1, o1 = UM.pipe
+    i2, o2 = UM.pipe
+    machine.write(o1, 'foo')
+
+    assert_raises(Errno::EBADF) { machine.splice(i1, o2 + 1, 1000) }
+  ensure
+    [f1, f2, i1, o1, i2, o2].each { machine.close(it) rescue nil }
+  end
+end
+
+class TeeTest < UMBaseTest
+  def test_tee
+    i_src, o_src = UM.pipe
+    i_dest1, o_dest1 = UM.pipe
+    i_dest2, o_dest2 = UM.pipe
+
+    len1 = len2 = nil
+
+    f = machine.spin do
+      len1 = machine.tee(i_src, o_dest1, 1000)
+      len2 = machine.splice(i_src, o_dest2, 1000)
+    ensure
+      machine.close(o_dest1)
+      machine.close(o_dest2)
+    end
+
+    machine.write(o_src, 'foobar')
+    machine.close(o_src)
+    result1 = +''
+    machine.read(i_dest1, result1, 1000)
+    result2 = +''
+    machine.read(i_dest2, result2, 1000)
+
+    assert_equal 'foobar', result1
+    assert_equal 6, len1
+
+    assert_equal 'foobar', result2
+    assert_equal 6, len2    
+  ensure
+    machine.terminate(f)
+    machine.join(f)
+    [i_src, o_src, i_dest1, o_dest1, i_dest2, o_dest2].each {
+      machine.close(it) rescue nil
+    }
+  end
+end
+
+class FsyncTest < UMBaseTest
+  def test_fsync
+    fn = "/tmp/um_#{SecureRandom.hex}"
+    fd = machine.open(fn, UM::O_CREAT | UM::O_WRONLY)
+
+    machine.write(fd, 'foo')
+    assert_equal 0, machine.fsync(fd)
+  ensure
+    machine.close(fd)
+    FileUtils.rm(fn) rescue nil
+  end
+
+  def test_fsync_bad_args
+    assert_raises(Errno::EINVAL) { machine.fsync(1) }
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uringmachine
 version: !ruby/object:Gem::Version
-  version: 0.29.1
+  version: 0.30.0
 platform: ruby
 authors:
 - Sharon Rosner
@@ -58,10 +58,12 @@ files:
 - benchmark/README.md
 - benchmark/bm_io_pipe.rb
 - benchmark/bm_io_socketpair.rb
+- benchmark/bm_io_ssl.rb
 - benchmark/bm_mutex_cpu.rb
 - benchmark/bm_mutex_io.rb
 - benchmark/bm_pg_client.rb
 - benchmark/bm_queue.rb
+- benchmark/bm_redis_client.rb
 - benchmark/chart_all.png
 - benchmark/chart_bm_io_pipe_x.png
 - benchmark/common.rb
@@ -119,6 +121,7 @@ files:
 - ext/um/um_stream_class.c
 - ext/um/um_sync.c
 - ext/um/um_utils.c
+- grant-2025/final-report.md
 - grant-2025/interim-report.md
 - grant-2025/journal.md
 - grant-2025/tasks.md