uringmachine 0.23.1 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a53007580b3e3fc11ce53466d79afa6a68e8546966d080b73b45cea166843e12
-  data.tar.gz: f86c71ea56e72fe9d0fbbd130191b97d1e411feee7398f4bb748eda561ea4732
+  metadata.gz: 162f747c9286305e5bba72e0ab5c3d0d89c9a0ff42e1480b4c247a05dab0c2f3
+  data.tar.gz: 41ebc4a248a204f898d6d4cc954405b441c533109f08cae2806a0204bd1726aa
 SHA512:
-  metadata.gz: 8a414b66431041c2d738cf8b0a68c4a78a2ebb14ad900868e351dac35de930aa5d1fe6862d67dedb90ce19f935bd6808ff0948825362960153c6fe95a7c4fe82
-  data.tar.gz: 688cab6262c1a83267f4d08909554dbb7bb2046bd55b2b1c5eb6e7b183b5487c2d14d681e44174f347dd5afea860b7d04e3db256477433cf46d3dc60a192ee77
+  metadata.gz: d99daa2b45df0c28f9d087e19ce92678f78b76c551d47a5c55d93188a881b347a3d87f49cb93dc10686c5c89726fbc97b40e656cbcb09becbd53eeccc790e435
+  data.tar.gz: ba9f0408ac9157e82dfd34595d73d5e924a58cf8db0ee76971c5675b44c89a1ace5219e569c3a21ceff6e51439d39814f9a1f2a0314a2506bbde9169679c6707

data/.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        ruby: ['head']
+        ruby: ['4.0', 'head']
 
     name: ${{matrix.os}}, ${{matrix.ruby}}
 

data/.gitignore

@@ -37,6 +37,7 @@ build-iPhoneSimulator/
 /_yardoc/
 /doc/
 /rdoc/
+/yard/
 
 ## Environment normalization:
 /.bundle/

data/.gitmodules

@@ -2,6 +2,3 @@
 	path = vendor/liburing
 	url = https://github.com/axboe/liburing
 
-[submodule "vendor/libressl"]
-	path = vendor/libressl
-	url = https://github.com/libressl/portable

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+# 0.25.0 2026-02-10
+
+- Add Yard docs
+- Add `UM::STDIN_FILENO`, `UM::STDOUT_FILENO`, `UM::STDERR_FILENO` constants
+- Mark fibers as non-blocking in `#spin`
+- Use `Set` instead of `Hash` for holding machine's fiber list
+- Add inotify API, `#file_watch` convenience method
+- Add SSL functionality: `#ssl_set_bio`, `#ssl_read`, `#ssl_write`
+
+# 0.24.0 2026-01-30
+
+- Add `Stream.resp_encode_cmd`
+- Add sidecar mode
+- Add test mode, remove special handling of OP_SCHEDULE in um_switch, do it only
+  in test mode
+- Improve fiber scheduler error handling, add tests for I/O errors
+
 # 0.23.1 2025-12-16
 
 - Add `MSG_NOSIGNAL` to default flags for `#sendv` and `#send_bundle`

data/Gemfile

@@ -1,3 +1,14 @@
-source 'https://rubygems.org'
+source 'https://gem.coop'
 
 gemspec
+
+group :development do
+  gem 'localhost'
+  gem 'rake-compiler',  '~>1.3.0'
+  gem 'minitest',       '~>6.0.1'
+  gem 'benchmark'
+  gem 'benchmark-ips'
+  gem 'http_parser.rb', '~>0.8.0'
+  gem 'yard'
+  gem 'irb'
+end

data/README.md

