uringmachine 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e14941110d09a575728da68cb038a02334d151f0d384d88ad67a34b21a49d234
-  data.tar.gz: 158299106b117a973163ae480ea4e9827a0cb88eb76b2323da04fd631e8916ca
+  metadata.gz: 74e4816d1191d862df3ba04d46cc038d04b999c22c5604d9a4eec0d1d3fd047c
+  data.tar.gz: d857ba559f6c48dfc8d65a1812eb3996c7a65d70d263e016bbb96dbf99e6273c
 SHA512:
-  metadata.gz: f71a5b6b6740fea281df8880511b424a0c759e876e17f79a6b661453416d13c2d9d65e0c53ddee5df066ca92472571ffae8c0e9a4ca4fd745d02705a8645965d
-  data.tar.gz: baa86b9bc0009c69bfe894aae3489d43ed28d1fca44a24a9ddc7cc1625a54de6c17f65731c1a707af561942174f9584554a183a67f8428d5855e799c274db0b6
+  metadata.gz: 662c0f7e07df7f87c759eb3e8001aa91c0682d55c63fc46e0429c5ac577de3e0f89476f93b0deb3e05fb3fba4daa4eaae767141615c9e1af1b35df8966f7d988
+  data.tar.gz: d22cc49d99ef5772411ebdb8019b6d83eb9e944a83b0a327c638bb5eeaef5661ed3cc34dcb6673a26049e9f7f17cebe76306ca7b847cd4bc0e244c99dfafb210

data/.rubocop.yml

@@ -0,0 +1,2 @@
+AllCops:
+  DisabledByDefault: true

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+# 0.22.0 2025-12-10
+
+- Fix use of `um_yield` in statx, multishot ops
+- Improve performance of `UM#snooze`
+- Add some profiling info (WIP)
+- Add `UM#metrics` for getting metrics
+- Add `UM#pending_fibers` for detecting leaking fibers in tests
+- More tests and benchmarks
+- Add `UM#await_fibers` for awaiting fibers
+- Add `UM.socketpair` for creating a socket pair
+- Fiber scheduler:
+  - Use fiber's mailbox for processing blocking operations
+  - Add `#io_close`, `#yield` hooks, remove `#process_fork` hook
+
 # 0.21.0 2025-12-06
 
 - Add `UM#submit`

data/TODO.md

@@ -1,5 +1,149 @@
 ## immediate
 
