uringmachine 0.21.0 → 0.22.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e14941110d09a575728da68cb038a02334d151f0d384d88ad67a34b21a49d234
-  data.tar.gz: 158299106b117a973163ae480ea4e9827a0cb88eb76b2323da04fd631e8916ca
+  metadata.gz: fbf0486feb49686a85ad162dd569ce125b4f168904e6f364e7c4358be234ca78
+  data.tar.gz: 27d0e3533c7d41f87b95376258992e37ebfa0d42c32ac0b46e7595939b3f1afa
 SHA512:
-  metadata.gz: f71a5b6b6740fea281df8880511b424a0c759e876e17f79a6b661453416d13c2d9d65e0c53ddee5df066ca92472571ffae8c0e9a4ca4fd745d02705a8645965d
-  data.tar.gz: baa86b9bc0009c69bfe894aae3489d43ed28d1fca44a24a9ddc7cc1625a54de6c17f65731c1a707af561942174f9584554a183a67f8428d5855e799c274db0b6
+  metadata.gz: c4bf87080fe32e145e334944cc1871d109f5b11c5c3cb413c9de3f44cf09b9554ac3fabeb54650c18f67ed96d6381a0290ae8e461ff37b9fef3d27351675ff68
+  data.tar.gz: a53addafe3007de3ad77f3e42e4ca3b3f90ae372af24b00beff1b5b486fa4c1f5d6c84de22788192b05328c14c7eeec4e602a77623a00c5c2f8de5bdbd8dca7d

