uringmachine 0.23.1 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a53007580b3e3fc11ce53466d79afa6a68e8546966d080b73b45cea166843e12
-  data.tar.gz: f86c71ea56e72fe9d0fbbd130191b97d1e411feee7398f4bb748eda561ea4732
+  metadata.gz: 258d087be861df468fe7b4cf1628fe2669f095c0f347db65a5b5d63b31d34421
+  data.tar.gz: 12d340eb8c71147557af11dbbeb2b961ec163ecdc4f28c8688d19a3b20e232ec
 SHA512:
-  metadata.gz: 8a414b66431041c2d738cf8b0a68c4a78a2ebb14ad900868e351dac35de930aa5d1fe6862d67dedb90ce19f935bd6808ff0948825362960153c6fe95a7c4fe82
-  data.tar.gz: 688cab6262c1a83267f4d08909554dbb7bb2046bd55b2b1c5eb6e7b183b5487c2d14d681e44174f347dd5afea860b7d04e3db256477433cf46d3dc60a192ee77
+  metadata.gz: e22dd92400e845b2b6931f10d96b5e926b413d72cc7e2c80df355f188b1989774fc963cbea32b9ca3373da403efc685ad3806e7a9965459295973db38f922d78
+  data.tar.gz: e7fa4a7728f64306d2219225d41ab697e17bdd76274015c13ad16d9b2f14d1d6e961896e62c03ded86607f8b59e908ccac708b470a07be6f4aadac11349db034

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/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 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,3 @@
-source 'https://rubygems.org'
+source 'https://gem.coop'
 
 gemspec

data/TODO.md

@@ -1,6 +1,20 @@
 ## immediate
 
-## buffer rings - automatic management
+- 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
 # completely hands off
@@ -10,35 +24,61 @@ machine.read_each(fd) { |str| ... }
 machine.read_each(fd, io_buffer: true) { |iobuff, len| ... }
 ```
 
-## write/send multiple buffers at once
+## Balancing I/O with the runqueue
 
-This is done as vectored IO:
+- 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:
 
-```ruby
-machine.writev(fd, buf1, buf2, buf3)
-
-# 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
 
+(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:
+
+  - kernel-side state: unsubmitted, submitted, completed, done (for multishot ops)
+  - app-side state: unsubmitted, submitted, ...
+
+
 ## ops
 
 - [ ] multishot timeout

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

data/benchmark/bm_io_socketpair.rb

@@ -3,10 +3,10 @@
 require_relative './common'
 require 'socket'
 
-GROUPS = 50
+GROUPS = 48
 ITERATIONS = 10000
 
-SIZE = 1024
+SIZE = 1 << 14
 DATA = '*' * SIZE
 
 class UMBenchmark
@@ -55,6 +55,22 @@ class UMBenchmark
     end
   end
 
+  def do_scheduler_x(div, scheduler, ios)
+    (GROUPS/div).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)
@@ -68,4 +84,18 @@ class UMBenchmark
       end
     end
   end
+
+  def do_um_x(div, machine, fibers, fds)
+    (GROUPS/div).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_io.rb

@@ -4,9 +4,9 @@ require_relative './common'
 require 'securerandom'
 require 'fileutils'
 
-GROUPS = ENV['N']&.to_i || 50
+GROUPS = ENV['N']&.to_i || 48
 WORKERS = 10
-ITERATIONS = 1000
+ITERATIONS = 10000
 
 puts "N=#{GROUPS}"
 
@@ -14,10 +14,15 @@ SIZE = 1024
 DATA = "*" * SIZE
 
 class UMBenchmark
+  def cleanup
+    # `rm /tmp/mutex*` rescue nil
+  end
+
   def do_threads(threads, ios)
     GROUPS.times do
       mutex = Mutex.new
-      ios << (f = File.open("/tmp/mutex_io_threads_#{SecureRandom.hex}", 'w'))
+      # ios << (f = File.open("/tmp/mutex_io_threads_#{SecureRandom.hex}", 'w'))
+      ios << (f = File.open("/dev/null", 'w'))
       f.sync = true
       WORKERS.times do
         threads << Thread.new do
