uringmachine 0.29.0 → 0.29.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a6a6d78b632e43c1ac15e8745ede898e531ff9a731822fd22c5991ca0222d69
-  data.tar.gz: 0acd35ee028ea519c2788c720336dbcb1c2fa8317912459b7a81f4afbe6b3747
+  metadata.gz: 6151ac8411facd0ef37fa66a7cae623d2137f335bbe1e178529cb0a76c9f56c3
+  data.tar.gz: 5918fde9ea4ba936760a3d402207bd6fd5806337b005cd3633ab1cf0f8584ed0
 SHA512:
-  metadata.gz: ed9f7684132ee1e1aae9c7783131fd927e88604444d44bc889cdf8c362b0a5dd85b3e887873c0512946af2c08dd8189e6c3bf972f19f90a7f12daee4c44c5ccd
-  data.tar.gz: f5bff069de535e906543a679266700bacbb715d0e72b14d4bf7cd042ab8d77e58d8c69feb1dbd65f16026aa4bcec20d024acffd2e2f18ac255f5b70190c25788
+  metadata.gz: 0d77a7f37251930db32ec8023b1cb60e5595348544b279b175d39a528dbe782a703c75f6ebde5b2dd84379ec12ae83decf47f11f0b692e4975a36f146b4bc975
+  data.tar.gz: 190d3d88d32f91241c3c9ed3fc674d5318fcf630e64d5d5fdecdc7a86b6e62f03786190a021f4828e6a40022ccbf301a3cffdf0311ff35bc747889d9f00fbb9b

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+# 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`
+- Improve buffer commit level handling
+
 # 0.29.0 2026-03-11
 
 - Reimplement streams based on buffer pool

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,6 +1,5 @@
 ## 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

data/benchmark/gets_concurrent.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'uringmachine', path: '..'
+  gem 'benchmark'
+end
+
+require 'benchmark'
+require 'uringmachine'
+
+C = 10
+N = 1000
+
+CMD = <<~EOF
+  bash -c "for i in {1..#{C*2}}; do nc -l -p 1234 </dev/random & done; wait $(jobs -p)"
+EOF
+
+def start_server
+  @pid = fork {
+    p :server_launch
+    `#{CMD}`
+    puts
+    p :server_done
+    puts
+  }
+  sleep(0.5)
+end
+
+def stop_server
+  Process.kill('SIGINT', @pid)
+  Process.wait(@pid)
+end
+
+def io_gets
+  start_server
+  tt = C.times.map {
+    Thread.new do
+      s = TCPSocket.new('localhost', 1234)
+      # io = File.open('/dev/random', 'r')
+      N.times { s.gets }
+    ensure
+      s.close
+    end
+  }
+  tt.each(&:join)
+ensure
+  stop_server
+end
+
+@machine = UM.new
+
+def buf_gets(fd, buffer)
+  while true
+    idx = buffer.byteindex("\n")
+    if idx
+      line = buffer[0..(idx - 1)]
+
+      buffer = buffer[(idx + 1)..-1]
+      return line
+    end
+    @machine.read(fd, buffer, 65536, -1)
+  end
+end
+
+def um_read
+  start_server
+  ff = C.times.map {
+    @machine.spin 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)
+      buffer = +''.encode(Encoding::US_ASCII)
+      N.times { buf_gets(fd, buffer) }
+    ensure
+      @machine.close(fd)
+    end
+  }
+  @machine.await(ff)
+ensure
+  stop_server
+end
+
+@total_stream = 0
+def um_stream_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 }
+rescue => e
+  p e
+  p e.backtrace
+ensure
+  stream.clear
+  @machine.close(fd)
+end
+
+def um_stream
+  start_server
+  ff = C.times.map {
+    @machine.snooze
+    @machine.spin { um_stream_do }
+  }
+  @machine.await(ff)
+  pp total: @total_stream
+ensure
+  stop_server
+end
+
+p(C:, N:)
+um_stream
+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 }
+end

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

@@ -540,15 +540,19 @@ VALUE um_timeout_complete(VALUE arg) {
   return Qnil;
 }
 