+## Measuring CPU time for fibers
+
+- use CPU time (CLOCK_THREAD_CPUTIME_ID)
+- measure:
+  - time each fiber is waiting
+  - time each fiber is running
+  - time machine is waiting (for CQEs)
+  - time machine is running fibers from the runqueue
+- can be turned on/off at any time
+- no performance impact when off
+
+How can this be implemented:
+
+- `um_get_time_cpu()` function for reading CPU time (CLOCK_THREAD_CPUTIME_ID) as
+  double.
+- add to `struct um`:
+
+  ```c
+  struct um {
+    ...
+    int profiling_mode;
+    double total_time_run;
+    double total_time_wait;
+    double last_cpu_time;
+  }
+  ```
+
+- `UM#profile=` to turn it on/off.
+- On `machine.profile = true`, reset `total_time_xxx` and `last_cpu_time`
+
+  ```c
+  machine->total_time_run = 0;
+  machine->total_time_wait = 0;
+  machine->last_cpu_time = um_get_time_cpu();
+  ```
+
+- when profiling is active:
+  - before processing CQEs:
+
+    ```c
+    // before
+    double cpu_time0;
+    VALUE fiber;
+    int profiling_mode = machine->profiling_mode;
+    if (profiling_mode) {
+      fiber = rb_fiber_current();
+      cpu_time0 = um_get_time_cpu();
+      double elapsed = cpu_time0 - machine->last_cpu_time;
+      um_update_fiber_time_run(fiber, cpu_time0, elapsed);
+      machine->total_time_run += elapsed;
+    }
+    process_cqes(...)
+    // after
+    if (profiling_mode) {
+      double cpu_time1 = um_get_time_cpu();
+      double elapsed = cpu_time1 - cpu_time0;
+      um_update_fiber_last_time(fiber, cpu_time1);
+      machine->total_time_wait += elapsed;
+      machine->last_cpu_time = cpu_time1;
+    }
+    ```
+
+  - when doing switching, in `um_process_runqueue_op`:
+
+    ```c
+    // before
+    double cpu_time;
+    VALUE cur_fiber;
+    VALUE next_fiber = get_next_fiber(...);
+    int profiling_mode = machine->profiling_mode;
+    if (profiling_mode) {
+      cur_fiber = rb_fiber_current();
+      cpu_time = um_get_time_cpu();
+      double elapsed = cpu_time - machine->last_cpu_time;
+      um_update_fiber_time_run(cur_fiber, cpu_time, elapsed);
+      machine->total_time_run += elapsed;
+      um_update_fiber_time_wait(next_fiber, cpu_time);
+      machine->last_cpu_time = cpu_time;
+    }
+    do_fiber_transfer(...)
+    ```
+
+  - updating fiber time instance vars:
+
+    ```c
+    inline void um_update_fiber_time_run(VALUE fiber, double stamp, double elapsed) {
+      // VALUE fiber_stamp = rb_ivar_get(fiber, ID_time_last_cpu);
+      VALUE fiber_total_run = rb_ivar_get(fiber, ID_time_total_run);
+      double total = NIL_P(fiber_total_run) ?
+        elapsed : NUM2DBL(fiber_total_run) + elapsed;
+      rb_ivar_set(fiber, ID_time_total_run, DBL2NUM(total));
+      rb_ivar_set(fiber, ID_time_last_cpu, DBL2NUM(stamp));
+    }
+
+    inline void um_update_fiber_time_wait(VALUE fiber, double stamp) {
+      VALUE fiber_last_stamp = rb_ivar_get(fiber, ID_time_last_cpu);
+      if (likely(!NIL_P(fiber_last_stamp))) {
+        double last_stamp = NUM2DBL(fiber_last_stamp);
+        double elapsed = stamp - last_stamp;
+        VALUE fiber_total_wait = rb_ivar_get(fiber, ID_time_total_wait);
+        double total = NIL_P(fiber_total_wait) ?
+          elapsed : NUM2DBL(fiber_total_wait) + elapsed;
+        rb_ivar_set(fiber, ID_time_total_wait, DBL2NUM(total));
+      }
+      else
+        rb_ivar_set(fiber, ID_time_total_wait, DBL2NUM(0.0));
+      rb_ivar_set(fiber, ID_time_last_cpu, DBL2NUM(stamp));
+    }
+    ```
+
+## Metrics API
+
+- machine metrics: `UM#metrics` - returns a hash containing metrics:
+
+  ```ruby
+  {
+    size:,          # SQ size (entries)
+    total_ops:, # total ops submitted
+    total_fiber_switches:, # total fiber switches
+    total_cqe_waits:, # total number of CQE waits
+    ops_pending:, # number of pending ops
+    ops_unsubmitted:, # number of unsubmitted
+    ops_runqueue:, # number of ops in runqueue
+    ops_free:, # number of ops in freelist
+    ops_transient:, # number of ops in transient list
+    hwm_pending:, # high water mark - pending ops
+    hwm_unsubmitted:, # high water mark - unsubmitted ops
+    hwm_runqueue:, # high water mark - runqueue depth
+    hwm_free:, # high water mark - ops in free list
+    hwm_transient:, # high water mark - ops in transient list
+    # when profiling is active
+    time_total_run:, # total CPU time running
+    time_total_wait:, # total CPU time waiting for CQEs
+  }
+  ```
+
+- For this we need to add tracking for:
+  - runqueue list size
+  - transient list size
+  - free list size
+- Those will be done in um_op.c (in linked list management code)
+
+- All metrics info in kept in
+
 ## useful concurrency tools
 
 - debounce

data/benchmark/README.md

