uringmachine 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 258d087be861df468fe7b4cf1628fe2669f095c0f347db65a5b5d63b31d34421
-  data.tar.gz: 12d340eb8c71147557af11dbbeb2b961ec163ecdc4f28c8688d19a3b20e232ec
+  metadata.gz: 162f747c9286305e5bba72e0ab5c3d0d89c9a0ff42e1480b4c247a05dab0c2f3
+  data.tar.gz: 41ebc4a248a204f898d6d4cc954405b441c533109f08cae2806a0204bd1726aa
 SHA512:
-  metadata.gz: e22dd92400e845b2b6931f10d96b5e926b413d72cc7e2c80df355f188b1989774fc963cbea32b9ca3373da403efc685ad3806e7a9965459295973db38f922d78
-  data.tar.gz: e7fa4a7728f64306d2219225d41ab697e17bdd76274015c13ad16d9b2f14d1d6e961896e62c03ded86607f8b59e908ccac708b470a07be6f4aadac11349db034
+  metadata.gz: d99daa2b45df0c28f9d087e19ce92678f78b76c551d47a5c55d93188a881b347a3d87f49cb93dc10686c5c89726fbc97b40e656cbcb09becbd53eeccc790e435
+  data.tar.gz: ba9f0408ac9157e82dfd34595d73d5e924a58cf8db0ee76971c5675b44c89a1ace5219e569c3a21ceff6e51439d39814f9a1f2a0314a2506bbde9169679c6707

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,12 @@
+# 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`

data/Gemfile

@@ -1,3 +1,14 @@
 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

@@ -2,18 +2,6 @@
 
 - Fix all futex value (Queue, Mutex) to be aligned
 
-## Sidecar thread
-
-The sidecar thread is an auxiliary thread that is used to wait for CQEs. It
-calls `io_uring_wait_cqe` (or equivalent lower-level interface) in a loop, and
-each time a CQE is available, it signals this to the primary UringMachine
-thread (using a futex).
-
-The primary UringMachine thread runs fibers from the runqueue. When the runqueue
-is exhausted, it performs a `io_uring_submit` for unsubmitted ops. It then waits
-for the futex to become signalled (non-zero), and then processes all available
-completions.
-
 ## Buffer rings - automatic management
 
 ```ruby
@@ -81,10 +69,6 @@ Op lifecycle management can be much much simpler
 
 ## ops
 
-- [ ] multishot timeout
-  - [v] machine.periodically(interval) { ... }
-  - [ ] machine.prep_timeout_multishot(interval)
-
 - splice / - tee
 - sendto
 - recvfrom
@@ -96,7 +80,6 @@ Op lifecycle management can be much much simpler
 - fadvise
 - madvise
 - getxattr / setxattr
-- send_bundle / recv_bundle (kernel >= 6.10)
 
 ## actors
 

data/benchmark/common.rb

@@ -10,6 +10,8 @@ gemfile do
   gem 'async'
   gem 'pg'
   gem 'gvltools'
+  gem 'openssl'
+  gem 'localhost'
 end
 
 require 'uringmachine/fiber_scheduler'

data/benchmark/openssl.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'uringmachine', path: '..'
+  gem 'benchmark'
+  gem 'benchmark-ips'
+  gem 'openssl'
+  gem 'localhost'
+end
+
+require 'uringmachine'
+require 'benchmark/ips'
+require 'openssl'
+require 'localhost/authority'
+
+authority = Localhost::Authority.fetch
+ctx = authority.server_context
+ctx.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+Socket.do_not_reverse_lookup = true
+tcps = TCPServer.new("127.0.0.1", 0)
+port = tcps.connect_address.ip_port
+
+ssls = OpenSSL::SSL::SSLServer.new(tcps, ctx)
+
+Thread.new do
+  Thread.current.report_on_exception = false
+  loop do
+    begin
+      ssl = ssls.accept
+    rescue OpenSSL::SSL::SSLError, IOError, Errno::EBADF, Errno::EINVAL,
+           Errno::ECONNABORTED, Errno::ENOTSOCK, Errno::ECONNRESET
+      retry
+    end
+
+    Thread.new do
+      Thread.current.report_on_exception = false
+
+      begin
+        while line = ssl.gets
+          ssl.write(line)
+        end
+      ensure
+        ssl.close
+      end
+      true
+    end
+  end
+end
+
+@ssl_stock = OpenSSL::SSL::SSLSocket.open("127.0.0.1", port)
+@ssl_stock.sync_close = true
+@ssl_stock.connect
+
+um = UM.new
+
+@ssl_um = OpenSSL::SSL::SSLSocket.open("127.0.0.1", port)
+@ssl_um.sync_close = true
+um.ssl_set_bio(@ssl_um)
+@ssl_um.connect
+
+@msg = 'abc' * 1000
+
+def do_io(ssl)
+  ssl.puts @msg
+  ssl.gets
+end
+
+Benchmark.ips do |x|
+  x.report('stock') { do_io(@ssl_stock) }
+  x.report('UM BIO') { do_io(@ssl_um) }
+
+  x.compare!(order: :baseline)
+end