uringmachine 0.30.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a97099f1d89b2333b8be056c91acabad63fad122ce4c802a666e4abb10aca93b
-  data.tar.gz: '095878ee7df374be5dc87b74ea636b3def2b611006c76c7d86ae7c00ad064f47'
+  metadata.gz: 299bd9cc7810b3d67352cf1c35e1bad8228d26dc1495d2e03e8283299347836a
+  data.tar.gz: 1241fd5922a26d0223a6d345984e7548bb4486160a5f7f70cb25f4356cde4736
 SHA512:
-  metadata.gz: 339349fd4116011334517f124201a1cf425762c1bafe33ba61fa3eaf175fa5064512f780f8354f8fc317515bab6c4914cb41fba2022d23c17aac7e08d18cad7b
-  data.tar.gz: 02c7b30e4143f07382f2788a9f242e6f051f57b438fc3ecc63153a13f318bbbab69e5239add2af31e277c68b21483be60bd542863c8f7aa358d7fa1b0c0793e9
+  metadata.gz: 0075bd142ba474e475eb53fca3eb8e88bbb5fdba8214d7832b34582f3089e2720e99e069f49d7244b2c2cd9f5536ca5113589b9a5658d3f3679e3d6352043e1d
+  data.tar.gz: fe68ab2c66601a0aa5786e86b86173b5c6b94a1f58d0a7151546c4c596b1d625912ebd32670c8230ab301886f3a6a0a35edff1cd7a472f5253cb181e0156a1f7

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+# 0.32.0 2026-04-03
+
+- Rename `UM::Connection` to `UM::IO`
+
+# 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`
@@ -30,7 +42,7 @@
 
 # 0.28.2 2026-02-20
 
-- Fix `Stream#get_string`
+- Fix `Stream#read`
 
 # 0.28.1 2026-02-20
 