@@ -0,0 +1,173 @@
+# UringMachine Benchmarks
+
+The following benchmarks measure the performance of UringMachine against stock
+Ruby in a variety of scenarios. For each scenario, we compare three different
+implementations:
+
+- **Threads**: thread-based concurrency using the stock Ruby I/O and
+  synchronization classes.
+
+- **Async FS**: fiber-based concurrency with the
+  [Async](https://github.com/socketry/async) fiber scheduler, using the stock
+  Ruby I/O and synchronization classes.
+
+- **UM FS**: fiber-based concurrency with the UringMachine fiber scheduler,
+  using the stock Ruby I/O and synchronization classes.
+
+- **UM pure**: fiber-based concurrency using the UringMachine low-level (pure)
+  API.
+
+- **UM sqpoll**: the same as **UM pure** with [submission queue
+  polling](https://unixism.net/loti/tutorial/sq_poll.html).
+
+<img src="./chart.png">
+
+## Observations:
+
+- We see the stark difference between thread-based and fiber-based concurrency.
+  For I/O-bound workloads, there's really no contest - and that's exactly why
+  the fiber scheduler interface changes everything.
+
+- The UringMachine fiber scheduler is in some cases faster than the Async fiber
+  scheduler, but not in all. This might be because the Async FS does scheduling
+  of fibers in plain Ruby, while the UMFS implements a runqueue in its
+  C-extension.
+
+- The UringMachine low-level API is faster to use in most cases, and its
+  performance advantage grows with the level of concurrency.
+
+- SQ polling provides a performance advantage in high-concurrency scenarios,
+  depending on the context. It remains to be seen how it affects performance in
+  real-world situations.
+
+- The [pg](https://github.com/ged/ruby-pg) gem supports the use of fiber
+  schedulers, and there too we see a marked performance advantage to using
+  fibers instead of threads.
+
+## 1. I/O - Pipe
+
+50 groups, where in each group we create a pipe with a pair of threads/fibers
+writing/reading 1KB of data to the pipe.
+
+```
+C=50x2         user     system      total        real
+Threads    2.501885   3.111840   5.613725 (  5.017991)
+Async FS   1.189332   0.526275   1.715607 (  1.715726)
+UM FS      0.715688   0.318851   1.034539 (  1.034723)
+UM pure    0.241029   0.365079   0.606108 (  0.606308)
+UM sqpoll  0.217577   0.634414   0.851991 (  0.593531)
+```
+
+## 2. I/O - Socketpair
+
+50 concurrent groups, where in each group we create a unix socketpair with a
+pair of threads/fibers writing/reading 1KB of data to the sockets.
+
+```
+N=50           user     system      total        real
+Threads    2.372753   3.612468   5.985221 (  4.798625)
+Async FS   0.516226   0.877822   1.394048 (  1.394266)
+UM FS      0.521360   0.875674   1.397034 (  1.397327)
+UM pure    0.239353   0.642498   0.881851 (  0.881962)
+UM sqpoll  0.220933   1.021997   1.242930 (  0.976198)
+```
+
+## 3. Mutex - CPU-bound
+
+20 concurrent groups, where in each group we create a mutex and start 10 worker
+threads/fibers locking the mutex and performing a Regexp match.
+
+```
+N=20           user     system      total        real
+Threads    5.348378   0.021847   5.370225 (  5.362117)
+Async FS   5.519970   0.003964   5.523934 (  5.524536)
+UM FS      5.505282   0.003983   5.509265 (  5.509840)
+UM pure    5.607048   0.002991   5.610039 (  5.610749)
+UM sqpoll  5.437836   5.418316  10.856152 (  5.443331)
+```
+
+## 4. Mutex - I/O-bound
+
+N concurrent groups, where in each group we create a mutex, open a file and
+start 10 worker threads/fibers locking the mutex and writing 1KB chunks to the
+file.
+
+```
+N=1            user     system      total        real
+Threads    0.044103   0.057831   0.101934 (  0.087204)
+Async FS   0.050608   0.084449   0.135057 (  0.121300)
+UM FS      0.030355   0.077069   0.107424 (  0.108146)
+UM pure    0.024489   0.086201   0.110690 (  0.108023)
+UM sqpoll  0.022752   0.225133   0.247885 (  0.136251)
+
+N=5            user     system      total        real
+Threads    0.214296   0.384078   0.598374 (  0.467425)
+Async FS   0.085820   0.158782   0.244602 (  0.139766)
+UM FS      0.064279   0.147278   0.211557 (  0.117488)
+UM pure    0.036478   0.182950   0.219428 (  0.119745)
+UM sqpoll  0.036929   0.347573   0.384502 (  0.160814)
+
+N=10           user     system      total        real
+Threads    0.435688   0.752219   1.187907 (  0.924561)
+Async FS   0.126573   0.303704   0.430277 (  0.234900)
+UM FS      0.128427   0.215204   0.343631 (  0.184074)
+UM pure    0.065522   0.359659   0.425181 (  0.192385)
+UM sqpoll  0.076810   0.477429   0.554239 (  0.210087)
+
+N=20           user     system      total        real
+Threads    0.830763   1.585299   2.416062 (  1.868194)
+Async FS   0.291823   0.644043   0.935866 (  0.507887)
+UM FS      0.226202   0.460401   0.686603 (  0.362879)
+UM pure    0.120524   0.616274   0.736798 (  0.332182)
+UM sqpoll  0.177150   0.849890   1.027040 (  0.284069)
+
+N=50           user     system      total        real
+Threads    2.124048   4.182537   6.306585 (  4.878387)
+Async FS   0.897134   1.268629   2.165763 (  1.254624)
+UM FS      0.733193   0.971821   1.705014 (  0.933749)
+UM pure    0.226431   1.504441   1.730872 (  0.760731)
+UM sqpoll  0.557310   2.107389   2.664699 (  0.783992)
+
+N=100          user     system      total        real
+Threads    4.420832   8.628756  13.049588 ( 10.264590)
+Async FS   2.557661   2.532998   5.090659 (  3.179336)
+UM FS      2.262136   1.912055   4.174191 (  2.523789)
+UM pure    0.633897   2.793998   3.427895 (  1.612989)
+UM sqpoll  1.119460   4.193703   5.313163 (  1.525968)
+```
+
+## 5. Queue
+
+20 concurrent groups, where in each group we create a queue, start 5 producer
+threads/fibers that push items to the queue, and 10 consumer threads/fibers that
+pull items from the queue.
+
+```
+N=20           user     system      total        real
+Threads    2.522270   0.125569   2.647839 (  2.638276)
+Async FS   2.245917   0.044860   2.290777 (  2.291068)
+UM FS      2.235130   0.000958   2.236088 (  2.236392)
+UM pure    2.125827   0.225050   2.350877 (  2.351347)
+UM sqpoll  2.044662   2.460344   4.505006 (  2.261502)
+```
+
+## 6. Postgres client
+
+C concurrent threads/fiber, each thread issuing SELECT query to a PG database.
+
+```
+C=10          user     system      total        real
+Threads   0.813844   0.358261   1.172105 (  0.987320)
+Async FS  0.545493   0.098608   0.644101 (  0.644636)
+UM FS     0.523503   0.094336   0.617839 (  0.619250)
+
+C=20          user     system      total        real
+Threads   1.652901   0.714299   2.367200 (  2.014781)
+Async FS  1.136826   0.212991   1.349817 (  1.350544)
+UM FS     1.084873   0.205865   1.290738 (  1.291865)
+
+C=50          user     system      total        real
+Threads   4.410604   1.804900   6.215504 (  5.253016)
+Async FS  2.918522   0.507981   3.426503 (  3.427966)
+UM FS     2.789549   0.537269   3.326818 (  3.329802)
+```

data/benchmark/bm_io_pipe.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative './common'
+
+GROUPS = 50
+ITERATIONS = 10000
+
+SIZE = 1024
+DATA = '*' * SIZE
+
+class UMBenchmark
+  def do_threads(threads, ios)
+    GROUPS.times do
+      r, w = IO.pipe
+      r.sync = true
+      w.sync = true
+      threads << Thread.new do
+        ITERATIONS.times { w.write(DATA) }
+        w.close
+      end
+      threads << Thread.new do
+        ITERATIONS.times { r.readpartial(SIZE) }
+        r.close
+      end
+    end
+  end
+
+  def do_thread_pool(thread_pool, ios)
+    GROUPS.times do
+      r, w = IO.pipe
+      r.sync = true
+      w.sync = true
+      ios << r << w
+      ITERATIONS.times {
+        thread_pool.queue { w.write(DATA) }
+        thread_pool.queue { r.readpartial(SIZE) }
+      }
+    end
+  end
+
+  def do_scheduler(scheduler, ios)
+    GROUPS.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
+      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

data/benchmark/bm_io_socketpair.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative './common'
+require 'socket'
+
+GROUPS = 50
+ITERATIONS = 10000
+
+SIZE = 1024
+DATA = '*' * SIZE
+
+class UMBenchmark
+  def do_threads(threads, ios)
+    GROUPS.times do
+      r, w = Socket.socketpair(:AF_UNIX, :SOCK_STREAM, 0)
+      r.sync = true
+      w.sync = true
+      threads << Thread.new do
+        ITERATIONS.times { w.send(DATA, 0) }
+        w.close
+      end
+      threads << Thread.new do
+        ITERATIONS.times { r.recv(SIZE) }
+        r.close
+      end
+    end
+  end
+
+  def do_thread_pool(thread_pool, ios)
+    GROUPS.times do
+      r, w = Socket.socketpair(:AF_UNIX, :SOCK_STREAM, 0)
+      r.sync = true
+      w.sync = true
+      ios << r << w
+      ITERATIONS.times {
+        thread_pool.queue { w.send(DATA, 0) }
+        thread_pool.queue { r.recv(SIZE) }
+      }
+    end
+  end
+
+  def do_scheduler(scheduler, ios)
+    GROUPS.times do
+      r, w = Socket.socketpair(:AF_UNIX, :SOCK_STREAM, 0)
+      r.sync = true
+      w.sync = true
+      Fiber.schedule do
+        ITERATIONS.times { w.send(DATA, 0) }
+        w.close
+      end
+      Fiber.schedule do
+        ITERATIONS.times { r.recv(SIZE) }
+        r.close
+      end
+    end
+  end
+
+  def do_um(machine, fibers, fds)
+    GROUPS.times do
+      r, w = UM.socketpair(UM::AF_UNIX, UM::SOCK_STREAM, 0)
+      fibers << machine.spin do
+        ITERATIONS.times { machine.send(w, DATA, SIZE, UM::MSG_WAITALL) }
+        machine.close_async(w)
+      end
+      fibers << machine.spin do
+        ITERATIONS.times { machine.recv(r, +'', SIZE, 0) }
+        machine.close_async(r)
+      end
+    end
+  end
+end

data/benchmark/bm_mutex_cpu.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative './common'
+
+GROUPS = 20
+WORKERS = 10
+ITERATIONS = 10000
+
+STR = "foobar" * 100
+RE = /foo(.+)$/
+
+class UMBenchmark
+  def do_threads(threads, ios)
+    GROUPS.times do
+      mutex = Mutex.new
+      WORKERS.times do
+        threads << Thread.new do
+          ITERATIONS.times do
+            mutex.synchronize do
+              STR.match(RE)
+            end
+          end
+        end
+      end
+    end
+  end
+
+  def do_scheduler(scheduler, ios)
+    GROUPS.times do
+      mutex = Mutex.new
+      WORKERS.times do
+        Fiber.schedule do
+          ITERATIONS.times do
+            mutex.synchronize do
+              STR.match(RE)
+            end
+          end
+        end
+      end
+    end
+  end
+
+  def do_um(machine, fibers, fds)
+    GROUPS.times do
+      mutex = UM::Mutex.new
+      WORKERS.times do
+        fibers << machine.spin do
+          ITERATIONS.times do
+            machine.synchronize(mutex) do
+              STR.match(RE)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/benchmark/bm_mutex_io.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative './common'
+require 'securerandom'
+require 'fileutils'
+
+GROUPS = ENV['N']&.to_i || 50
+WORKERS = 10
+ITERATIONS = 1000
+
+puts "N=#{GROUPS}"
+
+SIZE = 1024
+DATA = "*" * SIZE
+
+class UMBenchmark
+  def do_threads(threads, ios)
+    GROUPS.times do
+      mutex = Mutex.new
+      ios << (f = File.open("/tmp/mutex_io_threads_#{SecureRandom.hex}", 'w'))
+      f.sync = true
+      WORKERS.times do
+        threads << Thread.new do
+          ITERATIONS.times do
+            mutex.synchronize do
+              f.write(DATA)
+            end
+          end
+        end
+      end
+    end
+  end
+
+  def do_scheduler(scheduler, ios)
+    GROUPS.times do
+      mutex = Mutex.new
+      ios << (f = File.open("/tmp/mutex_io_fiber_scheduler_#{SecureRandom.hex}", 'w'))
+      f.sync = true
+      WORKERS.times do
+        Fiber.schedule do
+          ITERATIONS.times do
+            mutex.synchronize { f.write(DATA) }
+          end
+        end
+      end
+    end
+  end
+
+  def do_um(machine, fibers, fds)
+    GROUPS.times do
+      mutex = UM::Mutex.new
+      fds << (fd = machine.open("/tmp/mutex_io_um_#{SecureRandom.hex}", UM::O_CREAT | UM::O_WRONLY))
+      WORKERS.times do
+        fibers << machine.spin do
+          ITERATIONS.times do
+            machine.synchronize(mutex) do
+              machine.write(fd, DATA)
+            end
+          end
+        end
+      end
+    end
+  end
+end