-VALUE um_timeout(struct um *machine, VALUE interval, VALUE class) {
+VALUE um_timeout(struct um *machine, VALUE interval, VALUE obj) {
   static ID ID_new = 0;
-  if (unlikely(!ID_new)) ID_new = rb_intern("new");
+
+  if (TYPE(obj) == T_CLASS) {
+    if (unlikely(!ID_new)) ID_new = rb_intern("new");
+    obj = rb_funcall(obj, ID_new, 0);
+  }
 
   struct um_op *op = um_op_acquire(machine);
   um_prep_op(machine, op, OP_TIMEOUT, 2, 0);
   op->ts = um_double_to_timespec(NUM2DBL(interval));
   RB_OBJ_WRITE(machine->self, &op->fiber, rb_fiber_current());
-  RB_OBJ_WRITE(machine->self, &op->value, rb_funcall(class, ID_new, 0));
+  RB_OBJ_WRITE(machine->self, &op->value, obj);
   RB_OBJ_WRITE(machine->self, &op->async_op, Qnil);
 
   struct io_uring_sqe *sqe = um_get_sqe(machine, op);
@@ -556,6 +560,7 @@ VALUE um_timeout(struct um *machine, VALUE interval, VALUE class) {
 
   struct op_ctx ctx = { .machine = machine, .op = op };
   return rb_ensure(rb_yield, Qnil, um_timeout_complete, (VALUE)&ctx);
+  RB_GC_GUARD(obj);
 }
 
 /*******************************************************************************

data/ext/um/um.h

@@ -111,12 +111,10 @@ enum um_stream_mode {
 
 #define BP_BGID                     0xF00B
 #define BP_BR_ENTRIES               1024
-
 #define BP_INITIAL_BUFFER_SIZE      (1U << 14) // 16KB
-#define BP_INITIAL_COMMIT_THRESHOLD (1U << 16) // 64KB
+#define BP_INITIAL_COMMIT_LEVEL     (BP_INITIAL_BUFFER_SIZE * 16) // 256KB
 #define BP_MAX_BUFFER_SIZE          (1U << 20) // 1MB
-
-#define BP_MAX_COMMIT_THRESHOLD     (BP_MAX_BUFFER_SIZE * BP_BR_ENTRIES) // 1GB
+#define BP_MAX_COMMIT_LEVEL         (BP_MAX_BUFFER_SIZE * BP_BR_ENTRIES) // 1GB
 #define BP_AVAIL_BID_BITMAP_WORDS   (BP_BR_ENTRIES / 64)
 
 struct um_buffer {
@@ -163,7 +161,7 @@ struct um_op {
     struct iovec *iovecs; // used for vectorized write/send
     siginfo_t siginfo; // used for waitid
     int int_value; // used for getsockopt
-    size_t bp_commit_threshold; // buffer pool commit threshold
+    size_t bp_commit_level; // buffer pool commit threshold
   };
 };
 
@@ -234,7 +232,7 @@ struct um {
 
   struct io_uring_buf_ring *bp_br;
   size_t bp_buffer_size;
-  size_t bp_commit_threshold;
+  size_t bp_commit_level;
   struct um_buffer **bp_commited_buffers;
   uint64_t bp_avail_bid_bitmap[BP_AVAIL_BID_BITMAP_WORDS];
 
@@ -285,7 +283,8 @@ struct um_stream {
   struct um_op *op;
   struct um_segment *head;
   struct um_segment *tail;
-  size_t pending_len;
+  size_t consumed_bytes;
+  size_t pending_bytes;
   size_t pos;
   int eof;
 };
@@ -437,7 +436,7 @@ void stream_teardown(struct um_stream *stream);
 void stream_clear(struct um_stream *stream);
 VALUE stream_get_line(struct um_stream *stream, VALUE buf, size_t maxlen);
 VALUE stream_get_string(struct um_stream *stream, VALUE out_buffer, ssize_t len, size_t inc, int safe_inc);
-VALUE stream_skip(struct um_stream *stream, size_t len);
+void stream_skip(struct um_stream *stream, size_t inc, int safe_inc);
 VALUE resp_decode(struct um_stream *stream, VALUE out_buffer);
 void resp_encode(struct um_write_buffer *buf, VALUE obj);
 void resp_encode_cmd(struct um_write_buffer *buf, int argc, VALUE *argv);

data/ext/um/um_buffer_pool.c

@@ -31,7 +31,6 @@ inline struct um_buffer *bp_buffer_checkout(struct um *machine) {
   buffer->ref_count++;
   buffer->pos = 0;
   buffer->next = NULL;
-
   return buffer;
 }
 
@@ -76,7 +75,7 @@ inline void bp_setup(struct um *machine) {
   if (unlikely(!machine->bp_br)) rb_syserr_fail(ret, strerror(ret));
 
   machine->bp_buffer_size = BP_INITIAL_BUFFER_SIZE;
-  machine->bp_commit_threshold = BP_INITIAL_COMMIT_THRESHOLD;
+  machine->bp_commit_level = BP_INITIAL_COMMIT_LEVEL;
   machine->bp_commited_buffers = malloc(sizeof(struct um_buffer) * BP_BR_ENTRIES);
   memset(machine->bp_commited_buffers, 0, sizeof(struct um_buffer) * BP_BR_ENTRIES);
   memset(machine->bp_avail_bid_bitmap, 0xFF, sizeof(machine->bp_avail_bid_bitmap));
@@ -160,10 +159,13 @@ inline struct um_buffer *get_buffer(struct um *machine, int bid) {
 
 inline int should_commit_more_p(struct um *machine) {
   return (machine->bp_buffer_count < BP_BR_ENTRIES) &&
-         (machine->bp_total_commited < machine->bp_commit_threshold);
+         (machine->bp_total_commited < machine->bp_commit_level);
 }
 
 inline void bp_ensure_commit_level(struct um *machine) {
+  if (machine->bp_total_commited > (machine->bp_commit_level / 2))
+    return;
+
   int added = 0;
   while (should_commit_more_p(machine)) {
     if (likely(commit_buffer(machine, added))) added++;
@@ -178,11 +180,11 @@ inline void bp_ensure_commit_level(struct um *machine) {
 }
 
 inline void bp_handle_enobufs(struct um *machine) {
-  if (unlikely(machine->bp_commit_threshold >= BP_MAX_COMMIT_THRESHOLD))
+  if (unlikely(machine->bp_commit_level >= BP_MAX_COMMIT_LEVEL))
     rb_raise(eUMError, "Buffer starvation");
 
-  machine->bp_commit_threshold *= 2;
-  while (machine->bp_buffer_size < machine->bp_commit_threshold / 4)
+  machine->bp_commit_level *= 2;
+  while (machine->bp_buffer_size < machine->bp_commit_level / 4)
     machine->bp_buffer_size *= 2;
   bp_discard_buffer_freelist(machine);
 }

data/ext/um/um_class.c

@@ -334,17 +334,17 @@ VALUE UM_schedule(VALUE self, VALUE fiber, VALUE value) {
 }
 
 /* Runs the given block, interrupting its execution if its runtime exceeds the
- * given timeout interval (in seconds).
+ * given timeout interval (in seconds), raising the specified exception.
  *
  * - https://www.man7.org/linux/man-pages//man3/io_uring_prep_timeoute.3.html
  *
  * @param interval [Number] timeout interval in seconds
- * @param exception_class [any] timeout exception class
+ * @param exception [any] timeout exception class or instance
  * @return [any] block's return value
  */
-VALUE UM_timeout(VALUE self, VALUE interval, VALUE exception_class) {
+VALUE UM_timeout(VALUE self, VALUE interval, VALUE exception) {
   struct um *machine = um_get_machine(self);
-  return um_timeout(machine, interval, exception_class);
+  return um_timeout(machine, interval, exception);
 }
 
 /* Puts the current fiber to sleep for the given time duration (in seconds),

data/ext/um/um_stream.c

@@ -9,7 +9,7 @@ inline void stream_add_segment(struct um_stream *stream, struct um_segment *segm
   }
   else
     stream->head = stream->tail = segment;
-  stream->pending_len += segment->len;
+  stream->pending_bytes += segment->len;
 }
 
 inline int stream_process_op_result(struct um_stream *stream, struct um_op_result *result) {
@@ -50,7 +50,7 @@ void stream_multishot_op_start(struct um_stream *stream) {
     default:
       um_raise_internal_error("Invalid multishot op");
   }
-  stream->op->bp_commit_threshold = stream->machine->bp_commit_threshold;
+  stream->op->bp_commit_level = stream->machine->bp_commit_level;
 }
 
 void stream_multishot_op_stop(struct um_stream *stream) {
@@ -73,7 +73,7 @@ void um_stream_cleanup(struct um_stream *stream) {
     um_segment_checkin(stream->machine, stream->head);
     stream->head = next;
   }
-  stream->pending_len = 0;
+  stream->pending_bytes = 0;
 }
 
 // returns true if case of ENOBUFS error, sets more to true if more data forthcoming
@@ -124,7 +124,7 @@ void stream_clear(struct um_stream *stream) {
     um_segment_checkin(stream->machine, stream->head);
     stream->head = next;
   }
-  stream->pending_len = 0;
+  stream->pending_bytes = 0;
 
   if (stream->working_buffer) {
     bp_buffer_checkin(stream->machine, stream->working_buffer);
@@ -156,16 +156,27 @@ int stream_get_more_segments_bp(struct um_stream *stream) {
     enobufs = stream_process_segments(stream, &total_bytes, &more);
     um_op_multishot_results_clear(stream->machine, stream->op);
     if (unlikely(enobufs)) {
-      int should_restart = stream->pending_len < (stream->machine->bp_buffer_size * 4);
+      int should_restart = stream->pending_bytes < (stream->machine->bp_buffer_size * 4);
+      // int same_threshold = stream->op->bp_commit_level == stream->machine->bp_commit_level;
+
+      // fprintf(stderr, "%p enobufs total: %ld pending: %ld threshold: %ld bc: %d (same: %d, restart: %d)\n",
+      //   stream,
+      //   total_bytes, stream->pending_bytes, stream->machine->bp_commit_level,
+      //   stream->machine->bp_buffer_count,
+      //   same_threshold, should_restart
+      // );
 
       // If multiple stream ops are happening at the same time, they'll all get
       // ENOBUFS! We track the commit threshold in the op in order to prevent
       // running bp_handle_enobufs() more than once.
 
       if (should_restart) {
-        if (stream->op->bp_commit_threshold == stream->machine->bp_commit_threshold)
+        if (stream->op->bp_commit_level == stream->machine->bp_commit_level)
           bp_handle_enobufs(stream->machine);
-        stream_multishot_op_start(stream);
+
+        um_op_release(stream->machine, stream->op);
+        stream->op = NULL;
+        // stream_multishot_op_start(stream);
       }
       else {
         um_op_release(stream->machine, stream->op);
@@ -215,6 +226,49 @@ int stream_get_more_segments(struct um_stream *stream) {
 
 ///////////////////////////////////////////////////////////////////////////////////////
 
+inline void stream_shift_head(struct um_stream *stream) {
+  struct um_segment *consumed = stream->head;
+  stream->head = consumed->next;
+  if (!stream->head) stream->tail = NULL;
+  um_segment_checkin(stream->machine, consumed);
+  stream->pos = 0;
+}
+
+inline void stream_skip(struct um_stream *stream, size_t inc, int safe_inc) {
+  if (unlikely(stream->eof && !stream->head)) return;
+  if (safe_inc && !stream->tail && !stream_get_more_segments(stream)) return;
+
+  while (inc) {
+    size_t segment_len = stream->head->len - stream->pos;
+    size_t inc_len = (segment_len <= inc) ? segment_len : inc;
+    inc -= inc_len;
+    stream->pos += inc_len;
+    stream->consumed_bytes += inc_len;
+    stream->pending_bytes -= inc_len;
+    if (stream->pos == stream->head->len) {
+      stream_shift_head(stream);
+      if (inc && safe_inc && !stream->head) {
+        if (!stream_get_more_segments(stream)) break;
+      }
+    }
+  }
+}
+
+inline void stream_copy(struct um_stream *stream, char *dest, size_t len) {
+  while (len) {
+    char *segment_ptr = stream->head->ptr + stream->pos;
+    size_t segment_len = stream->head->len - stream->pos;
+    size_t cpy_len = (segment_len <= len) ? segment_len : len;
+    memcpy(dest, segment_ptr, cpy_len);
+
+    len -= cpy_len;
+    stream->pos += cpy_len;
+    stream->consumed_bytes += cpy_len;
+    stream->pending_bytes -= cpy_len;
+    dest += cpy_len;
+    if (stream->pos == stream->head->len) stream_shift_head(stream);
+  }
+}
 
 VALUE stream_consume_string(struct um_stream *stream, VALUE out_buffer, size_t len, size_t inc, int safe_inc) {
   VALUE str = Qnil;
@@ -228,69 +282,22 @@ VALUE stream_consume_string(struct um_stream *stream, VALUE out_buffer, size_t l
   }
   else
     str = rb_str_new(NULL, len);
-  char *str_ptr = RSTRING_PTR(str);
-  while (len) {
-    char *segment_ptr = stream->head->ptr + stream->pos;
-    size_t segment_len = stream->head->len - stream->pos;
-    size_t cpy_len = (segment_len <= len) ? segment_len : len;
-    memcpy(str_ptr, segment_ptr, cpy_len);
-
-    len -= cpy_len;
-    stream->pos += cpy_len;
-    stream->pending_len -= cpy_len;
-    str_ptr += cpy_len;
-    if (stream->pos == stream->head->len) {
-      struct um_segment *consumed = stream->head;
-      stream->head = consumed->next;
-      if (!stream->head) stream->tail = NULL;
-      um_segment_checkin(stream->machine, consumed);
-      stream->pos = 0;
-    }
-  }
+  char *dest = RSTRING_PTR(str);
 
-  while (inc) {
-    size_t segment_len = stream->head->len - stream->pos;
-    size_t inc_len = (segment_len <= inc) ? segment_len : inc;
-    inc -= inc_len;
-    stream->pos += inc_len;
-    stream->pending_len -= inc_len;
-    if (stream->pos == stream->head->len) {
-      struct um_segment *consumed = stream->head;
-      stream->head = consumed->next;
-      um_segment_checkin(stream->machine, consumed);
-      if (!stream->head) {
-        stream->tail = NULL;
-        if (inc && safe_inc) {
-          if (!stream_get_more_segments(stream)) break;
-        }
-      }
-      stream->pos = 0;
-    }
-  }
+  stream_copy(stream, dest, len);
+  stream_skip(stream, inc, safe_inc);
   return str;
   RB_GC_GUARD(str);
 }
 
-// inline void stream_advance(struct um_stream *stream, size_t inc) {
-//   while (inc) {
-//     size_t segment_len = stream->head->len - stream->pos;
-//     size_t inc_len = (segment_len <= inc) ? segment_len : inc;
-//     inc -= inc_len;
-//     stream->pos += inc_len;
-//     if (stream->pos == stream->head->len) {
-//       struct um_segment *consumed = stream->head;
-//       stream->head = consumed->next;
-//       um_segment_checkin(stream->machine, consumed);
-//       if (!stream->head) {
-//         stream->tail = NULL;
-//         if (!stream_get_more_segments(stream)) return;
-//       }
-//       stream->pos = 0;
-//     }
-//   }
-// }
-
 VALUE stream_get_line(struct um_stream *stream, VALUE out_buffer, size_t maxlen) {
+  // if (stream->head) {
+  //   fprintf(stderr, "head: %p pos: %ld: %.*s\n",
+  //     stream->head, stream->pos,
+  //     (int)(stream->head->len - stream->pos), stream->head->ptr + stream->pos
+  //   );
+  // }
+
   if (unlikely(stream->eof && !stream->head)) return Qnil;
   if (!stream->tail && !stream_get_more_segments(stream)) return Qnil;
 

data/ext/um/um_stream_class.c

@@ -102,6 +102,20 @@ static inline void stream_setup(struct um_stream *stream, VALUE target, VALUE mo
     rb_raise(eUMError, "Invalid stream mode");
 }
 
+/* call-seq:
+ *   UM::Stream.new(machine, fd, mode = nil) -> stream
+ *   machine.stream(fd, mode = nil) -> stream
+ *   machine.stream(fd, mode = nil) { |stream| ... }
+ *
+ * Initializes a new stream with the given UringMachine instance, target and
+ * optional mode. The target maybe a file descriptor, or an instance of
+ * OpenSSL::SSL::SSLSocket. In case of an SSL socket, the mode should be :ssl.
+ *
+ * @param machine [UringMachine] UringMachine instance
+ * @param target [integer, OpenSSL::SSL::SSLSocket] stream target: file descriptor or SSL socket
+ * @param mode [Symbol] optional stream mode: :bp_read, :bp_recv, :ssl
+ * @return [void]
+ */
 VALUE Stream_initialize(int argc, VALUE *argv, VALUE self) {
   VALUE machine;
   VALUE target;
@@ -118,6 +132,13 @@ VALUE Stream_initialize(int argc, VALUE *argv, VALUE self) {
   return self;
 }
 
+/* call-seq:
+ *   stream.mode -> mode
+ *
+ * Returns the stream mode.
+ *
+ * @return [Symbol] stream mode
+ */
 VALUE Stream_mode(VALUE self) {
   struct um_stream *stream = um_get_stream(self);
   switch (stream->mode) {
@@ -129,16 +150,57 @@ VALUE Stream_mode(VALUE self) {
   return Qnil;
 }
 
+/* call-seq:
+ *   stream.get_line(limit) -> str
+ *
+ * Reads from the string until a newline character is encountered. Returns the
+ * line without the newline delimiter. If limit is 0, the line length is not
+ * limited. If no newline delimiter is found before EOF, returns nil.
+ *
+ * @param limit [integer] maximum line length (0 means no limit)
+ * @return [String, nil] read data or nil
+ */
 VALUE Stream_get_line(VALUE self, VALUE limit) {
   struct um_stream *stream = um_get_stream(self);
   return stream_get_line(stream, Qnil, NUM2ULONG(limit));
 }
 
+/* call-seq:
+ *   stream.get_string(len) -> str
+ *
+ * Reads len bytes from the stream. If len is 0, reads all available bytes. If
+ * len is negative, reads up to -len available bytes. If len is positive and eof
+ * is encountered before len bytes are read, returns nil.
+ *
+ * @param len [integer] number of bytes to read
+ * @return [String, nil] read data or nil
+ */
 VALUE Stream_get_string(VALUE self, VALUE len) {
   struct um_stream *stream = um_get_stream(self);
   return stream_get_string(stream, Qnil, NUM2LONG(len), 0, false);
 }
 
+/* call-seq:
+ *   stream.skip(len) -> len
+ *
+ * Skips len bytes in the stream.
+ *
+ * @param len [integer] number of bytes to skip
+ * @return [Integer] len
+ */
+VALUE Stream_skip(VALUE self, VALUE len) {
+  struct um_stream *stream = um_get_stream(self);
+  stream_skip(stream, NUM2LONG(len), true);
+  return len;
+}
+
+/* call-seq:
+ *   stream.resp_decode -> obj
+ *
+ * Decodes an object from a RESP (Redis protocol) message.
+ *
+ * @return [any] decoded object
+ */
 VALUE Stream_resp_decode(VALUE self) {
   struct um_stream *stream = um_get_stream(self);
   VALUE out_buffer = rb_utf8_str_new_literal("");
@@ -147,6 +209,15 @@ VALUE Stream_resp_decode(VALUE self) {
   return obj;
 }
 
+/* call-seq:
+ *   stream.resp_encode(obj) -> string
+ *
+ * Encodes an object into a RESP (Redis protocol) message.
+ *
+ * @param str [String] string buffer
+ * @param obj [any] object to be encoded
+ * @return [String] str
+ */
 VALUE Stream_resp_encode(VALUE self, VALUE str, VALUE obj) {
   struct um_write_buffer buf;
   write_buffer_init(&buf, str);
@@ -156,11 +227,49 @@ VALUE Stream_resp_encode(VALUE self, VALUE str, VALUE obj) {
   return str;
 }
 
+/* call-seq:
+ *   stream.eof? -> bool
+ *
+ * Returns true if stream has reached EOF.
+ *
+ * @return [bool] EOF reached
+ */
 VALUE Stream_eof_p(VALUE self) {
   struct um_stream *stream = um_get_stream(self);
   return stream->eof ? Qtrue : Qfalse;
 }
 
+/* call-seq:
+ *   stream.consumed -> int
+ *
+ * Returns the total number of bytes consumed from the stream.
+ *
+ * @return [Integer] total bytes consumed
+ */
+VALUE Stream_consumed(VALUE self) {
+  struct um_stream *stream = um_get_stream(self);
+  return LONG2NUM(stream->consumed_bytes);
+}
+
+/* call-seq:
+ *   stream.pending -> int
+ *
+ * Returns the number of bytes available for reading.
+ *
+ * @return [Integer] bytes available
+ */
+VALUE Stream_pending(VALUE self) {
+  struct um_stream *stream = um_get_stream(self);
+  return LONG2NUM(stream->pending_bytes);
+}
+
+/* call-seq:
+ *   stream.clear -> stream
+ *
+ * Clears all available bytes and stops any ongoing read operation.
+ *
+ * @return [UM::Stream] self
+ */
 VALUE Stream_clear(VALUE self) {
   struct um_stream *stream = um_get_stream(self);
   stream_clear(stream);
@@ -176,11 +285,14 @@ void Init_Stream(void) {
 
   rb_define_method(cStream, "get_line", Stream_get_line, 1);
   rb_define_method(cStream, "get_string", Stream_get_string, 1);
+  rb_define_method(cStream, "skip", Stream_skip, 1);
 
   rb_define_method(cStream, "resp_decode", Stream_resp_decode, 0);
   rb_define_singleton_method(cStream, "resp_encode", Stream_resp_encode, 2);
 
   rb_define_method(cStream, "eof?", Stream_eof_p, 0);
+  rb_define_method(cStream, "consumed", Stream_consumed, 0);
+  rb_define_method(cStream, "pending", Stream_pending, 0);
   rb_define_method(cStream, "clear", Stream_clear, 0);
 
   eStreamRESPError = rb_define_class_under(cStream, "RESPError", rb_eStandardError);

data/grant-2025/tasks.md

@@ -35,8 +35,9 @@
       - [v] Data processing through a rewritten stream implementation.
 
   - [ ] More benchmarks
-    - Different reading methods in concurrent setting
-    - SSL vs SSL-custom-BIO vs SSL-stream
+    - [ ] Different reading methods in concurrent setting
+    - [ ] SSL vs SSL-custom-BIO vs SSL-stream in concurrent setting
+    - [ ] stream resp client vs redis gem in concurrent setting
 
   - [v] Sidecar mode
     - [v] Convert `UM#initialize` to take kwargs

data/lib/uringmachine/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class UringMachine
-  VERSION = '0.29.0'
+  VERSION = '0.29.2'
 end

data/lib/uringmachine.rb

@@ -194,6 +194,15 @@ class UringMachine
     close_async(fd)
   end
 
+  def stream(target, mode = nil)
+    stream = UM::Stream.new(self, target, mode)
+    return stream if !block_given?
+
+    res = yield(stream)
+    stream.clear
+    res
+  end
+
   private
 
   # @param block [Proc]

data/test/helper.rb

@@ -103,3 +103,5 @@ class UMBaseTest < Minitest::Test
     dir
   end
 end
+
+puts "Ruby: #{RUBY_VERSION}\nKernel: #{UringMachine.kernel_version}"

data/test/test_fiber_scheduler.rb

@@ -6,6 +6,7 @@ require 'securerandom'
 require 'socket'
 require 'net/http'
 require 'json'
+require 'timeout'
 
 class MethodCallAuditor
   attr_reader :calls
@@ -722,12 +723,11 @@ class FiberSchedulerTest < UMBaseTest
         sleep 1
       end
       res = true
-    rescue => e
-      res = e
+    rescue => res
     end
     @scheduler.join
-    assert_equal 3, machine.metrics[:total_ops]
     assert_kind_of Timeout::Error, res
+    assert_equal 3, machine.metrics[:total_ops]
     assert_equal({
       fiber: 1,
       timeout_after: 1,

data/test/test_stream.rb

@@ -46,7 +46,10 @@ class StreamTest < StreamBaseTest
     assert stream.eof?
 
     stream.clear
-    assert_equal [5, 0, 256, 16384 * 5, 16384 * 5 - 6], buffer_metrics
+
+    # initial buffer size: 6BKV, initial buffers commited: 16 (256KB)
+    # (plus an additional buffer commited after first usage)
+    assert_equal [16, 0, 256, 16384 * 16, 16384 * 16 - 6], buffer_metrics
     assert_equal 0, machine.metrics[:ops_pending]
   end
 
@@ -68,7 +71,7 @@ class StreamTest < StreamBaseTest
     assert_equal 0, machine.metrics[:ops_pending]
     assert_equal 256, machine.metrics[:segments_free]
 
-    assert_equal [5, 0, 256, 16384 * 5, 16384 * 5 - 6], buffer_metrics
+    assert_equal [16, 0, 256, 16384 * 16, 16384 * 16 - 6], buffer_metrics
   ensure
     machine.close(rfd) rescue nil
     machine.close(wfd) rescue nil
@@ -118,11 +121,11 @@ class StreamTest < StreamBaseTest
     buf = stream.get_string(msg.bytesize)
     assert_equal msg, buf
 
-    assert_equal 16, machine.metrics[:buffers_allocated]
-    assert_equal 11, machine.metrics[:buffers_free]
+    stream.clear
+    # numbers may vary with different kernel versions
+    assert_in_range 24..32, machine.metrics[:buffers_allocated]
+    assert_in_range 10..18, machine.metrics[:buffers_free]
     assert_equal 256, machine.metrics[:segments_free]
-    assert_equal 65536 * 4, machine.metrics[:buffer_space_allocated]
-
   ensure
     machine.terminate(f)
     machine.join(f)
@@ -136,7 +139,7 @@ class StreamTest < StreamBaseTest
 
     assert_equal 'foo', stream.get_line(0)
 
-    assert_equal [5, 0, 255, 16384 * 5, 16384 * 5 - 12], buffer_metrics
+    assert_equal [16, 0, 255, 16384 * 16, 16384 * 16 - 12], buffer_metrics
     assert_equal 'bar', stream.get_line(0)
     assert_nil stream.get_line(0)
     assert_equal "baz", stream.get_string(-6)
@@ -152,11 +155,11 @@ class StreamTest < StreamBaseTest
     machine.close(@wfd)
 
     # three segments received
-    assert_equal [5, 0, 253, 16384 * 5, 16384 * 5 - 13], buffer_metrics
+    assert_equal [16, 0, 253, 16384 * 16, 16384 * 16 - 13], buffer_metrics
     assert_equal 'bar', stream.get_line(0)
-    assert_equal [5, 0, 255, 16384 * 5, 16384 * 5 - 13], buffer_metrics
+    assert_equal [16, 0, 255, 16384 * 16, 16384 * 16 - 13], buffer_metrics
     assert_equal 'baz', stream.get_line(0)
-    assert_equal [5, 0, 256, 16384 * 5, 16384 * 5 - 13], buffer_metrics
+    assert_equal [16, 0, 256, 16384 * 16, 16384 * 16 - 13], buffer_metrics
     assert_nil stream.get_line(0)
   end
 
@@ -182,7 +185,7 @@ class StreamTest < StreamBaseTest
     assert_equal 'bizz', stream.get_line(5)
 
     assert_nil stream.get_line(8)
-    assert_equal [5, 0, 256, 16384 * 5, 16384 * 5 - 17], buffer_metrics
+    assert_equal [16, 0, 256, 16384 * 16, 16384 * 16 - 17], buffer_metrics
   end
 
   def test_stream_get_string
@@ -218,6 +221,16 @@ class StreamTest < StreamBaseTest
     assert_nil stream.get_string(-3)
   end
 
+  def test_stream_skip
+    machine.write(@wfd, "foobarbaz")
+
+    stream.skip(2)
+    assert_equal 'obar', stream.get_string(4)
+
+    stream.skip(1)
+    assert_equal 'az', stream.get_string(0)
+  end
+
   def test_stream_big_data
     data = SecureRandom.random_bytes(300_000)
     fiber = machine.spin {
@@ -467,6 +480,23 @@ class StreamDevRandomTest < UMBaseTest
     machine.close(fd) rescue nil
   end
 
+  def get_line_do(n, acc)
+    fd = @machine.open('/dev/random', UM::O_RDONLY)
+    stream = UM::Stream.new(@machine, fd)
+    n.times { acc << stream.get_line(0) }
+  end
+
+  def test_stream_dev_random_get_line_concurrent
+    acc = []
+    c = 1
+    n = 100000
+    ff = c.times.map {
+      machine.spin { get_line_do(n, acc) }
+    }
+    machine.await(ff)
+    assert_equal c * n, acc.size
+  end
+
   def test_stream_dev_random_get_string
     fd = machine.open('/dev/random', UM::O_RDONLY)
     stream = UM::Stream.new(machine, fd)
@@ -573,3 +603,36 @@ class StreamModeTest < UMBaseTest
     sock2&.close rescue nil
   end
 end
+
+class StreamByteCountsTest < StreamBaseTest
+  def test_stream_byte_counts
+    machine.write(@wfd, "foobar")
+
+    assert_equal 0, stream.consumed
+    assert_equal 0, stream.pending
+
+    buf = stream.get_string(2)
+    assert_equal 'fo', buf
+    assert_equal 2, stream.consumed
+    assert_equal 4, stream.pending
+
+    buf = stream.get_string(3)
+    assert_equal 'oba', buf
+    assert_equal 5, stream.consumed
+    assert_equal 1, stream.pending
+
+    machine.write(@wfd, "abc\ndef")
+    machine.snooze
+    assert_equal 5, stream.consumed
+    assert_equal 1, stream.pending
+
+    buf = stream.get_line(0)
+    assert_equal 'rabc', buf
+    assert_equal 10, stream.consumed
+    assert_equal 3, stream.pending
+
+    stream.clear
+    assert_equal 10, stream.consumed
+    assert_equal 0, stream.pending
+  end
+end

data/test/test_um.rb

@@ -292,6 +292,20 @@ class ScheduleTest < UMBaseTest
     assert_kind_of TOError, e
   end
 
+  def test_timeout_with_exception_instance
+    res = nil
+    e = TOError.new
+    begin
+      res = machine.timeout(0.01, e) {
+        machine.sleep(1)
+        :foo
+      }
+    rescue => res
+    end
+
+    assert_equal e, res
+  end
+
   def test_timeout_with_raising_block
     e = nil
     begin
@@ -3491,3 +3505,55 @@ class SetChildSubreaperTest < Minitest::Test
     assert_equal grand_child_pid, res
   end
 end
+
+class StreamMethodTest < UMBaseTest
+  def setup
+    super
+    @rfd, @wfd = UM.pipe
+  end
+
+  def teardown
+    @stream = nil
+    machine.close(@rfd) rescue nil
+    machine.close(@wfd) rescue nil
+    super
+  end
+
+  def test_stream_method
+    machine.write(@wfd, "foobar")
+    machine.close(@wfd)
+
+    stream = machine.stream(@rfd)
+    assert_kind_of UM::Stream, stream
+
+    buf = stream.get_string(3)
+    assert_equal 'foo', buf
+
+    buf = stream.get_string(-6)
+    assert_equal 'bar', buf
+    assert stream.eof?
+
+    stream.clear
+  end
+
+  def test_stream_method_with_block
+    machine.write(@wfd, "foobar")
+    machine.close(@wfd)
+
+    bufs = []
+    stream_obj = nil
+    res = machine.stream(@rfd) do |s|
+      stream_obj = s
+
+      bufs << s.get_string(3)
+      bufs << s.get_string(-6)
+
+      :foo
+    end
+
+    assert_kind_of UM::Stream, stream_obj
+    assert stream_obj.eof?
+    assert_equal ['foo', 'bar'], bufs
+    assert_equal :foo, res
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uringmachine
 version: !ruby/object:Gem::Version
-  version: 0.29.0
+  version: 0.29.2
 platform: ruby
 authors:
 - Sharon Rosner
@@ -67,6 +67,7 @@ files:
 - benchmark/common.rb
 - benchmark/dns_client.rb
 - benchmark/gets.rb
+- benchmark/gets_concurrent.rb
 - benchmark/http_parse.rb
 - benchmark/http_server_accept_queue.rb
 - benchmark/http_server_multi_accept.rb