uringmachine 0.29.1 → 0.29.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 248a2f0e2a780904f26f0183d08237039e18b76b736e7b3563c2699e30041d65
-  data.tar.gz: 2020b0c8cc9be25becddef80fa4c66f0bc49e30d0791ec2b2b2e618fbf3ab0b6
+  metadata.gz: 6151ac8411facd0ef37fa66a7cae623d2137f335bbe1e178529cb0a76c9f56c3
+  data.tar.gz: 5918fde9ea4ba936760a3d402207bd6fd5806337b005cd3633ab1cf0f8584ed0
 SHA512:
-  metadata.gz: 543a8adf2c628f080f9ec249e11ff7e4bd969f0eca9e47285ba0ef20c28575ddd6d1902a3890d49ccb1ccf5100d13cd721bbd03c472bde15205344524fd7795c
-  data.tar.gz: 4afbe860f29187507c57a8e319d02f2f843d27aa7d65176f0e0040914bf4d8e68ce894d4663b13d3ace530bf2aa4fe3ca547e58d5cbcb1daf5d89f6d5bb94ae2
+  metadata.gz: 0d77a7f37251930db32ec8023b1cb60e5595348544b279b175d39a528dbe782a703c75f6ebde5b2dd84379ec12ae83decf47f11f0b692e4975a36f146b4bc975
+  data.tar.gz: 190d3d88d32f91241c3c9ed3fc674d5318fcf630e64d5d5fdecdc7a86b6e62f03786190a021f4828e6a40022ccbf301a3cffdf0311ff35bc747889d9f00fbb9b

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 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,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/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.h

@@ -283,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;
 };

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) {
@@ -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,12 +156,12 @@ 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_len, stream->machine->bp_commit_level,
+      //   total_bytes, stream->pending_bytes, stream->machine->bp_commit_level,
       //   stream->machine->bp_buffer_count,
       //   same_threshold, should_restart
       // );
@@ -173,7 +173,7 @@ int stream_get_more_segments_bp(struct um_stream *stream) {
       if (should_restart) {
         if (stream->op->bp_commit_level == stream->machine->bp_commit_level)
           bp_handle_enobufs(stream->machine);
-  
+
         um_op_release(stream->machine, stream->op);
         stream->op = NULL;
         // stream_multishot_op_start(stream);
@@ -235,12 +235,16 @@ inline void stream_shift_head(struct um_stream *stream) {
 }
 
 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->pending_len -= 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) {
@@ -259,7 +263,8 @@ inline void stream_copy(struct um_stream *stream, char *dest, size_t len) {
 
     len -= cpy_len;
     stream->pos += cpy_len;
-    stream->pending_len -= 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);
   }

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/lib/uringmachine/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class UringMachine
-  VERSION = '0.29.1'
+  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/test_stream.rb

@@ -221,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 {
@@ -593,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

@@ -3505,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.1
+  version: 0.29.2
 platform: ruby
 authors:
 - Sharon Rosner