@@ -169,9 +181,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.
+- [IO](#io-api) class with automatic buffer management for reading.
 - Optimized I/O for encrypted SSL connections.
 
 ## Design
@@ -286,64 +286,69 @@ fiber = Fiber.schedule do
 end
 ```
 
-## Read Streams
+## IO API
 
-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::IO` is a class designed for efficiently read from and write to a
+socket or other file descriptor. The IO class is ideal for implementing
+line-based 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
+An IO is associated with a UringMachine instance and a target file descriptor
+(or SSL socket, see also [IO modes](#io-modes) below). Behind the scenes, the IO
+class takes advantage of io_uring's provided 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 IO instances 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 an IO for a given fd, use `UM#io`:
 
 ```ruby
-stream = machine.stream(fd)
+io = machine.io(fd)
 
-# you can also provide a block that will be passed the stream instance:
-machine.stream(fd) { |s| do_something_with(s) }
+# you can provide a block that will be passed the IO instance:
+machine.io(fd) { |io| do_something_with(io) }
 
-# you can also instantiate a stream directly:
-stream = UM::Stream.new(machine, fd)
+# you can also instantiate an IO directly:
+io = UM::IO.new(machine, fd)
 ```
 
-The following API is used to interact with the stream:
+The following API is used to interact with an IO:
 
 ```ruby
 # Read until a newline character is encountered:
-line = stream.get_line(0)
+line = io.read_line(0)
 
 # Read line with a maximum length of 13 bytes:
-line = stream.get_line(13)
+line = io.read_line(13)
 
 # Read all data:
-buf = stream.get_string(0)
+buf = io.read(0)
 
 # Read exactly 13 bytes:
-buf = stream.get_string(13)
+buf = io.read(13)
 
 # Read up to 13 bytes:
-buf = stream.get_string(-13)
+buf = io.read(-13)
+
+# Read continuously until EOF
+io.read_each { |data| ... }
 
 # Skip 3 bytes:
-stream.skip(3)
+io.skip(3)
+
+# Write
+io.write('foo', 'bar', 'baz')
 ```
 
 Here's an example of a how a basic HTTP request parser might be implemented
-using a stream:
+using a `UM::IO`:
 
 ```ruby
-def parse_http_request_headers(stream)
-  request_line = stream.get_line(0)
+def parse_http_request_headers(io)
+  request_line = io.read_line(0)
   m = request_line.match(REQUEST_LINE_RE)
   return nil if !m
 
@@ -354,7 +359,7 @@ def parse_http_request_headers(stream)
   }
 
   while true
-    line = stream.get_line(0)
+    line = io.read_line(0)
     break if !line || line.empty?
 
     m = line.match(HEADER_RE)
@@ -364,24 +369,26 @@ def parse_http_request_headers(stream)
 end
 ```
 
-### Stream modes
+### IO modes
 
-Stream modes allow streams to be transport agnostic. Currently streams support
-three modes:
+IO modes allow IOs to be transport agnostic. The following modes are currently
+supported:
 
-- `: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 `IO.new`:
 
 ```ruby
-# stream using recv:
-stream = machine.stream(fd, :bp_recv)
+# using recv/send:
+io = machine.io(fd, :socket)
 
-# stream on an SSL socket:
-stream = machine.stream(ssl, :ssl)
+# SSL I/O:
+io = machine.io(ssl, :ssl)
+# or simply:
+io = machine.io(ssl)
 ```
 
 ## Performance

data/TODO.md

@@ -1,9 +1,28 @@
+- Rename Connection to IO
+
+  ```ruby
+  io = machine.io(fd)
+  l = io.read_line(4)
+  io.write('foo')
+  ```
+
+- Add `IO#fd`/`IO#target` method
+
+- Add `UM#inspect` (show size, modes)
+- Add `UM::IO#inspect` (show target, mode, pending bytes)
+
+## Reimplement multishot read/recv using buffer pool
+
+- remove `#setup_buffer_ring` method
+- use buffer pool, just like UM::Connection
+
 ## immediate
 
 - 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`
 
 ## Balancing I/O with the runqueue
 
@@ -70,11 +89,9 @@
 
 ## ops still not implemented
 
-- splice / - tee
 - sendto
 - recvfrom
 - poll_multishot
-- fsync
 - mkdir / mkdirat
 - link / linkat / unlink / unlinkat / symlink
 - rename / renameat

data/benchmark/bm_io_pipe.rb

@@ -2,8 +2,8 @@
 
 require_relative './common'
 
-GROUPS = 48
-ITERATIONS = 10000
+GROUPS = ENV['C']&.to_i || 48
+ITERATIONS = ENV['I']&.to_i || 10000
 
 SIZE = 1024
 DATA = '*' * SIZE

data/benchmark/common.rb

@@ -62,35 +62,35 @@ class UMBenchmark
     # baseline_um:  [:baseline_um,  "UM no concurrency"],
     # thread_pool:  [:thread_pool,  "ThreadPool"],
 
-    threads:        [:threads,      "Threads"],
+    # threads:        [:threads,      "Threads"],
 
-    async_uring:    [:scheduler,    "Async uring"],
-    async_uring_x2: [:scheduler_x,  "Async uring x2"],
+    # 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_fs:          [:scheduler,    "UM FS"],
+    # um_fs_x2:       [:scheduler_x,  "UM FS x2"],
 
-    um:             [:um,           "UM"],
-    um_sidecar:     [:um,           "UM sidecar"],
+    # 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"],
+    # 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)|
       if respond_to?(:"do_#{doer}")
-        STDOUT << "Running #{name}... "
-        ts = nil
+        # STDOUT << "Running #{name}... "
+        # ts = nil
         b.report(name) {
-          ts = measure_time { send(:"run_#{sym}") }
+          # ts = measure_time { send(:"run_#{sym}") }
+          send(:"run_#{sym}")
         }
-        p ts
         cleanup
       end
     end
@@ -197,7 +197,7 @@ class UMBenchmark
   end
 
   def run_um
-    machine = UM.new
+    machine = UM.new(size: 16384)
     fibers = []
     fds = []
     do_um(machine, fibers, fds)
@@ -226,7 +226,7 @@ class UMBenchmark
   def run_um_x2
     threads  = 2.times.map do
       Thread.new do
-        machine = UM.new
+        machine = UM.new(size: 16384)
         fibers = []
         fds = []
         do_um_x(2, machine, fibers, fds)
@@ -240,7 +240,7 @@ class UMBenchmark
   def run_um_x4
     threads  = 4.times.map do
       Thread.new do
-        machine = UM.new
+        machine = UM.new(size: 16384)
         fibers = []
         fds = []
         do_um_x(4, machine, fibers, fds)

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_io = @machine.open('/dev/random', UM::O_RDONLY)
+@io = UM::IO.new(@machine, @fd_io)
+def um_io_read_line
+  @io².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('UM::IO')      { um_io_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_io = 0
+def um_io_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 }
+  io = UM::IO.new(@machine, fd)
+  N.times { @total_io += io.read_line(0)&.bytesize || 0 }
 rescue => e
   p e
   p e.backtrace
 ensure
-  stream.clear
+  io.clear
   @machine.close(fd)
 end
 
-def um_stream
+def um_io
   start_server
   ff = C.times.map {
     @machine.snooze
-    @machine.spin { um_stream_do }
+    @machine.spin { um_io_do }
   }
   @machine.await(ff)
-  pp total: @total_stream
+  pp total: @total_io
 ensure
   stop_server
 end
 
 p(C:, N:)
-um_stream
+um_io
 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('Thread/IO#gets')     { io_gets }
+  it.report('Fiber/UM#read+buf')  { um_read }
+  it.report('Fiber/UM::IO')       { um_io }
 end

data/benchmark/http_parse.rb

@@ -65,7 +65,7 @@ require 'stringio'
 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)
+def read_line(fd, sio, buffer)
   while true
     line = sio.gets(chomp: true)
     return line if line
@@ -76,7 +76,7 @@ def get_line(fd, sio, buffer)
 end
 
 def get_request_line(fd, sio, buffer)
-  line = get_line(fd, sio, buffer)
+  line = read_line(fd, sio, buffer)
 
   m = line.match(RE_REQUEST_LINE)
   return nil if !m
@@ -96,7 +96,7 @@ def parse_headers(fd)
   return nil if !headers
 
   while true
-    line = get_line(fd, sio, buffer)
+    line = read_line(fd, sio, buffer)
     break if line.empty?
 
     m = line.match(RE_HEADER_LINE)
@@ -129,15 +129,15 @@ ensure
   ($machine.close(wfd) rescue nil) if wfd
 end
 
-def stream_parse_headers(fd)
-  stream = UM::Stream.new($machine, fd)
+def io_parse_headers(fd)
+  io = UM::IO.new($machine, fd)
 
   buf = String.new(capacity: 65536)
-  headers = stream_get_request_line(stream, buf)
+  headers = io_get_request_line(io, buf)
   return nil if !headers
 
   while true
-    line = stream.get_line(0)
+    line = io.read_line(0)
     break if line.empty?
 
     m = line.match(RE_HEADER_LINE)
@@ -149,8 +149,8 @@ def stream_parse_headers(fd)
   headers
 end
 
-def stream_get_request_line(stream, buf)
-  line = stream.get_line(0)
+def io_get_request_line(io, buf)
+  line = io.read_line(0)
 
   m = line.match(RE_REQUEST_LINE)
   return nil if !m
@@ -162,12 +162,12 @@ def stream_get_request_line(stream, buf)
   }
 end
 
-def parse_http_stream
+def parse_http_io
   rfd, wfd = UM.pipe
   queue = UM::Queue.new
 
   $machine.spin do
-    headers = stream_parse_headers(rfd)
+    headers = io_parse_headers(rfd)
     $machine.push(queue, headers)
   rescue Exception => e
     p e
@@ -188,7 +188,7 @@ def compare_allocs
   p(
     alloc_http_parser:  alloc_count { x.times { parse_http_parser } },
     alloc_stringio:     alloc_count { x.times { parse_http_stringio } },
-    alloc_stream:       alloc_count { x.times { parse_http_stream } }
+    alloc_io:           alloc_count { x.times { parse_http_io } }
   )
 ensure
   GC.enable
@@ -213,8 +213,8 @@ def benchmark
     x.config(:time => 5, :warmup => 3)
 
     x.report("http_parser") { parse_http_parser }
-    x.report("stringio") { parse_http_stringio }
-    x.report("stream") { parse_http_stream }
+    x.report("StringIO")    { parse_http_stringio }
+    x.report("UM::IO")      { parse_http_io }
 
     x.compare!
   end

data/benchmark/http_server_accept_queue.rb

@@ -12,8 +12,8 @@ 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)
+def io_get_request_line(io, buf)
+  line = io.read_line(0)
   m = line&.match(RE_REQUEST_LINE)
   return nil if !m
 
@@ -26,12 +26,12 @@ end
 
 class InvalidHeadersError < StandardError; end
 
-def get_headers(stream, buf)
-  headers = stream_get_request_line(stream, buf)
+def get_headers(io, buf)
+  headers = io_get_request_line(io, buf)
   return nil if !headers
 
   while true
-    line = stream.get_line(buf, 0)
+    line = io.read_line(0)
     break if line.empty?
 
     m = line.match(RE_HEADER_LINE)
@@ -51,17 +51,21 @@ def send_response(machine, fd)
 end
 
 def handle_connection(machine, fd)
-  stream = UM::Stream.new(machine, fd)
+  io = UM::IO.new(machine, fd)
   buf = String.new(capacity: 65536)
 
   while true
-    headers = get_headers(stream, buf)
+    headers = get_headers(io, buf)
     break if !headers
 
     send_response(machine, fd)
   end
 rescue InvalidHeadersError, SystemCallError => e
   # ignore
+rescue => e
+  p e
+  p e.backtrace
+  exit!
 ensure
   machine.close_async(fd)
 end

data/benchmark/http_server_multi_accept.rb

@@ -12,8 +12,8 @@ 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)
+def io_get_request_line(io, buf)
+  line = io.read_line(0)
   m = line&.match(RE_REQUEST_LINE)
   return nil if !m
 
@@ -26,12 +26,12 @@ end
 
 class InvalidHeadersError < StandardError; end
 
-def get_headers(stream, buf)
-  headers = stream_get_request_line(stream, buf)
+def get_headers(io, buf)
+  headers = io_get_request_line(io, buf)
   return nil if !headers
 
   while true
-    line = stream.get_line(buf, 0)
+    line = io.read_line(0)
     break if line.empty?
 
     m = line.match(RE_HEADER_LINE)
@@ -51,11 +51,11 @@ def send_response(machine, fd)
 end
 
 def handle_connection(machine, fd)
-  stream = UM::Stream.new(machine, fd)
+  io = UM::IO.new(machine, fd)
   buf = String.new(capacity: 65536)
 
   while true
-    headers = get_headers(stream, buf)
+    headers = get_headers(io, buf)
     break if !headers
 
     send_response(machine, fd)

data/benchmark/http_server_multi_ractor.rb

@@ -12,8 +12,8 @@ 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)
+def io_get_request_line(io, buf)
+  line = io.read_line(0)
   m = line&.match(RE_REQUEST_LINE)
   return nil if !m
 
@@ -26,12 +26,12 @@ end
 
 class InvalidHeadersError < StandardError; end
 
-def get_headers(stream, buf)
-  headers = stream_get_request_line(stream, buf)
+def get_headers(io, buf)
+  headers = io_get_request_line(io, buf)
   return nil if !headers
 
   while true
-    line = stream.get_line(buf, 0)
+    line = io.read_line(0)
     break if line.empty?
 
     m = line.match(RE_HEADER_LINE)
@@ -53,11 +53,11 @@ end
 
 def handle_connection(machine, fd)
   machine.setsockopt(fd, UM::IPPROTO_TCP, UM::TCP_NODELAY, true)
-  stream = UM::Stream.new(machine, fd)
+  io = UM::IO.new(machine, fd)
   buf = String.new(capacity: 65536)
 
   while true
-    headers = get_headers(stream, buf)
+    headers = get_headers(io, buf)
     break if !headers
 
     send_response(machine, fd)

data/benchmark/http_server_single_thread.rb

@@ -12,8 +12,8 @@ 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)
+def io_get_request_line(io, buf)
+  line = io.read_line(0)
   m = line&.match(RE_REQUEST_LINE)
   return nil if !m
 
@@ -26,12 +26,12 @@ end
 
 class InvalidHeadersError < StandardError; end
 
-def get_headers(stream, buf)
-  headers = stream_get_request_line(stream, buf)
+def get_headers(io, buf)
+  headers = io_get_request_line(io, buf)
   return nil if !headers
 
   while true
-    line = stream.get_line(buf, 0)
+    line =  io.read_line(0)
     break if line.empty?
 
     m = line.match(RE_HEADER_LINE)
@@ -52,11 +52,11 @@ end
 
 def handle_connection(machine, fd)
   machine.setsockopt(fd, UM::IPPROTO_TCP, UM::TCP_NODELAY, true)
-  stream = UM::Stream.new(machine, fd)
+  io = UM::IO.new(machine, fd)
   buf = String.new(capacity: 65536)
 
   while true
-    headers = get_headers(stream, buf)
+    headers = get_headers(io, buf)
     break if !headers
 
     send_response(machine, fd)
@@ -77,4 +77,4 @@ machine.bind(fd, '127.0.0.1', PORT)
 machine.listen(fd, 128)
 
 puts "Listening on localhost:#{PORT}"
-machine.accept_each(fd) { |conn| machine.spin { handle_connection(machine, conn) } }
+machine.accept_each(fd) { | io| machine.spin { handle_connection(machine,  io) } }