@@ -34,7 +39,24 @@ class UMBenchmark
   def do_scheduler(scheduler, ios)
     GROUPS.times do
       mutex = Mutex.new
-      ios << (f = File.open("/tmp/mutex_io_fiber_scheduler_#{SecureRandom.hex}", 'w'))
+      # ios << (f = File.open("/tmp/mutex_io_fiber_scheduler_#{SecureRandom.hex}", 'w'))
+      ios << (f = File.open("/dev/null", '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_scheduler_x(div, scheduler, ios)
+    (GROUPS/div).times do
+      mutex = Mutex.new
+      # ios << (f = File.open("/tmp/mutex_io_fiber_scheduler_#{SecureRandom.hex}", 'w'))
+      ios << (f = File.open("/dev/null", 'w'))
       f.sync = true
       WORKERS.times do
         Fiber.schedule do
@@ -49,7 +71,27 @@ class UMBenchmark
   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))
+      # fds << (fd = machine.open("/tmp/mutex_io_um_#{SecureRandom.hex}", UM::O_CREAT | UM::O_WRONLY))
+      fds << (fd = machine.open("/dev/null", UM::O_WRONLY))
+      WORKERS.times do
+        fibers << machine.spin do
+          ITERATIONS.times do
+            machine.synchronize(mutex) do
+              machine.write(fd, DATA)
+            end
+          end
+        rescue => e
+          p e
+        end
+      end
+    end
+  end
+
+  def do_um_x(div, machine, fibers, fds)
+    (GROUPS/div).times do
+      mutex = UM::Mutex.new
+      # fds << (fd = machine.open("/tmp/mutex_io_um_#{SecureRandom.hex}", UM::O_CREAT | UM::O_WRONLY))
+      fds << (fd = machine.open("/dev/null", UM::O_WRONLY))
       WORKERS.times do
         fibers << machine.spin do
           ITERATIONS.times do

data/benchmark/common.rb

@@ -9,6 +9,7 @@ gemfile do
   gem 'io-event'
   gem 'async'
   gem 'pg'
+  gem 'gvltools'
 end
 
 require 'uringmachine/fiber_scheduler'
@@ -54,26 +55,56 @@ class UMBenchmark
   end
 
   @@benchmarks = {
-    baseline:     [:baseline,     "No Concurrency"],
-    threads:      [:threads,      "Threads"],
-    thread_pool:  [:thread_pool,  "ThreadPool"],
-    async_uring:  [:scheduler,    "Async uring"],
-    async_epoll:  [:scheduler,    "Async epoll"],
-    um_fs:        [:scheduler,    "UM FS"],
-    um:           [:um,           "UM"],
-    um_sqpoll:    [:um,           "UM sqpoll"]
+    # baseline:     [:baseline,     "No Concurrency"],
+    # baseline_um:  [:baseline_um,  "UM no concurrency"],
+    # thread_pool:  [:thread_pool,  "ThreadPool"],
+
+    threads:        [:threads,      "Threads"],
+
+    async_uring:    [:scheduler,    "Async uring"],
+    async_uring_x2: [:scheduler_x,  "Async uring x2"],
+
+    # async_epoll:    [:scheduler,    "Async epoll"],
+    # async_epoll_x2: [:scheduler_x,  "Async epoll x2"],
+
+    um_fs:          [:scheduler,    "UM FS"],
+    um_fs_x2:       [:scheduler_x,  "UM FS x2"],
+
+    um:             [:um,           "UM"],
+    um_sidecar:     [:um,           "UM sidecar"],
+    # um_sqpoll:      [:um,           "UM sqpoll"],
+    um_x2:          [:um_x,         "UM x2"],
+    um_x4:          [:um_x,         "UM x4"],
+    um_x8:          [:um_x,         "UM x8"],
   }
 
   def run_benchmarks(b)
+    STDOUT.sync = true
     @@benchmarks.each do |sym, (doer, name)|
-      b.report(name) { send(:"run_#{sym}") } if respond_to?(:"do_#{doer}")
+      if respond_to?(:"do_#{doer}")
+        STDOUT << "Running #{name}... "
+        ts = nil
+        b.report(name) {
+          ts = measure_time { send(:"run_#{sym}") }
+        }
+        p ts
+        cleanup
+      end
     end
   end
 
