uringmachine 0.20.0 → 0.22.0

data/ext/um/um_utils.c

@@ -2,6 +2,7 @@
 #include <sys/mman.h>
 #include <stdlib.h>
 #include <ruby/io/buffer.h>
+#include <time.h>
 
 inline struct __kernel_timespec um_double_to_timespec(double value) {
   double integral;
@@ -16,6 +17,21 @@ inline double um_timestamp_to_double(__s64 tv_sec, __u32 tv_nsec) {
   return (double)tv_sec + ((double)tv_nsec) / 1000000000;
 }
 
+inline double um_get_time_cpu() {
+  struct timespec ts;
+  if (clock_gettime(CLOCK_THREAD_CPUTIME_ID, &ts)) return -1.0;
+
+  return um_timestamp_to_double(ts.tv_sec, ts.tv_nsec);
+}
+
+inline double um_get_time_monotonic() {
+  struct timespec ts;
+  if (clock_gettime(CLOCK_MONOTONIC, &ts)) return -1.0;
+
+  return um_timestamp_to_double(ts.tv_sec, ts.tv_nsec);
+}
+
+
 #define RAISE_EXCEPTION(e) rb_funcall(e, ID_invoke, 0);
 
 inline int um_value_is_exception_p(VALUE v) {

data/grant-2025/journal.md

@@ -205,7 +205,8 @@ Ruby I/O layer. Some interesting warts in the Ruby `IO` implementation:
   I'll see if I can prepare a PR for that to be merged for the Ruby 4.0 release.
 
   For the time being, I've added a `#post_fork` method to the UM fiber scheduler
-  which should be manually called after a fork. (commit 2c7877385869c6acbdd8354e2b2909cff448651b)
+  which should be manually called after a fork. (commit
+  2c7877385869c6acbdd8354e2b2909cff448651b)
 
 - Added two new low-level APIs for waiting on processes, instead of
   `UM#waitpid`, using the io_uring version of `waitid`. The vanilla version
@@ -227,3 +228,243 @@ Ruby I/O layer. Some interesting warts in the Ruby `IO` implementation:
   ...
   pid2, status = machine.waitid(P_PIDFD, fd, UM::WEXITED)
   ```
+
+# 2025-11-28
+
+- On Samuel's suggestions, I've submitted a
+  [PR](https://github.com/ruby/ruby/pull/15342) for adding a
+  `Fiber::Scheduler#process_fork` hook that is automatically invoked after a
+  fork. This is in continuation to the `#post_fork` method. I still have a lot
+  to learn about working with the Ruby core code, but I'm really excited about
+  the possibility of this PR (and the [previous
+  one](https://github.com/ruby/ruby/pull/15213) as well) getting merged in time
+  for the Ruby 4.0 release.
+- Added a bunch of tests for `UM::FiberScheduler`: socket I/O, file I/O, mutex,
+  queue, waiting for threads. In the process I discovered a lots of things that
+  can be improved in the way Ruby invokes the fiber scheduler.
+
+  - For regular files, Ruby assumes file I/O can never be non-blocking (or
+    async), and thus invokes the `#blocking_operation_wait` hook in order to
+    perform the I/O in a separate thread. With io_uring, of course, file I/O
+    *is* asynchronous.
+  - For sockets there are no specialized hooks, like `#socket_send` etc.
+    Instead, Ruby makes the socket fd's non-blocking and invokes `#io_wait` to
+    wait for the socket to be ready.
+
+  I find it interesting how io_uring breaks a lot of assumptions about how I/O
+  should be done.
+
+# 2025-12-03
+
+- Samuel and me continued discussing the behavior of the fiber scheduler after a
+  fork. After talking it through, we decided the best course of action would be
+  to remove the fiber scheduler after a fork, rather than to introduce a
+  `process_fork` hook. This is a safer choice, since a scheduler risks carrying
+  over some of its state across a fork, leading to unexpected behavior.
+
+  Another problem I uncovered is that if a fork is done from a non-blocking
+  fiber, the main fiber of the forked process (which "inherits" the forking
+  fiber) stays in non-blocking mode, which also may lead to unexpected behavior,
+  since the main fiber of all Ruby threads should be in blocking mode.
+
+  So I submitted a new [PR](https://github.com/ruby/ruby/pull/15385) that
+  corrects these two problems.
+
+- I mapped the remaining missing hooks in the UringMachine fiber scheduler
+  implementation, and made the tests more robust by checking that the different
+  scheduler hooks were actually being called.
+
+- Continued implementing the missing fiber scheduler hooks: `#fiber_interrupt`,
+  `#address_resolve`, `#timeout_after`. For the most part, they were simple to
+  implement. I probably spent most of my time figuring out how to test these,
+  rather than implementing them. Most of the hooks involve just a few lines of
+  code, with many of them consisting of a single line of code, calling into the
+  relevant UringMachine low-level API.
+
+- Implemented the `#io_select` hook, which involved implementing a low-level
+  `UM#select` method. This method took some effort to implement, since it needs
+  to handle an arbitrary number of file descriptors to check for readiness. We
+  need to create a separate SQE for each fd we want to poll. When one or more
+  CQEs arrive for polled fd's, we also need to cancel all poll operations that
+  have not completed.
+
+  Since in many cases, `IO.select` is called with just a single IO, I also added
+  a special-case implementation of `UM#select` that specifically handles a
+  single fd.
+
+# 2025-12-04
+
+- Implemented a worker pool for performing blocking operations in the scheduler.
+  Up until now, each scheduler started their own worker thread for performing
+  blocking operations for use in the `#blocking_operation_wait` hook. The new
+  implementation uses a worker thread pool shared by all schedulers, with a
+  worker count limited to CPU count. Workers are started when needed.
+
+  I also added an optional `entries` argument to set the SQE and CQE buffer
+  sizes when starting a new `UringMachine` instance. The default size is 4096
+  SQE entries (liburing by default makes the CQE buffer size double that of the
+  SQE buffer). The blocking operations worker threads specify a value of 4 since
+  they only use their UringMachine instance for popping jobs off the job queue
+  and pushing the blocking operation result back to the scheduler.
+
+- Added support for `file_offset` argument in `UM#read` and `UM#write` in
+  preparation for implementing the `#io_pread` and `#io_pwrite` hooks. The
+  `UM#write_async` API, which permits writing to a file descriptor without
+  waiting for the operation to complete, got support for specifying `length` and
+  `file_offset` arguments as well. In addition, `UM#write` and `UM#write_async`
+  got short-circuit logic for writes with a length of 0.
+
+- Added support for specifying buffer offset in `#io_read` and `#io_write`
+  hooks.
+
+- Added support for timeout in `#block`, `#io_read` and `#io_write` hooks.
+
+# 2025-12-05
+
+- I found and fixed a problem with how `futex_wake` was done in the low-level
+  UringMachine code handling mutexes and queues. This fixed a deadlock in the
+  scheduler background worker pool where clients of the pool where not properly
+  woken after the submitted operation was done.
+
+- I finished work on the `#io_pread` and `#io_pwrite` hooks. Unfortunately, the
+  test for `#io_pwrite` consistently hangs (not on `IO#pwrite` itself, rather on
+  closing the file.) With Samuel's help, hopefully we'll find a solution...
+
+- With those two last hooks, the fiber scheduler implementation is now feature
+  complete! While I have written test cases for the different fiber scheduler
+  hooks, I'd like to add more tests - and especially tests that exercise
+  multiple hooks, tests with high concurrency, and integration tests where I
+  check how the fiber scheduler plays with Ruby APIs like `Net::HTTP` and the
+  `socket` API in general.
+
+# 2025-12-06
+
+- Samuel has found the issue with pwrite (it turns out the the `#io_pwrite` hook
+  was being invoked with the GVL released), and [fixed
+  it](https://github.com/ruby/ruby/pull/15428). So now `#pwrite` works correctly
+  with a fiber scheduler!
+
+- I followed Samuel's suggestion and incorporated some debug logging into the
+  extension code interfacing with liburing, in order to facilitate debugging
+  when issues are encountered.
+
+- Added support for [SQPOLL
+  mode](https://unixism.net/loti/tutorial/sq_poll.html) when setting up a
+  UringMachine instance. It's not clear to me what are the performance
+  implications of that, but I'll try to make some time to check this against
+  [TP2](https://github.com/noteflakes/tp2), a UringMachine-based web server I'm
+  currently using in a bunch of projects.
+
+# 2025-12-07
+
+- I started looking at getting `#io_close` to work, and found out that Samuel
+  has already done the work, that is the code was already there, but was
+  commented out. Samuel explained that it was impossible to get it to work due
+  to the complexity of the implementation of `IO#close`, and indeed when I tried
+  it myself I saw that in fact it was just not possible the way the IO state is
+  managed when an IO is closed. I then had the idea that maybe we could pass the
+  underlying fd instead of the IO object itself to the `#io_close` hook. I tried
+  it and indeed it worked without any problems. The only issue is that this
+  breaks the convention where the different `io_xxx` hooks take an io as their
+  first argument. Nevertheless, I suggested this idea to Samuel and gladly he
+  accepted when he saw this is the only we can make this hook work. Samuel then
+  proceeded to prepare a [PR](https://github.com/ruby/ruby/pull/15434) and merge
+  it.
+
+- Added the `#io_close` hook to the UringMachine fiber scheduler, as well as a
+  `#yield` hook for dealing with thread interrupts in response to another
+  [PR](https://github.com/ruby/ruby/pull/14700) by Samuel. I also added missing
+  docs for the different methods in the fiber scheduler.
+
+# 2025-12-08
+
+- Wrote a bunch of benchmarks for different scenarios comparing threads vs fiber
+  scheduler vs low-level UM implementation. The
+  [results](https://github.com/digital-fabric/uringmachine/blob/main/benchmark/README.md)
+  show the promise of UringMachine and of its fiber scheduler. What is great
+  about the fiber scheduler interface is that it provides a significant boost to
+  I/O-bound scenarios, with almost no change to the source code (basically, you
+  just need to replace `Thread.new` with `Fiber.schedule`).
+
+  These results, though preliminary, seem to validate the approach I took with
+  UringMachine - implementing a low-level API and tying it to the entire Ruby
+  ecosystem by way of the fiber scheduler interface.
+
+- Spent the rest of the day writing lots of tests for the fiber scheduler. I
+  tried to cover the entire `IO` API - both class- and instance methods. I also
+  wrote some "integration" tests - different scenarios not unlike those in the
+  benchmarks, which exercise the different hooks in the fiber scheduler.
+
+- Added some new APIs to help with testing: `UM#await_fibers` is a method for
+  waiting for one or more fibers to terminate. Unlike `UM#join`, it doesn't
+  return the return values of the given fibers, it just waits for them to
+  terminate. Another new API is `UM.socketpair`, which is like
+  `Socket.socketpair` except it returns raw fd's.
+
+- Fixed a tricky bug that caused an occasional segmentation fault while running
+  benchmarks. Some fibers waiting an operation to complete were garbage
+  collected because there was no reference to them anywhere. I fixed this by
+  adding a map of pending fibers at the C-extension level and adding and
+  removing pending fibers from it automatically. I also added checking for
+  leaking fibers at the end of each test, so the UringMachine instance will not
+  hold onto fibers that have terminated.
+
+# 2025-12-09
+
+- Added the Async fiber scheduler to the different benchmarks. Also added an
+  SQPOLL mode to the benchmarks. Added a PG client benchmark.
+
+- Fixed some small issues in the UM fiber scheduler and in the UM low-level API
+  implementation.
+
+# 2025-12-10
+
+- Refactored the benchmarks, abstracting away all the common code into a
+  common class that is then used in the different benchmarks. I also added a
+  test for ASync with an epoll selector. I'll try to find some time in the
+  coming days to update the results in the repo.
+
+- Added and streamlined metrics that indicate the following:
+
+  - The ring size
+  - Total number of ops
+  - Total number of fiber switches
+  - Total number of waits for CQEs
+  - Current number of pending ops
+  - Current number of unsubmitted ops
+  - Current size of runqueue
+  - Current number of transient ops
+  - Current number of free ops
+
+  I also added some basic time measurements:
+
+  - Total CPU time
+  - Total time spent waiting for CQEs
+
+  These are off by default, but can be enabled by calling `UM#profile(true)`.
+  I'd like to do a lot more with profiling, like measuring the CPU time spent on
+  each fiber, but I'm a bit apprehensive of the performance costs involved, as
+  getting the `CLOCK_THREAD_CPUTIME_ID` clock is relatively slow, and then
+  managing this for each fiber means getting and setting a couple of instance
+  variables, which can *really* slow things down. On top of that, I'm not that
+  sure this is really needed.
+
+- I went through some old benchmarks, reorganized them, get rid of some that
+  were irrelevant. There were some really interesting ones: a benchmark
+  measuring the cost of different ways of accessing an SQLite DB (using
+  [Extralite](https://github.com/digital-fabric/extralite/)): normally, using an
+  actor interface, or protected by a mutex. I'll try to follow up with a
+  benchmark measuring concurrent access to SQLite DBs, similar to the PG one.
+  
+  Another interesting benchmark I found was one for resolving DNS addresses
+  using Ruby's builtin `Addrinfo` API, the bundled `resolv` gem, and a basic DNS
+  resolver included in UringMachine (I totally forgot I made one). Here too, I'd
+  like to add a benchmark to measure how these different solutions do in a
+  highly concurrent scenario.
+  
+- Thanks to one of these old benchmarks I made a change that more than doubled
+  the performance of `UM#snooze`. What this method does is it adds the current
+  fiber to the end of the runqueue, and yields control to the next fiber in the
+  runqueue, or to process available CQE's. This method is useful for testing,
+  but also for yielding control periodically when performing CPU-bound work, in
+  order to keep the application responsive and improve latency.

data/grant-2025/tasks.md

@@ -1,44 +1,119 @@
 - [v] io-event
-
   - [v] Make PR to use io_uring_prep_waitid for kernel version >= 6.7
 
-    - https://github.com/socketry/io-event/blob/44666dc92ac3e093ca6ce3ab47052b808a58a325/ext/io/event/selector/uring.c#L460
-    - https://github.com/digital-fabric/uringmachine/blob/d5505d7fd94b800c848d186e17585e03ad9af6f2/ext/um/um.c#L697-L713
+- [ ] UringMachine low-level API
+  - [v] Add support for IO::Buffer in UM API.
+  - [v] Add `UM::Error` class to be used instead of RuntimeError
+  - [v] Add optional ring size argument to `UM.new` (for example, a the
+        worker thread for the scheduler `blocking_operation_wait` hook does not need
+        a lot of depth, so you can basically do `UM.new(4)`)
+  - [v] Add debugging code suggested by Samuel
+  - [v] Add support for SQPOLL
+        https://unixism.net/loti/tutorial/sq_poll.html
+  - [v] Add `UM.socketpair`
+
+  - [ ] Add more metrics
+    - [v] runqueue depth
+    - [v] number of pending fibers
+    - [v] ops: transient count, free count
+    - [v] total fiber switches, total waiting for CQEs
+    - [ ] watermark: ops_pending, ops_unsubmitted, ops_runqueue, ops_free, ops_transient
+          (only in profile mode)
+  - [ ] Performance tuning parameters
+    - [ ] max fiber switches before processing CQEs
+    - [ ] max fiber switches before submitting unsubmitted SQEs
+    - [ ] measure switches since last submitting / last CQE processing
+
+  - [ ] Add support for using IO::Buffer in association with io_uring registered
+    buffers / buffer rings
+  - [ ] Add some way to measure fiber CPU time.
+        https://github.com/socketry/async/issues/428
+
+- [ ] UringMachine Fiber::Scheduler implementation
+  - [v] Check how scheduler interacts with `fork`.
+  - [v] Implement `process_wait` (with `rb_process_status_new`)
+  - [v] Implement `fiber_interrupt` hook
+  - [v] Add `#address_resolve` hook with same impl as Async:
+        https://github.com/socketry/async/blob/ea8b0725042b63667ea781d4d011786ca3658256/lib/async/scheduler.rb#L285-L296
+  - [v] Implement other hooks:
+    - [v] `#timeout_after`
+          https://github.com/socketry/async/blob/ea8b0725042b63667ea781d4d011786ca3658256/lib/async/scheduler.rb#L631-L644
+    - [v] `#io_pread`
+    - [v] `#io_pwrite`
+    - [v] `#io_select`
+    - [v] Add timeout handling in different I/O hooks
+  - [v] Experiment more with fork:
+    - [v] what happens to schedulers on other threads (those that don't make it post-fork)
+          - do they get GC'd?
+          - do they get closed (`#scheduler_close` called)?
+          - are they freed cleanly (at least for UM)?
+
+          ```ruby
+          class S
+            def respond_to?(sym) = true
+          end
+          o = S.new
+          ObjectSpace.define_finalizer(o, ->(*){ puts 'scheduler finalized' })
+          t1 = Thread.new { Fiber.set_scheduler(o); sleep }
+          t2 = Thread.new {
+            fork { p(t1:, t2:) }
+            GC.start
+          }
+
+          # output:
+          # scheduler finalized
+          ```
+
+          So, apparently there's no problem!
+  - [v] Implement multi-thread worker pool for `blocking_operation_wait`
+        Single thread pool at class level, shared by all schedulers
+        With worker count according to CPU count
+  - [v] Test working with non-blocking files, it should be fine, and we shouldn't need to reset `O_NONBLOCK`.
+  - [v] Implement timeouts (how do timeouts interact with blocking ops?)
+  - [v] Implement `#yield` hook (https://github.com/ruby/ruby/pull/14700)
+  - [v] Finish documentation for the `FiberScheduler` class
+  - [v] Implement `#io_close` hook
+
+  - [v] tests:
+    - [v] Wrap the scheduler interface such that we can verify that specific
+      hooks were called. Add asserts for called hooks for all tests.
+    - [v] Sockets (only io_wait)
+    - [v] Files
+    - [v] Mutex / Queue
+    - [v] Thread.join
+    - [v] Process.wait
+    - [v] fork
+    - [v] system / exec / etc.
+    - [v] popen
+  - [v] "Integration tests"
+    - [v] IO - all methods!
+    - [v] queue: multiple concurrent readers / writers
+    - [v] net/http test: ad-hoc HTTP/1.1 server + `Net::HTTP` client
+    - [v] pipes: multiple pairs of fibers - reader / writer
+    - [v] sockets: echo server + many clients
 
-- [ ] UringMachine
-  - [v] Add support for IO::Buffer in UM API. (How can we detect an IO::Buffer object?)
-        https://docs.ruby-lang.org/capi/en/master/d8/d36/group__object.html#gab1b70414d07e7de585f47ee50a64a86c
+  - [ ] Benchmarks
+    - [v] UM queue / Ruby queue (threads) / Ruby queue with UM fiber scheduler
 
-  - [v] Add `UM::Error` class to be used instead of RuntimeError
+          N groups where each group has M producers and O consumers accessing the same queue.
 
-  - [ ] Do batch allocation for `struct um_op`, so they'll be adjacent
-  - [ ] Add optional buffer depth argument to `UM.new` (for example, a the
-    worker thread for the scheduler `blocking_operation_wait` hook does not need
-    a lot of depth, so you can basically do `UM.new(4)`)
+    - [v] UM mutex / Ruby mutex (threads) / Ruby mutex with UM fiber scheduler
 
-  - [ ] Add support for using IO::Buffer in association with io_uring registered buffers / buffer rings
+      - [v] N groups where each group has M fibers locking the same mutex and
+            performing CPU-bound work
+      - [v] N groups where each group has M fibers locking the same mutex and
+            performing IO-bound work (write to a file)
 
-- [ ] FiberScheduler implementation
-4
-  - [v] Check how scheduler interacts with `fork`.
-  - [v] Implement `process_wait` (with `rb_process_status_new`)
-  - [ ] Implement timeouts (how do timeouts interact with blocking ops?)
-  - [ ] Implement address resolution hook
-  - [ ] Add tests:
-    - [ ] Sockets
-    - [ ] Files
-    - [ ] Mutex / Queue
-    - [ ] Thread.join
-    - [ ] Process.wait
-    - [ ] fork
-    - [ ] system / exec / etc.
-    - [ ] popen
+    - [v] Pipe IO raw UM / Ruby threaded / Ruby with UM fiber scheduler
+
+          N groups where each group has a pair of reader / writer to a pipe
+
+    - [v] Socket IO (with socketpair) raw UM / Ruby threaded / Ruby with UM fiber scheduler
+
+          N groups where each group has a pair of reader / writer to a socketpair
+
+    - [v] Postgres test
 
-  - [ ] Benchmarks
-    - [ ] UM queue / Ruby queue (threads) / Ruby queue with UM fiber scheduler
-    - [ ] UM mutex / Ruby mutex (threads) / Ruby mutex with UM fiber scheduler
-    - [ ] Pipe IO raw UM / Ruby threaded / Ruby with UM fiber scheduler
-    - [ ] Socket IO (with socketpair) raw UM / Ruby threaded / Ruby with UM fiber scheduler
     - [ ] Measure CPU (thread) time usage for above examples
 
         - run each version 1M times
@@ -49,18 +124,38 @@
         cpu_time = Process.clock_gettime(Process::CLOCK_THREAD_CPUTIME_ID)
         ```
 
-        - my hunch is we'll be able to show with io_uring real_time is less,
-          while cpu_time is more. But it's just a hunch.
-
-
-  - https://github.com/ruby/ruby/blob/master/doc/fiber.md
-  - https://github.com/ruby/ruby/blob/master/test/fiber/scheduler.rb
-  - https://github.com/socketry/async/blob/main/context/getting-started.md
-- https://github.com/socketry/async/blob/main/context/scheduler.md
-- https://github.com/socketry/async/blob/main/lib/async/scheduler.rb#L28
+- [ ] Ruby Fiber::Scheduler interface
+  - [v] Make a PR for resetting the scheduler and resetting the fiber non-blocking flag.
+  - [v] hook for close
+  - [ ] hooks for send/recv/sendmsg/recvmsg
 
 - [ ] SSL
   - [ ] openssl gem: custom BIO?
 
     - curl: https://github.com/curl/curl/blob/5f4cd4c689c822ce957bb415076f0c78e5f474b5/lib/vtls/openssl.c#L786-L803
 
+- [ ] UringMachine website
+  - [ ] domain: uringmachine.dev
+  - [ ] logo: ???
+  - [ ] docs (similar to papercraft docs)
+
+- [ ] Uma - web server
+  - [ ] child process workers
+  - [ ] reforking (following https://github.com/Shopify/pitchfork)
+        see also: https://byroot.github.io/ruby/performance/2025/03/04/the-pitchfork-story.html
+        - Monitor worker memory usage - how much is shared
+        - Choose worker with most served request count as "mold" for next generation
+        - Perform GC out of band, preferably when there are no active requests
+          https://railsatscale.com/2024-10-23-next-generation-oob-gc/
+        - When a worker is promoted to "mold", it:
+          - Stops `accept`ing requests
+          - When finally idle, calls `Process.warmup`
+          - Starts replacing sibling workers with forked workers
+        see also: https://www.youtube.com/watch?v=kAW5O2dkSU8
+  - [ ] Each worker is single-threaded (except for auxiliary threads)
+  - [ ] Rack 3.0-compatible
+        see: https://github.com/socketry/protocol-rack
+  - [ ] Rails integration (Railtie)
+        see: https://github.com/socketry/falcon
+  - [ ] Benchmarks
+  - [ ] Add to the TechEmpower bencchmarks

data/lib/uringmachine/actor.rb

@@ -24,6 +24,8 @@ class UringMachine
   end
 
   class Actor < Fiber
+    class Stop < UM::Error; end
+
     def run(machine, target, mailbox)
       @machine = machine
       @target = target
@@ -31,6 +33,8 @@ class UringMachine
       while (msg = machine.shift(mailbox))
         process_message(msg)
       end
+    rescue Stop
+      # stopped
     ensure
       @target.teardown if @target.respond_to?(:teardown)
     end
@@ -45,6 +49,10 @@ class UringMachine
       @machine.shift response_mailbox
     end
 
+    def stop
+      @machine.schedule(self, Stop.new)
+    end
+
     private
 
     def process_message(msg)

data/lib/uringmachine/dns_resolver.rb

@@ -10,7 +10,6 @@ class UringMachine
       @nameservers = get_nameservers
       @fiber = @machine.spin { handle_requests_loop }
       @last_id = 0
-      @cache = {}
     end
 
     def resolve(hostname, type)
@@ -59,7 +58,7 @@ class UringMachine
       msg = Resolv::DNS::Message.decode buf
       addrs = []
       msg.each_answer do |name, ttl, data|
-        p [name, ttl, data]
+        # p [name, ttl, data]
         if data.kind_of?(Resolv::DNS::Resource::IN::A) ||
           data.kind_of?(Resolv::DNS::Resource::IN::AAAA)
           addrs << data.address.to_s