uringmachine 0.29.2 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6151ac8411facd0ef37fa66a7cae623d2137f335bbe1e178529cb0a76c9f56c3
-  data.tar.gz: 5918fde9ea4ba936760a3d402207bd6fd5806337b005cd3633ab1cf0f8584ed0
+  metadata.gz: 9c6af55ee77291dcf17471dde7dd9d68b731fd9a8dea4d1dccdcc09b325b9163
+  data.tar.gz: 516624d1a86287bbd0978d5aaf0cca540063ca7f6aa4cf2bab8cb9f23214d32d
 SHA512:
-  metadata.gz: 0d77a7f37251930db32ec8023b1cb60e5595348544b279b175d39a528dbe782a703c75f6ebde5b2dd84379ec12ae83decf47f11f0b692e4975a36f146b4bc975
-  data.tar.gz: 190d3d88d32f91241c3c9ed3fc674d5318fcf630e64d5d5fdecdc7a86b6e62f03786190a021f4828e6a40022ccbf301a3cffdf0311ff35bc747889d9f00fbb9b
+  metadata.gz: e9d845525499342080228b44afb5cabb84af6bb0cb14081cc5e4e2eb627ab638312c0df818f5d109ab99d6e34a299bb21da23711f131f4a9641d688cee5cf35e
+  data.tar.gz: d67d15b398bac118b85219be3669a1479eba68e5d93ceb2e3f598238ae2fbefd7cf83dcffa132fe12ed0b0385d675c15e7f89a05150290da6fbc4d8bc40a1431

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+# 0.31.0 2026-03-31
+
+- Rework `Stream` into `Connection` class:
+  - Rename modes, improve SSL detection
+  - Rename and enhance different read methods
+  - Add `#write` method
+  - Add `#resp_write` method
+
+# 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`
@@ -24,7 +38,7 @@
 
 # 0.28.2 2026-02-20
 
-- Fix `Stream#get_string`
+- Fix `Stream#read`
 
 # 0.28.1 2026-02-20
 
@@ -163,9 +177,9 @@
 
 # 2025-06-03 Version 0.12
 
-- Add buffer, maxlen params to `Stream#get_line`
-- Add buffer param to `Stream#get_string`
-- Remove `Stream#resp_get_line`, `Stream#resp_get_string` methods
+- Add buffer, maxlen params to `Stream#read_line`
+- Add buffer param to `Stream#read`
+- Remove `Stream#resp_read_line`, `Stream#resp_read` methods
 
 # 2025-06-02 Version 0.11.1
 

data/README.md

@@ -37,7 +37,7 @@ implementation that allows integration with the entire Ruby ecosystem.
 - 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.
+- [Connection](#connections) class with automatic buffer management for reading.
 - Optimized I/O for encrypted SSL connections.
 
 ## Design
@@ -286,64 +286,70 @@ fiber = Fiber.schedule do
 end
 ```
 
-## Read Streams
+## Connections
 
-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.
+`UringMachine::Connection` is a class designed for efficiently read from and
+write to a socket or other file descriptor. Connections 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
+A connection is associated with a UringMachine instance and a target file
+descriptor (or SSL socket, see also [connection modes](#connection-modes)
+below). Behind the scenes, connections 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
+When connections 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`:
+To create a connection for a given fd, use `UM#connection`:
 
 ```ruby
-stream = machine.stream(fd)
+conn = machine.connection(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 provide a block that will be passed the connection instance:
+machine.connection(fd) { |c| do_something_with(c) }
 
-# you can also instantiate a stream directly:
-stream = UM::Stream.new(machine, fd)
+# you can also instantiate a connection directly:
+conn = UM::Connection.new(machine, fd)
 ```
 
-The following API is used to interact with the stream:
+The following API is used to interact with the connection:
 
 ```ruby
 # Read until a newline character is encountered:
-line = stream.get_line(0)
+line = conn.read_line(0)
 
 # Read line with a maximum length of 13 bytes:
-line = stream.get_line(13)
+line = conn.read_line(13)
 
 # Read all data:
-buf = stream.get_string(0)
+buf = conn.read(0)
 
 # Read exactly 13 bytes:
-buf = stream.get_string(13)
+buf = conn.read(13)
 
 # Read up to 13 bytes:
-buf = stream.get_string(-13)
+buf = conn.read(-13)
+
+# Read continuously until EOF
+conn.read_each { |data| ... }
 
 # Skip 3 bytes:
-stream.skip(3)
+conn.skip(3)
+
+# Write
+conn.write('foo', 'bar', 'baz')
 ```
 
 Here's an example of a how a basic HTTP request parser might be implemented
-using a stream:
+using a connection:
 
 ```ruby
-def parse_http_request_headers(stream)
-  request_line = stream.get_line(0)
+def parse_http_request_headers(conn)
+  request_line = conn.read_line(0)
   m = request_line.match(REQUEST_LINE_RE)
   return nil if !m
 
@@ -354,7 +360,7 @@ def parse_http_request_headers(stream)
   }
 
   while true
-    line = stream.get_line(0)
+    line = conn.read_line(0)
     break if !line || line.empty?
 
     m = line.match(HEADER_RE)
@@ -364,24 +370,26 @@ def parse_http_request_headers(stream)
 end
 ```
 
-### Stream modes
+### Connection modes
 
-Stream modes allow streams to be transport agnostic. Currently streams support
-three modes:
+Connection modes allow connections to be transport agnostic. Currently
+connections support three modes:
 
-- `:bp_read` - use the buffer pool, read data using multishot read
+- `:fd` - 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.
+- `:socket` - 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`:
+The mode is specified as an additional argument to `Connection.new`:
 
 ```ruby
-# stream using recv:
-stream = machine.stream(fd, :bp_recv)
+# using recv/send:
+conn = machine.connection(fd, :socket)
 
-# stream on an SSL socket:
-stream = machine.stream(ssl, :ssl)
+# SSL I/O:
+conn = machine.connection(ssl, :ssl)
+# or simply:
+conn = machine.connection(ssl)
 ```
 
 ## Performance

data/TODO.md

@@ -1,67 +1,64 @@
 ## immediate
 
-- 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
+- Add `UM#read_file` for reading entire file
+- Add `UM#write_file` for writing entire file
+- Rename stream methods: `:fd`, `:socket`, `:ssl`
 
-- (?) Fix all futex value (Queue, Mutex) to be properly aligned
+## Improving streams
 
-<<<<<<< HEAD
-=======
-## Buffer rings - automatic management
+One wart of the stream API is that it's only for reading, so if we want to
+implement a protocol where we read and write to a target fd, we also need to
+keep the fd around or call `stream.target` every time we want to write to it,
+*and* we don't have a transport-agnostic write op.
 
-- 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:
+What if instead of `Stream` we had something called `Link`, which serves for
+both reading and writing:
 
 ```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
+conn = machine.connection(fd)
+while l = conn.read_line
+  conn.write(l, '\n')
+end
+# or:
+buf = conn.read(42)
 ```
 
-This can be very useful in testing of stuff such as protocol implementations:
+RESP:
 
 ```ruby
-stream = UM::Stream.new(machine, "GET /foo HTTP/1.1\r\nHost: bar.com\r\n")
+conn.resp_write(['foo', 'bar'])
+reply = conn.resp_read
 ```
 
-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!)
+HTTP:
+
+```ruby
+r = conn.http_read_request
+conn.http_write_response({ ':status' => 200 }, 'foo')
 
-Continued discussion in docs/design/buffer_pool.md
+# or:
+conn.http_write_request({ ':method' => 'GET', ':path' => '/foo' }, nil)
+```
+
+Plan of action:
+
+- Rename methods:
+  - [v] rename `#read_line` to `#read_line`
+  - [v] rename `#read` to `#read`
+  - [v] rename `#read_to_delim` to `#read_to_delim`
+  - [v] rename `#each` to `#read_each`
+  - [v] rename `#resp_decode` to `#resp_read`
+- Rename modes:
+  - [v] :fd to :fd
+  - [v] :socket to :socket
+  - [v] auto detect SSL
+- Rename `Stream` to `Connection`
+- Add methods:
+  - `#write(*bufs)`
+  - `#resp_write(obj)`
 