+  def cleanup
+  end
+
   def run_baseline
     do_baseline
   end
 
+  def run_baseline_um
+    machine = UM.new(4096)
+    do_baseline_um(machine)
+  end
+
   def run_threads
     threads = []
     ios = []
@@ -117,27 +148,140 @@ class UMBenchmark
     ios.each { it.close rescue nil }
   end
 
+  def run_async_uring_x2
+    threads  = 2.times.map do
+      Thread.new do
+        selector ||= IO::Event::Selector::URing.new(Fiber.current)
+        worker_pool = Async::Scheduler::WorkerPool.new
+        scheduler = Async::Scheduler.new(selector:, worker_pool:)
+        Fiber.set_scheduler(scheduler)
+        ios = []
+        scheduler.run { do_scheduler_x(2, scheduler, ios) }
+        ios.each { it.close rescue nil }
+      end
+    end
+    threads.each(&:join)
+  end
+
+  def run_async_epoll_x2
+    threads  = 2.times.map do
+      Thread.new do
+        selector ||= IO::Event::Selector::EPoll.new(Fiber.current)
+        scheduler = Async::Scheduler.new(selector:)
+        Fiber.set_scheduler(scheduler)
+        ios = []
+        scheduler.run { do_scheduler_x(2, scheduler, ios) }
+        ios.each { it.close rescue nil }
+      end
+    end
+    threads.each(&:join)
+  end
+
+  def run_um_fs_x2
+    threads  = 2.times.map do
+      Thread.new do
+        machine = UM.new
+        thread_pool = UM::BlockingOperationThreadPool.new(2)
+        scheduler = UM::FiberScheduler.new(machine, thread_pool)
+        Fiber.set_scheduler(scheduler)
+        ios = []
+        do_scheduler_x(2, scheduler, ios)
+        scheduler.join
+        ios.each { it.close rescue nil }
+      end
+    end
+    threads.each(&:join)
+  end
+
   def run_um
-    machine = UM.new(4096)
+    machine = UM.new
+    fibers = []
+    fds = []
+    do_um(machine, fibers, fds)
+    machine.await_fibers(fibers)
+    fds.each { machine.close(it) }
+  end
+
+  def run_um_sidecar
+    machine = UM.new(sidecar: true)
     fibers = []
     fds = []
     do_um(machine, fibers, fds)
     machine.await_fibers(fibers)
-    puts "UM:"
-    p machine.metrics
     fds.each { machine.close(it) }
   end
 
   def run_um_sqpoll
-    machine = UM.new(4096, true)
+    machine = UM.new(sqpoll: true)
     fibers = []
     fds = []
     do_um(machine, fibers, fds)
     machine.await_fibers(fibers)
-    fds.each { machine.close_async(it) }
-    puts "UM sqpoll:"
-    p machine.metrics
-    machine.snooze
+    fds.each { machine.close(it) }
+  end
+
+  def run_um_x2
+    threads  = 2.times.map do
+      Thread.new do
+        machine = UM.new
+        fibers = []
+        fds = []
+        do_um_x(2, machine, fibers, fds)
+        machine.await_fibers(fibers)
+        fds.each { machine.close(it) }
+      end
+    end
+    threads.each(&:join)
+  end
+
+  def run_um_x4
+    threads  = 4.times.map do
+      Thread.new do
+        machine = UM.new
+        fibers = []
+        fds = []
+        do_um_x(4, machine, fibers, fds)
+        machine.await_fibers(fibers)
+        fds.each { machine.close(it) }
+      end
+    end
+    threads.each(&:join)
+  end
+
+  def run_um_x8
+    threads  = 8.times.map do
+      Thread.new do
+        machine = UM.new
+        fibers = []
+        fds = []
+        do_um_x(8, machine, fibers, fds)
+        machine.await_fibers(fibers)
+        fds.each { machine.close(it) }
+      end
+    end
+    threads.each(&:join)
+  end
+
+  def measure_time
+    GVLTools::GlobalTimer.enable
+    t0s = [
+      Process.clock_gettime(Process::CLOCK_MONOTONIC),
+      Process.clock_gettime(Process::CLOCK_PROCESS_CPUTIME_ID),
+      GVLTools::GlobalTimer.monotonic_time / 1_000_000_000.0
+    ]
+    yield
+    t1s = [
+      Process.clock_gettime(Process::CLOCK_MONOTONIC),
+      Process.clock_gettime(Process::CLOCK_PROCESS_CPUTIME_ID),
+      GVLTools::GlobalTimer.monotonic_time / 1_000_000_000.0
+    ]
+    {
+      monotonic:  t1s[0] - t0s[0],
+      cpu:        t1s[1] - t0s[1],
+      gvl:        t1s[2] - t0s[2]
+    }
+  ensure
+    GVLTools::GlobalTimer.disable
   end
 end
 

