uringmachine 0.29.1 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 248a2f0e2a780904f26f0183d08237039e18b76b736e7b3563c2699e30041d65
-  data.tar.gz: 2020b0c8cc9be25becddef80fa4c66f0bc49e30d0791ec2b2b2e618fbf3ab0b6
+  metadata.gz: a97099f1d89b2333b8be056c91acabad63fad122ce4c802a666e4abb10aca93b
+  data.tar.gz: '095878ee7df374be5dc87b74ea636b3def2b611006c76c7d86ae7c00ad064f47'
 SHA512:
-  metadata.gz: 543a8adf2c628f080f9ec249e11ff7e4bd969f0eca9e47285ba0ef20c28575ddd6d1902a3890d49ccb1ccf5100d13cd721bbd03c472bde15205344524fd7795c
-  data.tar.gz: 4afbe860f29187507c57a8e319d02f2f843d27aa7d65176f0e0040914bf4d8e68ce894d4663b13d3ace530bf2aa4fe3ca547e58d5cbcb1daf5d89f6d5bb94ae2
+  metadata.gz: 339349fd4116011334517f124201a1cf425762c1bafe33ba61fa3eaf175fa5064512f780f8354f8fc317515bab6c4914cb41fba2022d23c17aac7e08d18cad7b
+  data.tar.gz: 02c7b30e4143f07382f2788a9f242e6f051f57b438fc3ecc63153a13f318bbbab69e5239add2af31e277c68b21483be60bd542863c8f7aa358d7fa1b0c0793e9

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+# 0.30.0 2026-03-23
+
+- Add `Stream#each`
+- Add `UM#splice`, `UM#tee`, `UM#fsync`
+- Add `UM#tcp_listen`, `UM#tcp_connect`
+
+# 0.29.2 2026-03-15
+
+- Add `Stream#consumed`, `Stream#pending`
+- Add `UM#stream`
+- Add `Stream#skip`
+
 # 0.29.1 2026-03-14
 
 - Add support for exception instance in `#timeout`

data/README.md

@@ -32,11 +32,13 @@ implementation that allows integration with the entire Ruby ecosystem.
 ## Features
 
 - Automatic fiber switching when performing blocking I/O operations.
-- Automatic cancellation using of ongoing operations with Ruby exceptions.
+- Automatic cancellation ongoing operations with Ruby exceptions.
 - General-purpose API for cancelling any operation on timeout.
 - Excellent performance characteristics for concurrent I/O-bound applications.
 - `Fiber::Scheduler` implementation to automatically integrate with the Ruby
   ecosystem in a transparent fashion.
+- Read streams with automatic buffer management.
+- Optimized I/O for encrypted SSL connections.
 
 ## Design
 
@@ -61,8 +63,8 @@ allow any library that performs I/O using standard-library classes such as `IO`,
 
 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.
+a Linux machine with a minimum Linux kernel version of 6.7. Some features
+require newer kernel versions.
 
 To perform I/O using UringMachine, simply create an instance:
 
@@ -79,7 +81,7 @@ You can perform I/O by directly making method calls such as `write` or `read`
 ```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")
+machine.write(UM::STDOUT_FILENO, "Hello, world!\n")
 ```
 
 UringMachine provides an I/O interface that is to a large degree equivalent to
@@ -91,14 +93,14 @@ the Unix standard C interface:
 fd = machine.open('foo.txt', UM::O_RDONLY)
 buf = +''
 size = machine.read(fd, buf, 8192)
-machine.write(STDOUT, "File content: #{buf.inspect}")
+machine.write(UM::STDOUT_FILENO, "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}")
+  machine.write(UM::STDOUT_FILENO, "File content: #{buf.inspect}")
 end
 ```
 
@@ -284,6 +286,104 @@ fiber = Fiber.schedule do
 end
 ```
 