data/.rubocop.yml

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

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+# 0.22.1 2025-12-11
+
+- Comment out SIGCLD constant
+
+# 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,139 @@
+# 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.
+
+- `ThreadPool`: thread pool consisting of 10 worker threads, receiving jobs
+  through a common queue.
+
+- `Async epoll`: fiber-based concurrency with
+  [Async](https://github.com/socketry/async) fiber scheduler, using an epoll
+  selector.
+
+- `Async uring`: fiber-based concurrency with Async fiber scheduler, using a
+  uring selector.
+
+- `UM FS`: fiber-based concurrency with UringMachine fiber scheduler.
+
+- `UM`: fiber-based concurrency using the UringMachine low-level API.
+
+<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. Interestingly, when
+  performing CPU-bound work, it seems slightly slightly slower. This should be
+  investigated.
+
+- 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.
+
+According to these benchmarks, for I/O-bound scenarios the different fiber-based
+implementations present a average speedup as follows:
+
+|implementation|average factor|
+|--------------|--------------|
+|Async epoll   |x2.36         |
+|Async uring   |x2.42         |
+|UM FS         |x2.85         |
+|UM            |x6.20         |
+
+## 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.105002   2.671980   4.776982 (  4.272842)
+ThreadPool   4.818014  10.740555  15.558569 (  7.070236)
+Async epoll  1.118937   0.254803   1.373740 (  1.374298)
+Async uring  1.363248   0.270063   1.633311 (  1.633696)
+UM FS        0.746332   0.183006   0.929338 (  0.929619)
+UM           0.237816   0.328352   0.566168 (  0.566265)
+```
+
+## 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.
+
+```
+C=50x2           user     system      total        real
+Threads      2.068122   3.247781   5.315903 (  4.295488)
+ThreadPool   2.283882   3.461607   5.745489 (  4.650422)
+Async epoll  0.381400   0.846445   1.227845 (  1.227983)
+Async uring  0.472526   0.821467   1.293993 (  1.294166)
+UM FS        0.443023   0.734334   1.177357 (  1.177576)
+UM           0.116995   0.675997   0.792992 (  0.793183)
+```
+
+## 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.
+
+```
+C=20x10          user     system      total        real
+Threads      5.174998   0.024885   5.199883 (  5.193211)
+Async epoll  5.309793   0.000949   5.310742 (  5.311217)
+Async uring  5.341404   0.004860   5.346264 (  5.346963)
+UM FS        5.363719   0.001976   5.365695 (  5.366254)
+UM           5.351073   0.005986   5.357059 (  5.357602)
+```
+
+## 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.
+
+```
+C=50x10          user     system      total        real
+Threads      2.042649   3.441547   5.484196 (  4.328783)
+Async epoll  0.810375   0.744084   1.554459 (  1.554726)
+Async uring  0.854985   1.129260   1.984245 (  1.140749)
+UM FS        0.686329   0.872376   1.558705 (  0.845214)
+UM           0.250370   1.323227   1.573597 (  0.720928)
+```
+
+## 5. Postgres client
+
+C concurrent threads/fibers, each thread issuing SELECT query to a PG database.
+
+```
+C=50             user     system      total        real
+Threads      4.304292   1.358116   5.662408 (  4.795725)
+Async epoll  2.890160   0.432836   3.322996 (  3.334350)
+Async uring  2.818439   0.433896   3.252335 (  3.252799)
+UM FS        2.819371   0.443182   3.262553 (  3.264606)
+```
+## 6. 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.
+
+```
+C=20x(5+10)      user     system      total        real
+Threads      4.880983   0.207451   5.088434 (  5.071019)
+Async epoll  4.107208   0.006519   4.113727 (  4.114227)
+Async uring  4.206283   0.028974   4.235257 (  4.235705)
+UM FS        4.082394   0.001719   4.084113 (  4.084522)
+UM           4.099893   0.323569   4.423462 (  4.424089)
+```

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

data/benchmark/bm_pg_client.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative './common'
+require 'securerandom'
+
+C = ENV['C']&.to_i ||50
+I = 1000
+puts "C=#{C}"
+
+class UMBenchmark
+  CONTAINER_NAME = "pg-#{SecureRandom.hex}"
+
+  def start_pg_server
+    `docker run --name #{CONTAINER_NAME} -e POSTGRES_PASSWORD=my_password -d -p 5432:5432 postgres`
+  end
+
+  def stop_pg_server
+    `docker stop #{CONTAINER_NAME}`
+  end
+
+  PG_OPTS = {
+    host:                         'localhost',
+    user:                         'postgres',
+    password:                     'my_password',
+    dbname:                       'postgres'
+  }
+
+  def create_db_conn(retries = 0)
+    ::PG.connect(PG_OPTS)
+  rescue ::PG::ConnectionBad
+    if retries < 3
+      sleep 0.5
+      create_db_conn(retries + 1)
+    else
+    raise
+    end
+  end
+
+  PREPARE_SQL = <<~SQL
+    create table if not exists foo(value int, name text);
+    create index if not exists idx_foo_value on foo(value);
+    with t1 as (
+      select generate_series(1,100000)
+      ),
+    t2 as (
+      select (random()*1000000)::integer as value,
+             (md5(random()::text)) as name
+      from t1
+    )
+    insert into foo(value, name) select * from t2;
+  SQL
+
+  def prepare_db
+    STDOUT << "Preparing database..."
+    t0 = Time.now
+    conn = create_db_conn
+    conn.exec(PREPARE_SQL)
+    puts " elapsed: #{Time.now - t0}"
+  end
+
+  def query_db(conn)
+    min = rand(1000000)
+    max = min + 2000
+    sql = format(
+      'select * from foo where value >= %d and value < %d;', min, max
+    )
+    conn.query(sql).to_a
+  end
+
+  def with_container
+    start_pg_server
+    sleep 0.5
+    prepare_db
+    yield
+  rescue Exception => e
+    p e
+    p e.backtrace
+  ensure
+  stop_pg_server
+  end
+
+  def benchmark
+    with_container {
+      Benchmark.bm { run_benchmarks(it) }
+    }
+  end
+
+  def do_threads(threads, ios)
+    C.times.map do
+      threads << Thread.new do
+        conn = create_db_conn
+        I.times { query_db(conn) }
+      ensure
+        conn.close
+      end
+    end
+  end
+
+  def do_scheduler(scheduler, ios)
+    C.times do
+      Fiber.schedule do
+        conn = create_db_conn
+        I.times { query_db(conn) }
+      ensure
+        conn.close
+      end
+    end
+  end
+end