data/benchmark/http_parse.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
-# require 'bundler/inline'
-
-# gemfile do
-#   source 'https://rubygems.org'
-#   gem 'uringmachine', path: '..'
-#   gem 'benchmark-ips'
-#   gem 'http_parser.rb'
-# end
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'uringmachine', path: '..'
+  gem 'benchmark'
+  gem 'benchmark-ips'
+  gem 'http_parser.rb'
+end
 
-require 'bundler/setup'
 require 'uringmachine'
 require 'benchmark/ips'
 require 'http/parser'

data/benchmark/http_server_accept_queue.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'uringmachine', path: '..'
+end
+
+require 'uringmachine'
+
+RE_REQUEST_LINE = /^([a-z]+)\s+([^\s]+)\s+(http\/[0-9\.]{1,3})/i
+RE_HEADER_LINE = /^([a-z0-9\-]+)\:\s+(.+)/i
+
+def stream_get_request_line(stream, buf)
+  line = stream.get_line(buf, 0)
+  m = line&.match(RE_REQUEST_LINE)
+  return nil if !m
+
+  {
+    'method'   => m[1].downcase,
+    'path'     => m[2],
+    'protocol' => m[3].downcase
+  }
+end
+
+class InvalidHeadersError < StandardError; end
+
+def get_headers(stream, buf)
+  headers = stream_get_request_line(stream, buf)
+  return nil if !headers
+
+  while true
+    line = stream.get_line(buf, 0)
+    break if line.empty?
+
+    m = line.match(RE_HEADER_LINE)
+    raise InvalidHeadersError, "Invalid header" if !m
+
+    headers[m[1]] = m[2]
+  end
+
+  headers
+end
+
+BODY = "Hello, world!" * 1000
+
+def send_response(machine, fd)
+  headers = "HTTP/1.1 200\r\nContent-Length: #{BODY.bytesize}\r\n\r\n"
+  machine.sendv(fd, headers, BODY)
+end
+
+def handle_connection(machine, fd)
+  stream = UM::Stream.new(machine, fd)
+  buf = String.new(capacity: 65536)
+
+  while true
+    headers = get_headers(stream, buf)
+    break if !headers
+
+    send_response(machine, fd)
+  end
+rescue InvalidHeadersError, SystemCallError => e
+  # ignore
+ensure
+  machine.close_async(fd)
+end
+
+N = ENV['N']&.to_i || 1
+PORT = ENV['PORT']&.to_i || 1234
+
+accept_queue = UM::Queue.new
+
+acceptor = Thread.new do
+  machine = UM.new
+  fd = machine.socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
+  machine.setsockopt(fd, UM::SOL_SOCKET, UM::SO_REUSEADDR, true)
+  machine.setsockopt(fd, UM::SOL_SOCKET, UM::SO_REUSEPORT, true)
+  machine.bind(fd, '127.0.0.1', PORT)
+  machine.listen(fd, 128)
+  machine.accept_into_queue(fd, accept_queue)
+rescue Exception => e
+  p e
+  p e.backtrace
+  exit!
+end
+
+workers = N.times.map do |idx|
+  Thread.new do
+    machine = UM.new
+
+    loop do
+      fd = machine.shift(accept_queue)
+      machine.spin { handle_connection(machine, fd) }
+    end
+  rescue Exception => e
+    p e
+    p e.backtrace
+    exit!
+  end
+end
+
+puts "Listening on localhost:#{PORT}, #{N} worker thread(s)"
+acceptor.join