+## Read Streams
+
+A UringMachine stream is used to efficiently read from a socket or other file
+descriptor. Streams are ideal for implementing the read side of protocols, and
+provide an API that is useful for both line-based protocols and binary
+(frame-based) protocols.
+
+A stream is associated with a UringMachine instance and a target file descriptor
+(see also [stream modes](#stream-modes) below). Behind the scenes, streams take
+advantage of io_uring's registered buffers feature, and more recently, the
+introduction of [incremental buffer
+consumption](https://github.com/axboe/liburing/wiki/What's-new-with-io_uring-in-6.11-and-6.12#incremental-provided-buffer-consumption).
+
+When streams are used, UringMachine automatically manages the buffers it
+provides to the kernel, maximizing buffer reuse and minimizing allocations.
+UringMachine also responds to stress conditions (increased incoming traffic) by
+automatically provisioning additional buffers.
+
+To create a stream for a given fd, use `UM#stream`:
+
+```ruby
+stream = machine.stream(fd)
+
+# you can also provide a block that will be passed the stream instance:
+machine.stream(fd) { |s| do_something_with(s) }
+
+# you can also instantiate a stream directly:
+stream = UM::Stream.new(machine, fd)
+```
+
+The following API is used to interact with the stream:
+
+```ruby
+# Read until a newline character is encountered:
+line = stream.get_line(0)
+
+# Read line with a maximum length of 13 bytes:
+line = stream.get_line(13)
+
+# Read all data:
+buf = stream.get_string(0)
+
+# Read exactly 13 bytes:
+buf = stream.get_string(13)
+
+# Read up to 13 bytes:
+buf = stream.get_string(-13)
+
+# Skip 3 bytes:
+stream.skip(3)
+```
+
+Here's an example of a how a basic HTTP request parser might be implemented
+using a stream:
+
+```ruby
+def parse_http_request_headers(stream)
+  request_line = stream.get_line(0)
+  m = request_line.match(REQUEST_LINE_RE)
+  return nil if !m
+
+  headers = {
+    ':method'   => m[1],
+    ':path'     => m[2],
+    ':protocol' => m[3]
+  }
+
+  while true
+    line = stream.get_line(0)
+    break if !line || line.empty?
+
+    m = line.match(HEADER_RE)
+    headers[m[1].downcase] = m[2]
+  end
+  headers
+end
+```
+
+### Stream modes
+
+Stream modes allow streams to be transport agnostic. Currently streams support
+three modes:
+
+- `:bp_read` - use the buffer pool, read data using multishot read
+  (this is the default mode).
+- `:bp_recv` - use the buffer pool, read data using multishot recv.
+- `:ssl` - read from an `SSLSocket` object.
+
+The mode is specified as an additional argument to `Stream.new`:
+
+```ruby
+# stream using recv:
+stream = machine.stream(fd, :bp_recv)
+
+# stream on an SSL socket:
+stream = machine.stream(ssl, :ssl)
+```
+
 ## Performance
 
 [Detailed benchmarks](benchmark/README.md)

data/TODO.md

@@ -1,68 +1,10 @@
 ## immediate
 
-- Add support for exception instances in `#timeout`.
-- Add support for returning a value on timeout
-
-  Since to do this safely we need to actually raise an exception that wraps the
-  value, rescue it and return the value, we might want a separate method that
-  wraps `#timeout`:
-
-  ```ruby
-  TimeoutValueError < StandardError
-
-  def timeout_with_value(interval, value, &block)
-    timeout_error = TimeoutValueError
-    timeout(interval, timeout_error, &block)
-  rescue TimeoutValueError => e
-    raise if e != timeout_error
-
-    value
-  end
-  ```
-
 - Add tests for support for Set in `machine#await`
 - Add tests for support for Set, Array in `machine#join`
 - Add `#read_file` for reading entire file
 - Add `#write_file` for writing entire file
 
-- (?) Fix all futex value (Queue, Mutex) to be properly aligned
-
-<<<<<<< HEAD
-=======
-## Buffer rings - automatic management
-
-- Take the buffer_pool branch, rewrite it
-- Allow multiple stream modes:
-  - :buffer_pool - uses buffer rings
-  - :ssl - read from an SSL connection (`SSLSocket`)
-  - :io - read from an `IO`
-
-The API will look something like:
-
-```ruby
-# The mode is selected automatically according to the given target
-
-stream = UM::Stream.new(machine, fd) # buffer_pool mode (read)
-stream = UM::Stream.new(machine, fd, :recv) # buffer_pool mode (recv)
-stream = UM::Stream.new(machine, ssl_sock) # SSLSocket mode
-stream = UM::Stream.new(machine, conn) # IO mode
-stream = UM::Stream.new(machine, str) # string mode
-stream = UM::Stream.new(machine, io_buf) # IO:Buffer mode
-```
-
-This can be very useful in testing of stuff such as protocol implementations:
-
-```ruby
-stream = UM::Stream.new(machine, "GET /foo HTTP/1.1\r\nHost: bar.com\r\n")
-```
-
-So basically the stream is tied to a machine, and that means it can only be used
-on the thread with which the machine is associated. It is not thread-safe. (This
-is incidentally true also for most of the UringMachine instance methods!)
-
-Continued discussion in docs/design/buffer_pool.md
-
->>>>>>> 04d9eb7 (Docs)
 ## Balancing I/O with the runqueue
 
 - in some cases where there are many entries in the runqueue, this can
@@ -90,6 +32,8 @@ Continued discussion in docs/design/buffer_pool.md
   debouncer = machine.debounce { }
   ```
 
+- happy eyeballs algo for TCP connect
+
 - read multiple files
 
   ```ruby
@@ -100,12 +44,31 @@ Continued discussion in docs/design/buffer_pool.md
   machine.read_files(*fns) #=> { fn1:, fn2:, fn3:, ...}
   ```
 
+- more generally, a DSL for expressing batch operations:
+
+  ```ruby
+  result = machine.batch do |b|
+    fns.each { b[it] = read_file(b, it) }
+  end
+  #=> { fn1 => data1, fn2 => data2, ... }
+
+  # we can also imagine performing operations in sequence using linking:
+  result = machine.batch {
+    m.
+  }
+
+  end
+  ```
+
 ## polyvalent select
 
 - select on multiple queues (ala Go)
 - select on mixture of queues and fds
+- select on fibers:
+  - select fibers that are done
+  - select first done fiber
 
-## ops
+## ops still not implemented
 
 - splice / - tee
 - sendto
@@ -124,31 +87,7 @@ Continued discussion in docs/design/buffer_pool.md
 When doing a `call`, we need to provide a mailbox for the response. can this be
 automatic?
 
-## streams
-
-We're still missing:
-
-- limit on line length in `get_line`
-- ability to supply buffer to `get_line` and `get_string`
-- allow read to eof, maybe with `read_to_eof`
-
-For the sake of performance, simplicity and explicitness, we change the API as
-follows:
-
-```ruby
-stream.get_line(buf, limit)
-# the defaults:
-stream.get_line(nil, -1)
-
-stream.get_string(len, buf)
-# defaults:
-stream.get_string(len, nil)
-
-# and
-stream.read_to_eof(buf)
-# defaults:
-stream.read_to_eof(nil)
-```
+##
 
 ## Syntax / pattern for launching/supervising multiple operations
 
@@ -167,6 +106,5 @@ machine.shift_select(*queues) #=> [result, queue]
   ```ruby
   # addrs: [['1.1.1.1', 80], ['2.2.2.2', 80]]
   #        ['1.1.1.1:80', '2.2.2.2:80']
-  tcp_connect_happy_eyeballs(*addrs)
+  tcp_connect_he(*addrs)
   ```
-

data/benchmark/bm_io_ssl.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative './common'
+require 'socket'
+require 'openssl'
+require 'localhost/authority'
+
+GROUPS = 48
+ITERATIONS = 5000
+
+SIZE = 1 << 14
+DATA = '*' * SIZE
+
+class UMBenchmark
+  def server_ctx
+    @server_ctx ||= Localhost::Authority.fetch.server_context
+  end
+
+  def ssl_wrap(sock, ctx)
+    OpenSSL::SSL::SSLSocket.new(sock, ctx).tap { it.sync_close = true }
+  end
+
+  def ssl_socketpair(machine)
+    sock1, sock2 = Socket.socketpair(:AF_UNIX, :SOCK_STREAM, 0)
+    ssl1 = ssl_wrap(sock1, server_ctx)
+    ssl2 = ssl_wrap(sock2, OpenSSL::SSL::SSLContext.new)
+
+    if !machine
+      t = Thread.new { ssl1.accept rescue nil }
+      ssl2.connect
+      t.join
+    else
+      machine.ssl_set_bio(ssl1)
+      machine.ssl_set_bio(ssl2)
+      f = machine.spin { ssl1.accept rescue nil }
+      ssl2.connect
+      machine.join(f)
+    end
+    [ssl1, ssl2]
+  end
+
+  def do_threads(threads, ios)
+    GROUPS.times do
+      r, w = ssl_socketpair(nil)
+      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 = ssl_socketpair(nil)
+      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 = ssl_socketpair(nil)
+      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_scheduler_x(div, scheduler, ios)
+    (GROUPS/div).times do
+      r, w = ssl_socketpair(nil)
+      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 = ssl_socketpair(machine)
+      fibers << machine.spin do
+        ITERATIONS.times { machine.ssl_write(w, DATA, SIZE) }
+        machine.close_async(w)
+      end
+      fibers << machine.spin do
+        ITERATIONS.times { machine.ssl_read(r, +'', SIZE) }
+        machine.close_async(r)
+      end
+    end
+  end
+
+  def do_um_x(div, machine, fibers, fds)
+    (GROUPS/div).times do
+      r, w = ssl_socketpair(machine)
+      fibers << machine.spin do
+        ITERATIONS.times { machine.ssl_write(w, DATA, SIZE) }
+        machine.close_async(w)
+      end
+      fibers << machine.spin do
+        ITERATIONS.times { machine.ssl_read(r, +'', SIZE) }
+        machine.close_async(r)
+      end
+    end
+  end
+end

data/benchmark/bm_redis_client.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative './common'
+require 'securerandom'
+
+C = ENV['C']&.to_i || 50
+I = 10
+puts "C=#{C}"
+
+class UMBenchmark
+  CONTAINER_NAME = "redis-#{SecureRandom.hex}"
+
+  def start_redis_server
+    `docker run --name #{CONTAINER_NAME} -d -p 6379:6379 redis:latest`
+  end
+
+  def stop_redis_server
+    `docker stop #{CONTAINER_NAME}`
+  end
+
+  def create_redis_conn(retries = 0)
+    Redis.new
+  rescue
+    if retries < 3
+      sleep 0.5
+      create_redis_conn(retries + 1)
+    else
+    raise
+    end
+  end
+
+  def query_redis(conn)
+    conn.set('abc', 'def')
+    p conn.get('abc')
+  end
+
+  def with_container
+    start_redis_server
+    sleep 0.5
+    yield
+  rescue Exception => e
+    p e
+    p e.backtrace
+  ensure
+  stop_redis_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_redis_conn
+  #       I.times { query_redis(conn) }
+  #     ensure
+  #       conn.close
+  #     end
+  #   end
+  # end
+
+  def do_scheduler(scheduler, ios)
+    return if !scheduler.is_a?(UM::FiberScheduler)
+    C.times do
+      Fiber.schedule do
+        conn = create_redis_conn
+        I.times { query_redis(conn) }
+      ensure
+        conn.close
+      end
+    end
+  end
+end

data/benchmark/common.rb

@@ -9,6 +9,7 @@ gemfile do
   gem 'io-event'
   gem 'async'
   gem 'pg'
+  gem 'redis'
   gem 'gvltools'
   gem 'openssl'
   gem 'localhost'

data/benchmark/http_parse.rb

@@ -62,7 +62,7 @@ end
 
 require 'stringio'
 
-RE_REQUEST_LINE = /^([a-z]+)\s+([^\s]+)\s+(http\/[0-9\.]{1,3})/i
+RE_REQUEST_LINE = /^([a-z]+)\s+([^\s]+)\s+(http\/1\.1)/i
 RE_HEADER_LINE = /^([a-z0-9\-]+)\:\s+(.+)/i
 
 def get_line(fd, sio, buffer)
@@ -137,7 +137,7 @@ def stream_parse_headers(fd)
   return nil if !headers
 
   while true
-    line = stream.get_line(buf, 0)
+    line = stream.get_line(0)
     break if line.empty?
 
     m = line.match(RE_HEADER_LINE)
@@ -150,7 +150,7 @@ def stream_parse_headers(fd)
 end
 
 def stream_get_request_line(stream, buf)
-  line = stream.get_line(buf, 0)
+  line = stream.get_line(0)
 
   m = line.match(RE_REQUEST_LINE)
   return nil if !m

data/docs/design/buffer_pool.md

@@ -57,7 +57,7 @@ buffers, to using managed buffers from the buffer pool.
 
 - The buffer pool is created and managed automatically. No API is involved.
 -
-- 
+-
 
 - To use the buffer pool, two dedicated APIs are added:
 

data/ext/um/um.c

@@ -1285,6 +1285,57 @@ VALUE um_statx(struct um *machine, int dirfd, VALUE path, int flags, unsigned in
   return statx_to_hash(&stat);
 }
 
+VALUE um_splice(struct um *machine, int in_fd, int out_fd, uint nbytes) {
+  struct um_op *op = um_op_acquire(machine);
+  um_prep_op(machine, op, OP_SPLICE, 2, 0);
+  struct io_uring_sqe *sqe = um_get_sqe(machine, op);
+  io_uring_prep_splice(sqe, in_fd, -1, out_fd, -1, nbytes, 0);
+
+  VALUE ret = um_yield(machine);
+
+  if (likely(um_verify_op_completion(machine, op, false))) ret = INT2NUM(op->result.res);
+  um_op_release(machine, op);
+
+  RAISE_IF_EXCEPTION(ret);
+  RB_GC_GUARD(ret);
+
+  return ret;
+}
+
+VALUE um_tee(struct um *machine, int in_fd, int out_fd, uint nbytes) {
+  struct um_op *op = um_op_acquire(machine);
+  um_prep_op(machine, op, OP_TEE, 2, 0);
+  struct io_uring_sqe *sqe = um_get_sqe(machine, op);
+  io_uring_prep_tee(sqe, in_fd, out_fd, nbytes, 0);
+
+  VALUE ret = um_yield(machine);
+
+  if (likely(um_verify_op_completion(machine, op, false))) ret = INT2NUM(op->result.res);
+  um_op_release(machine, op);
+
+  RAISE_IF_EXCEPTION(ret);
+  RB_GC_GUARD(ret);
+
+  return ret;
+}
+
+VALUE um_fsync(struct um *machine, int fd) {
+  struct um_op *op = um_op_acquire(machine);
+  um_prep_op(machine, op, OP_FSYNC, 2, 0);
+  struct io_uring_sqe *sqe = um_get_sqe(machine, op);
+  io_uring_prep_fsync(sqe, fd, 0);
+
+  VALUE ret = um_yield(machine);
+
+  if (likely(um_verify_op_completion(machine, op, false))) ret = INT2NUM(op->result.res);
+  um_op_release(machine, op);
+
+  RAISE_IF_EXCEPTION(ret);
+  RB_GC_GUARD(ret);
+
+  return ret;
+}
+
 /*******************************************************************************
                             multishot ops
 *******************************************************************************/