->>>>>>> 04d9eb7 (Docs)
 ## Balancing I/O with the runqueue
 
 - in some cases where there are many entries in the runqueue, this can
@@ -89,6 +86,8 @@ Continued discussion in docs/design/buffer_pool.md
   debouncer = machine.debounce { }
   ```
 
+- happy eyeballs algo for TCP connect
+
 - read multiple files
 
   ```ruby
@@ -99,12 +98,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
@@ -123,31 +141,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
 
@@ -166,6 +160,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/gets.rb

@@ -34,16 +34,16 @@ def um_read
   end
 end
 
-@fd_stream = @machine.open('/dev/random', UM::O_RDONLY)
-@stream = UM::Stream.new(@machine, @fd_stream)
-def um_stream_get_line
-  @stream.get_line(0)
+@fd_connection = @machine.open('/dev/random', UM::O_RDONLY)
+@conn = UM::Connection.new(@machine, @fd_connection)
+def um_connection_read_line
+  @conn.read_line(0)
 end
 
 Benchmark.ips do |x|
-  x.report('IO#gets')     { io_gets }
-  x.report('UM#read+buf') { um_read }
-  x.report('UM::Stream')  { um_stream_get_line }
+  x.report('IO#gets')         { io_gets }
+  x.report('UM#read+buf')     { um_read }
+  x.report('UM::Connection')  { um_connection_read_line }
 
   x.compare!(order: :baseline)
 end

data/benchmark/gets_concurrent.rb

@@ -83,40 +83,40 @@ ensure
   stop_server
 end
 
-@total_stream = 0
-def um_stream_do
+@total_connection = 0
+def um_connection_do
   # fd = @machine.open('/dev/random', UM::O_RDONLY)
   fd = @machine.socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
   @machine.connect(fd, '127.0.0.1', 1234)
-  stream = UM::Stream.new(@machine, fd)
-  N.times { @total_stream += stream.get_line(0)&.bytesize || 0 }
+  conn = UM::Connection.new(@machine, fd)
+  N.times { @total_connection += conn.read_line(0)&.bytesize || 0 }
 rescue => e
   p e
   p e.backtrace
 ensure
-  stream.clear
+  conn.clear
   @machine.close(fd)
 end
 
-def um_stream
+def um_connection
   start_server
   ff = C.times.map {
     @machine.snooze
-    @machine.spin { um_stream_do }
+    @machine.spin { um_connection_do }
   }
   @machine.await(ff)
-  pp total: @total_stream
+  pp total: @total_connection
 ensure
   stop_server
 end
 
 p(C:, N:)
-um_stream
+um_connection
 pp @machine.metrics
 exit
 
 Benchmark.bm do
   it.report('Thread/IO#gets')    { io_gets }
   it.report('Fiber/UM#read+buf') { um_read }
-  it.report('Fiber/UM::Stream')  { um_stream }
+  it.report('Fiber/UM::Stream')  { um_connection }
 end