@@ -1,139 +1,293 @@
-# UringMachine
-
-<a href="http://rubygems.org/gems/uringmachine">
-  <img src="https://badge.fury.io/rb/uringmachine.svg" alt="Ruby gem">
-</a>
-<a href="https://github.com/digital-fabric/uringmachine/actions?query=workflow%3ATests">
-  <img src="https://github.com/digital-fabric/uringmachine/workflows/Tests/badge.svg" alt="Tests">
-</a>
-<a href="https://github.com/digital-fabric/uringmachine/blob/master/LICENSE">
-  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
-</a>
-
-UringMachine is a fiber-based library for creating concurrent apps in Ruby on
-modern Linux machines. UringMachine provides a rich API for performing I/O using
-[io_uring](https://en.wikipedia.org/wiki/Io_uring).
+<h1 align="center">
+  <br>
+  UringMachine
+</h1>
+
+<h4 align="center">Ruby on io_uring!</h4>
+
+<p align="center">
+  <a href="http://rubygems.org/gems/uringmachine">
+    <img src="https://badge.fury.io/rb/uringmachine.svg" alt="Ruby gem">
+  </a>
+  <a href="https://github.com/digital-fabric/uringmachine/actions">
+    <img src="https://github.com/digital-fabric/uringmachine/actions/workflows/test.yml/badge.svg" alt="Tests">
+  </a>
+  <a href="https://github.com/digital-fabric/uringmachine/blob/master/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.rubydoc.info/gems/uringmachine">API reference</a>
+</p>
+
+## What is UringMachine?
+
+UringMachine is a Ruby gem for building fiber-based concurrent Ruby apps running
+on Linux and using io_uring for performing I/O. UringMachine provides a
+low-level API for performing concurrent I/O, as well as a full-featured
+[`Fiber::Scheduler`](https://docs.ruby-lang.org/en/master/Fiber/Scheduler.html)
+implementation that allows integration with the entire Ruby ecosystem.
 
 ## Features
 
-- Automatic fiber switching when performing blocking operations.
+- Automatic fiber switching when performing blocking I/O operations.
 - Automatic cancellation using of ongoing operations with Ruby exceptions.
 - General-purpose API for cancelling any operation on timeout.
-- High performance (needs to be proved).
-- (Eventually) I/O class with buffered reads and an intuitive API.
+- Excellent performance characteristics for concurrent I/O-bound applications.
+- `Fiber::Scheduler` implementation to automatically integrate with the Ruby
+  ecosystem in a transparent fashion.
 
 ## Design
 
-UringMachine is based on my experience marrying Ruby and io_uring:
-
-- [Polyphony](https://github.com/digital-fabric/polyphony) - a comprehensive gem
-  providing io_uring functionality, structured concurrency, and monkey-patching
-  for the Ruby standard library.
-- [IOU](https://github.com/digital-fabric/iou) - a low-level asynchronous API
-  for using io_uring from Ruby.
-
-### Learnings
-
-Some important learnings from those two projects, in no particular order:
-
-- Monkey-patching is not a good solution, long term. You need to deal with
-  changing APIs (Ruby is evolving quite rapidly these days!), and anyways you're
-  always going to get stuck with some standard Ruby API that's implemented as a
-  C extension and just won't play nice with whatever you're trying to do.
-- The design of the Polyphony io_uring backend was an evolution of something
-  that was originally based on libev as an event loop. In hindsight, adapting
-  the design for how io_uring worked led to code that was too complex and even
-  somewhat brittle.
-- IOU showed me that even if we embrace callbacks, the developer experience is
-  substantially inferior to what you can do with a sequential coding style. Even
-  just in terms of line count - with callbacks you end up with roughly double
-  the number of lines of code.
-- Implementing fiber switching on top of IOU was disappointing in terms of
-  performance. In order for a fiber-based solution to be performed it had to be
-  baked in - hence UringMachine.
-- Working with fibers has the very important benefit that you can keep stuff on
-  the stack, instead of passing around all kinds of references to the heap. In
-  addition, you mostly don't need to worry about marking Ruby objects used in
-  operations, since normally they'll already be on the stack as method call
-  parameters.
-- Polyphony was designed as an all-in-one solution that did everything: turning
-  stock APIs into fiber-aware ones, providing a solid structured-concurrency
-  implementation for controlling fiber life times, extensions providing
-  additional features such as compressing streaming data between two fds, other
-  APIs based on splicing etc. Perhaps a more cautious approach would be better.
-- Pending operation lifetime management in Polyphony was based a complex
-  reference counting scheme that proved problematic, especially for multishot
-  operations.
-
-So, based on those two projects, I wanted to design a Ruby API for io_uring
-based on the following principles:
-
-- Automatic fiber switching.
-- No monkey-patching. Instead, provide a simple custom API, as a replacement for
-  the stock Ruby `IO` and `Socket` classes.
-- Simpler management of pending operation lifetime.
-- Do not insist on structured concurrency, just provide the APIs necessary to
-  create actors and to supervise the execution of fibers.
-
-### Cancellation
-
-When working with io_uring, managing the life cycle of asynchronous operations
-is quite tricky, especially with regards to cancellation. This is due to the
-fact each operation lives on both sides of the userspace-kernel divide. This
-means that when cancelling an operation, we cannot free, or dispose of any
-resources associated with the operation, until we know for sure that the kernel
-side is also done with the operation.
-
-As stated above, working with fibers allows us to keep operation metadata and
-associated data (such as buffers etc) on the stack, which can greatly simplify
-the managing of the operation's lifetime, as well as significantly reduce heap
-allocations.
-
-When a cancellation does occur, UringMachine issues a cancellation (using
-`io_uring_prep_cancel64`), and then waits for the corresponding CQE (with a
-`-ECANCELED` result).
-
-## Short Example
+In UringMachine, an I/O operation is performed by submitting it to the io_uring
+interface (using the io_uring submission queue, or SQ) and waiting for a
+corresponding entry to be added to the completion queue, or CQ. Since
+UringMachine implements fiber-based concurrency, the fiber that performs the I/O
+yields control after submitting the operation, and when a completion is
+received, the fiber is scheduled to be resumed by putting it on the so-called
+"runqueue", which is a queue of fibers ready to be resumed. When the runqueue is
+exhausted, UringMachine enters the kernel in order to wait for one or more I/O
+operation completions.
 
-```ruby
-require 'uringmachine'
+As a general rule, a single UringMachine instance is used for per thread,
+managing the switching between the different fibers created on that same thread.
+In addition, a UringMachine-based fiber scheduler may be installed in order to
+allow any library that performs I/O using standard-library classes such as `IO`,
+`TCPSocket` or `OpenSSL::SSL::SSLSocket`, and higher-level abstractions such as
+`Net::HTTP` to perform I/O using UringMachine.
 
+## Getting Started
+
+To install UringMachine, simply run `gem install uringmachine` or `bundle add
+uringmachine` in your project directory. Note: to use UringMachine, you'll need
+a Linux machine with a minimum kernel version of 6.7. Some features require
+newer kernel versions.
+
+To perform I/O using UringMachine, simply create an instance:
+
+```ruby
 machine = UringMachine.new
-stdout_fd = STDOUT.fileno
-stdin_fd = STDIN.fileno
-machine.write(stdout_fd, "Hello, world!\n")
 
-loop do
-  machine.write(stdout_fd, "Say something: ")
+# or alternatively
+machine = UM.new
+```
+
+You can perform I/O by directly making method calls such as `write` or `read`
+(for the full API see the reference.):
+
+```ruby
+# Most UringMachine instance methods will need you to provide a file descriptor.
+# Here we print a message to STDOUT. Note the explicit line break:
+machine.write(STDOUT, "Hello, world!\n")
+```
+
+UringMachine provides an I/O interface that is to a large degree equivalent to
+the Unix standard C interface:
+
+```ruby
+# Constants used for the different I/O APIs are available under the
+# UringMachine, or UM namespace.
+fd = machine.open('foo.txt', UM::O_RDONLY)
+buf = +''
+size = machine.read(fd, buf, 8192)
+machine.write(STDOUT, "File content: #{buf.inspect}")
+machine.close(fd)
+
+# Or alternatively (with automatic file closing):
+machine.open('foo.txt', UM::O_RDONLY) do |fd|
+  buf = +''
+  size = machine.read(fd, buf, 8192)
+  machine.write(STDOUT, "File content: #{buf.inspect}")
+end
+```
+
+## Fiber control
+
+To perform I/O operations concurrently, you can spin up new fibers by calling
+`#spin`. You can wait for a fiber to terminate by calling `#join`:
+
+```ruby
+# This creates a pipe and returns the file descriptors for its read and write
+# ends.
+r_fd, w_fd = UM.pipe
+
+# read from pipe
+read_fiber = machine.spin do
   buf = +''
-  res = machine.read(stdin_fd, buf, 8192)
-  if res > 0
-    machine.write(stdout_fd, "You said: #{buf}")
-  else
-    break
+  loop do
+    len = machine.read(r_fd, buf, 8192)
+    break if len == 0
+
+    # print to STDOUT
+    machine.write(UM::STDOUT_FILENO, "#{buf}\n")
   end
 end
+
+write_fiber = machine.spin do
+  (1..10).each do |count|
+    machine.sleep(1)
+    machine.write(w_fd, "#{count} Mississipi")
+  end
+  machine.close(w_fd)
+end
+
+# Wait for both fibers to finish running
+machine.join(read_fiber, write_fiber)
 ```
 
-## Concurrent Execution
+You can also terminate a fiber by scheduling it manually. Normally this would be
+done using an exception, which would cause the fiber to cancel whatever
+operation it is currently waiting for, and run any `rescue` or `ensure` block:
 
-Concurrent execution is done by calling `#spin`, which creates a fiber:
+```ruby
+sleep_fiber = machine.spin do
+  puts "Going to sleep..."
+  machine.sleep(3)
+  puts "Done sleeping."
+rescue => e
+  puts "Got error: #{e.inspect}"
+end
+
+# Let sleep_fiber start running
+machine.sleep(0.1)
+machine.schedule(sleep_fiber, RuntimeError.new('Cancel!'))
+machine.join(sleep_fiber)
+```
+
+## Synchronization primitives
+
+UringMachine also includes a io_uring-based implementation of a queue and a
+mutex. `UM::Mutex` can be used for synchronizing access to a protected resource,
+for example a database connection:
 
 ```ruby
-machine = UringMachine.new
+class DBConnection
+  def initialize(machine, db)
+    @machine = machine
+    @db = db
+    @mutex = UM::Mutex.new
+  end
+
+def query(sql)
+  @machine.synchronize(@mutex) do
+    @db.query(sql)
+  end
+end
+```
+
+A queue can be used to coordinate between multiple fibers, for example a fiber
+that consumes data and a fiber that produces data:
 
-rfd, wfd = machine.pipe
+```ruby
+queue = UM::Queue.new
 
-f1 = machine.spin do
-  machine.write(wfd, 'hello')
-  machine.write(wfd, 'world')
-  machine.close(wfd)
+producer = machine.spin do
+  10.times do
+    # lazy producer wants to sleep a bit
+    machine.sleep(rand(0.1..1.5))
+    machine.push(queue, rand(1000))
+  end
+  machine.push(queue, :STOP)
 end
 
-bgid = machine.setup_buffer_ring(4096, 1024)
-f2 = machine.spin do
-  machine.read_each(rfd, bgid) do |str|
-    puts str
+consumer = machine.spin do
+  sum = 0
+  loop do
+    # the call to #shift blocks if the queue is empty
+    value = machine.shift(queue)
+    break if value == :STOP
+
+    sum += value
   end
+  puts "Sum: #{sum}"
+end
+
+machine.join(producer, consumer)
+```
+
+Note: to use the regular Ruby `Mutex` and `Queue` together with UringMachine,
+you'll need to set up a fiber scheduler (see below).
+
+## Sleeping and Working with Timeouts
+
+The `#sleep` method allows a fiber to sleep for a period of time:
+
+```ruby
+puts "Sleeping"
+machine.sleep(1)
+puts "Done sleeping"
+```
+
+You can also perform operations periodically by calling `#periodically`:
+
+```ruby
+machine.spin do
+  # This runs an infinite loop, invoking the block every 200 msecs
+  machine.periodically(0.2) do
+    machine.write(fd, "Hello")
+  end
+end
+```
+
+UringMachine also provides a uniform API for implementing timeouts. To add a
+timeout to an operation, you need to wrap it with a call to `#timeout`:
+
+```ruby
+class TOError < StandardError; end;
+
+# timeout after 3 seconds
+machine.timeout(3, TOError) do
+  # wait to shift an item from the queue
+  value = machine.shift(queue)
+rescue TOError
+  value = nil
 end
 ```
+
+## The Fiber Scheduler
+
+In order to allow UringMachine to integrate with the rest of the Ruby ecosystem,
+and act as the underlying I/O layer, UringMachine includes a full-featured
+implementation of the `Fiber::Scheduler` interface.
+
+Note: in order to benefit a the fiber scheduler you'll need to create so-called
+"non-blocking" fibers. This is usually achieved automatically in app servers
+such as [Falcon](https://github.com/socketry/falcon/).
+
+To start a fiber scheduler, you need to create an instance of
+`UringMachine::FiberScheduler` for each thread where you'll be doing fiber-based
+concurrent I/O:
+
+```ruby
+machine = UM.new
+scheduler = UM::FiberScheduler.new(machine)
+Fiber.set_scheduler(scheduler)
+```
+
+Once the scheduler in place, it's going to handle any I/O or other blocking
+operation (such as sleeping, or locking a mutex, or waiting for a thread to
+terminate) by offloading the operations to the underlying UringMachine instance,
+*provided the I/O is performed inside of a non-blocking fiber. A non-blocking
+fiber can be started either using `UringMachine#spin` or alternatively,
+`Fiber.schedule`:
+
+```ruby
+machine = UM.new
+scheduler = UM::FiberScheduler.new(machine)
+Fiber.set_scheduler(scheduler)
+
+fiber = Fiber.schedule do
+  # this will sleep using underlying UringMachine instance. It is equivalent to
+  # calling machine.sleep(0.05)
+  sleep(0.05)
+end
+```
+
+## Performance
+
+[Detailed benchmarks](benchmark/README.md)
+
+## API Reference
+
+[API Reference](https://www.rubydoc.info/gems/uringmachine)

data/Rakefile

@@ -37,3 +37,11 @@ task :release do
   puts "Cleaning up..."
   `rm *.gem`
 end
+
+require 'yard'
+YARD_FILES = FileList['ext/um/*.c', 'lib/uringmachine.rb', 'lib/uringmachine/**/*.rb']
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = YARD_FILES
+  t.options = %w( --verbose -o yard --readme README.md)
+end

data/TODO.md

@@ -1,6 +1,8 @@
 ## immediate
 
-## buffer rings - automatic management
+- Fix all futex value (Queue, Mutex) to be aligned
+
+## Buffer rings - automatic management
 
 ```ruby
 # completely hands off
@@ -10,40 +12,62 @@ machine.read_each(fd) { |str| ... }
 machine.read_each(fd, io_buffer: true) { |iobuff, len| ... }
 ```
 
-## write/send multiple buffers at once
-
-This is done as vectored IO:
+## Balancing I/O with the runqueue
 
-```ruby
-machine.writev(fd, buf1, buf2, buf3)
+- in some cases where there are many entries in the runqueue, this can
+  negatively affect latency. In some cases, this can also lead to I/O
+  starvation. If the runqueue is never empty, then SQEs are not submitted and
+  CQEs are not processed.
+- So we want to limit the number of consecutive fiber switches before processing
+  I/O.
+- Some possible approaches:
 
-# with optional file offset:
-machine.writev(fd, buf1, buf2, buf3, 0)
+  1. limit consecutive switches with a parameter
+  2. limit consecutive switches relative to the runqueue size and/or the amount
+     of pending SQEs
+  3. an adaptive algorithm that occasionally measures the time between I/O
+     processing iterations, and adjusts the consecutive switches limit?
 
-# for the moment it won't take flags
-machine.sendv(fd, buf1, buf2, buf3)
-```
+- We also want to devise some benchmark that measures throughput / latency with
+  different settings, in a situation with very high concurrency.
 
 ## useful concurrency tools
 
 - debounce
 
   ```ruby
-  debouncer = UM.debounce { }
+  debouncer = machine.debounce { }
   ```
 
+- read multiple files
 
+  ```ruby
+  # with a block
+  machine.read_files(*fns) { |fn, data| ... }
+
+  # without a block
+  machine.read_files(*fns) #=> { fn1:, fn2:, fn3:, ...}
+  ```
 
 ## polyvalent select
 
 - select on multiple queues (ala Go)
 - select on mixture of queues and fds
 
-## ops
+(see also simplified op management below)
+
+## simplified op management
+
+Op lifecycle management can be much much simpler
+
+- make all ops heap-allocated
+- clear up state transitions:
 
-- [ ] multishot timeout
-  - [v] machine.periodically(interval) { ... }
-  - [ ] machine.prep_timeout_multishot(interval)
+  - kernel-side state: unsubmitted, submitted, completed, done (for multishot ops)
+  - app-side state: unsubmitted, submitted, ...
+
+
+## ops
 
 - splice / - tee
 - sendto
@@ -56,7 +80,6 @@ machine.sendv(fd, buf1, buf2, buf3)
 - fadvise
 - madvise
 - getxattr / setxattr
-- send_bundle / recv_bundle (kernel >= 6.10)
 
 ## actors
 

data/benchmark/bm_io_pipe.rb

@@ -2,7 +2,7 @@
 
 require_relative './common'
 
-GROUPS = 50
+GROUPS = 48
 ITERATIONS = 10000
 
 SIZE = 1024
@@ -52,6 +52,18 @@ class UMBenchmark
     end
   end
 
+  def do_baseline_um(machine)
+    GROUPS.times do
+      r, w = UM.pipe
+      ITERATIONS.times {
+        machine.write(w, DATA)
+        machine.read(r, +'', SIZE)
+      }
+      machine.close(w)
+      machine.close(r)
+    end
+  end
+
   def do_scheduler(scheduler, ios)
     GROUPS.times do
       r, w = IO.pipe
@@ -68,6 +80,22 @@ class UMBenchmark
     end
   end
 
+  def do_scheduler_x(div, scheduler, ios)
+    (GROUPS/div).times do
+      r, w = IO.pipe
+      r.sync = true
+      w.sync = true
+      Fiber.schedule do
+        ITERATIONS.times { w.write(DATA) }
+        w.close
+      end
+      Fiber.schedule do
+        ITERATIONS.times { r.readpartial(SIZE) }
+        r.close
+      end
+    end
+  end
+
   def do_um(machine, fibers, fds)
     GROUPS.times do
       r, w = UM.pipe
@@ -81,4 +109,18 @@ class UMBenchmark
       end
     end
   end
+
+  def do_um_x(div, machine, fibers, fds)
+    (GROUPS/div).times do
+      r, w = UM.pipe
+      fibers << machine.spin do
+        ITERATIONS.times { machine.write(w, DATA) }
+        machine.close_async(w)
+      end
+      fibers << machine.spin do
+        ITERATIONS.times { machine.read(r, +'', SIZE) }
+        machine.close_async(r)
+      end
+    end
+  end
 end