uringmachine 0.28.3 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbdc1ca412e20436a209c2e4f77af29873d5c8bac02f88c35562333f1e5328e6
-  data.tar.gz: d426661ce83c278041042c5829a23b4bb5c0c65cf99d1cb3cb96f5706b464859
+  metadata.gz: 6a6a6d78b632e43c1ac15e8745ede898e531ff9a731822fd22c5991ca0222d69
+  data.tar.gz: 0acd35ee028ea519c2788c720336dbcb1c2fa8317912459b7a81f4afbe6b3747
 SHA512:
-  metadata.gz: 9908398a698bf7a2771a88b369023e27c3669bd205eb86a8132fee154709d68b21cd05a4fcd8b0bacb0f8e10140f2a2ef002f01cd7ac8177bf678c4f8e8574b5
-  data.tar.gz: afb606febf25d41fdf99b00e8cdeaa97523608445cc842cf49acbdf5af95f726276d443a574363b23b9b6c8287fad560780913f4bf1fd09240cf5df29185a9ac
+  metadata.gz: ed9f7684132ee1e1aae9c7783131fd927e88604444d44bc889cdf8c362b0a5dd85b3e887873c0512946af2c08dd8189e6c3bf972f19f90a7f12daee4c44c5ccd
+  data.tar.gz: f5bff069de535e906543a679266700bacbb715d0e72b14d4bf7cd042ab8d77e58d8c69feb1dbd65f16026aa4bcec20d024acffd2e2f18ac255f5b70190c25788

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+# 0.29.0 2026-03-11
+
+- Reimplement streams based on buffer pool
+- Add buffer pool with automatic buffer commit
+- Add support for procs in `#await`, `#join`
+- Accept splat fibers in `#await`
+- Rename `#await_fibers` to `#await`
+- Fiber scheduler: make `blocking_operation_wait` optional
+
 # 0.28.3 2026-02-22
 
 - Accept array in `#terminate` and `#join`
@@ -67,7 +76,7 @@
 - Add `UM#metrics` for getting metrics
 - Add `UM#pending_fibers` for detecting leaking fibers in tests
 - More tests and benchmarks
-- Add `UM#await_fibers` for awaiting fibers
+- Add `UM#await` for awaiting fibers
 - Add `UM.socketpair` for creating a socket pair
 - Fix segfault caused by waiting fibers not being marked
 - Fiber scheduler:

data/TODO.md

@@ -1,7 +1,7 @@
 ## immediate
 
 - Add support for exception instances in `#timeout`.
-- Add support for returning a value on timeout:
+- Add support for returning a value on timeout
 
   Since to do this safely we need to actually raise an exception that wraps the
   value, rescue it and return the value, we might want a separate method that
@@ -15,19 +15,22 @@
     timeout(interval, timeout_error, &block)
   rescue TimeoutValueError => e
     raise if e != timeout_error
-    
+
     value
   end
   ```
 
-- Add tests for support for Set in `machine#await_fibers`
+- Add tests for support for Set in `machine#await`
 - Add tests for support for Set, Array in `machine#join`
 - Add `#read_file` for reading entire file
 - Add `#write_file` for writing entire file
 
 - (?) Fix all futex value (Queue, Mutex) to be properly aligned
 
+<<<<<<< HEAD
+=======
 ## Buffer rings - automatic management
+
 - Take the buffer_pool branch, rewrite it
 - Allow multiple stream modes:
   - :buffer_pool - uses buffer rings
@@ -39,13 +42,27 @@ The API will look something like:
 ```ruby
 # The mode is selected automatically according to the given target
 
-stream = UM::Stream.new(fd) # buffer_pool mode
+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
+```
 
-stream = UM::Stream.new(ssl_sock) # ssl mode
+This can be very useful in testing of stuff such as protocol implementations:
 
-stream = UM::Stream.new(conn) # io mode
+```ruby
+stream = UM::Stream.new(machine, "GET /foo HTTP/1.1\r\nHost: bar.com\r\n")
 ```
 
+So basically the stream is tied to a machine, and that means it can only be used
+on the thread with which the machine is associated. It is not thread-safe. (This
+is incidentally true also for most of the UringMachine instance methods!)
+
+Continued discussion in docs/design/buffer_pool.md
+
+>>>>>>> 04d9eb7 (Docs)
 ## Balancing I/O with the runqueue
 
 - in some cases where there are many entries in the runqueue, this can
@@ -133,37 +150,14 @@ stream.read_to_eof(buf)
 stream.read_to_eof(nil)
 ```
 
-## Syntax / pattern for launching multiple operations
+## Syntax / pattern for launching/supervising multiple operations
+
+Select (see above):
 
 ```ruby
-results = machine.concurrently(
-  -> { machine.read(fd1, ...) },
-  -> { machine.read(fd2, ...) }
-  -> { ... }
-)
-
-# or maybe:
-jobs = (1..100).map { |i| -> { machine.read_file("/file_#{i}.csv") } }
-machine.join(jobs)
-
-# or maybe:
-jobs = (1..100).map { |i|
-  -> {
-    pipe  { machine.read_file("/file_#{i}.csv") }
-      >   { csv_to_pdf(it) }
-      >   { machine.write_file("/file_#{i}.pdf", it) }
-  }
-}
-
-# or otherwise
-jobs = (1..100).map { |i|
-  -> {
-    csv = machine.read_file("/file_#{i}.csv")
-    pdf = csv_to_pdf(csv)
-    machine.write_file("/file_#{i}.pdf", pdf)
-  }
-}
-machine.join(jobs)
+# select
+machine.join_select(*fibers) #=> [result, fiber]
+machine.shift_select(*queues) #=> [result, queue]
 ```
 
 ## Other abstractions

data/benchmark/common.rb

@@ -200,7 +200,7 @@ class UMBenchmark
     fibers = []
     fds = []
     do_um(machine, fibers, fds)
-    machine.await_fibers(fibers)
+    machine.await(fibers)
     fds.each { machine.close(it) }
   end
 
@@ -209,7 +209,7 @@ class UMBenchmark
     fibers = []
     fds = []
     do_um(machine, fibers, fds)
-    machine.await_fibers(fibers)
+    machine.await(fibers)
     fds.each { machine.close(it) }
   end
 
@@ -218,7 +218,7 @@ class UMBenchmark
     fibers = []
     fds = []
     do_um(machine, fibers, fds)
-    machine.await_fibers(fibers)
+    machine.await(fibers)
     fds.each { machine.close(it) }
   end
 
@@ -229,7 +229,7 @@ class UMBenchmark
         fibers = []
         fds = []
         do_um_x(2, machine, fibers, fds)
-        machine.await_fibers(fibers)
+        machine.await(fibers)
         fds.each { machine.close(it) }
       end
     end
@@ -243,7 +243,7 @@ class UMBenchmark
         fibers = []
         fds = []
         do_um_x(4, machine, fibers, fds)
-        machine.await_fibers(fibers)
+        machine.await(fibers)
         fds.each { machine.close(it) }
       end
     end
@@ -257,7 +257,7 @@ class UMBenchmark
         fibers = []
         fds = []
         do_um_x(8, machine, fibers, fds)
-        machine.await_fibers(fibers)
+        machine.await(fibers)
         fds.each { machine.close(it) }
       end
     end

data/benchmark/gets.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'uringmachine', path: '..'
+  gem 'benchmark'
+  gem 'benchmark-ips'
+end
+
+require 'benchmark/ips'
+require 'uringmachine'
+
+@machine = UM.new
+
+@io = File.open('/dev/random', 'r')
+def io_gets
+  @io.gets
+end
+
+@fd = @machine.open('/dev/random', UM::O_RDONLY)
+@buffer = +''.encode(Encoding::US_ASCII)
+def um_read
+  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
+
+@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)
+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.compare!(order: :baseline)
+end

data/benchmark/{read_each.rb → output.rb}

@@ -13,42 +13,31 @@ require 'uringmachine'
 
 @machine = UM.new
 
-make_socket_pair = -> do
-  port = 10000 + rand(30000)
-  server_fd = @machine.socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
-  @machine.setsockopt(server_fd, UM::SOL_SOCKET, UM::SO_REUSEADDR, true)
-  @machine.bind(server_fd, '127.0.0.1', port)
-  @machine.listen(server_fd, UM::SOMAXCONN)
-
-  client_conn_fd = @machine.socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
-  @machine.connect(client_conn_fd, '127.0.0.1', port)
-
-  server_conn_fd = @machine.accept(server_fd)
-
-  @machine.close(server_fd)
-  [client_conn_fd, server_conn_fd]
-end
-
-@client_fd, @server_fd = make_socket_pair.()
+@client_fd, @server_fd = UM.socketpair(UM::AF_UNIX, UM::SOCK_STREAM, 0)
 
 @read_buf = +''
 @read_fiber = @machine.spin do
   while true
     @machine.read(@client_fd, @read_buf, 65536, 0)
   end
+rescue Exception => e
+  p e
+  p e.backtrace.join
+  exit!
 end
 
 STR_COUNT = ARGV[0]&.to_i || 3
 STR_SIZE = ARGV[1]&.to_i || 100
 
 @parts = ['*' * STR_SIZE] * STR_COUNT
+p @parts
 
-@server_io = IO.new(@server_fd)
-@server_io.sync = true
-def io_write
-  @server_io.write(*@parts)
-  @machine.snooze
-end
+# @server_io = IO.new(@server_fd)
+# @server_io.sync = true
+# def io_write
+#   @server_io.write(*@parts)
+#   10.times { @machine.snooze }
+# end
 
 def um_write
   str = @parts.join
@@ -61,6 +50,17 @@ def um_write
   end
 end
 
+# def um_writev
+#   str = @parts.join
+#   len = str.bytesize
+
+#   while len > 0
+#     ret = @machine.write(@server_fd, str, len)
+#     len -= ret
+#     str = str[ret..-1] if len > 0
+#   end
+# end
+
 def um_send
   str = @parts.join
   @machine.send(@server_fd, str, str.bytesize, UM::MSG_WAITALL)
@@ -73,8 +73,11 @@ end
 
 p(STR_COUNT:, STR_SIZE:)
 
+# 10.times { io_write }
+# @machine.sleep(0.5)
+
 Benchmark.ips do |x|
-  x.report('IO#write')       { io_write }
+  # x.report('IO#write')       { io_write }
   x.report('UM#write')       { um_write }
   x.report('UM#send')        { um_send }
   x.report('UM#send_bundle') { um_send_bundle }

data/docs/design/buffer_pool.md

@@ -20,9 +20,44 @@ buffers, to using managed buffers from the buffer pool.
 
 ## Design
 
+### Goals
+
+- We want an abstract design that will work with both multishot read/recv and
+  automatic buffer management, *and* other readable sources, such as an SSL
+  socket, an `IO` instance, or even a string or a `IO::Buffer`.
+
+### The Stream Data Model
+
+- A stream is a series of `segments` (containing a `ptr` and `len`), held in a
+  linked list. A segment also has a `type` and a potential backing store
+  reference. For example, a segment with a `SEGMENT_STRING` type points to a
+  `String` object. A segment with a `SEGMENT_BUFFER_POOL` has a reference to a
+  managed buffer from the buffer pool with the given id.
+- The buffer pool is linked list of buffer descriptors, each referencing a piece
+  of memory of a certain length, along with some metadata.
+- Buffer descriptors are allocated in batches as needed and added to the buffer
+  pool.
+- A buffer group describes a buffer ring. It has a certain size, which limits
+  the number of buffers that can be added to the buffer ring.
+- When a buffer group is used for a multishot read/recv, buffers will be
+  automatically checked out from the buffer pool and added to the buffer ring
+  and commited to the kernel. The buffer group allocates and tracks a buffer id
+  for each buffer descriptor.
+
+### How buffer groups are checked out
+
+- We need a freelist of buffer groups
+
+- Once a segment is completely consumed, some cleanup code might be needed (for
+  example to decrement a ref_count on a managed buffer, or unlocking a string
+  backing store.)
+
+
 ### The API
 
 - The buffer pool is created and managed automatically. No API is involved.
+-
+- 
 
 - To use the buffer pool, two dedicated APIs are added:
 

data/docs/um_api.md

@@ -22,6 +22,7 @@
 - `accept_into_queue(sockfd, queue)` - accepts incoming connections to the given
   server socket in an infinite loop, pushing each one to the given queue.
 - `accept(sockfd)` - accepts an incoming connection, returning its fd.
+- `await(*fibers)` - awaits fiber termination
 - `bind(sockfd, host, port)` - binds the given socket to the given address.
 - `close_async(fd)` - closes the given fd asynchronously, i.e. <w>ithout waiting
   for the operation to complete.
@@ -29,6 +30,7 @@
 - `connect(sockfd, host, port)` - connects the given socket to the given
   address.
 - `getsockopt(sockfd, level, opt)` - returns a socket option value.
+- `join(*fibers)` - waits for fibers to terminate and returns return values.
 - `listen(sockfd)` - starts listening on the given socket.
 - `metrics` - returns metrics for the machine.
 - `open(pathname, flags)` - opens the given path and returns an fd.

data/ext/um/extconf.rb

@@ -30,9 +30,7 @@ def get_config
 end
 
 config = get_config
-puts "Building UringMachine (\n#{config.map { |(k, v)| "  #{k}: #{v}\n"}.join})"
-
-# require_relative 'zlib_conf'
+STDERR.puts "Building UringMachine (\n#{config.map { |(k, v)| "  #{k}: #{v}\n"}.join})"
 
 liburing_path = File.expand_path('../../vendor/liburing', __dir__)
 FileUtils.cd liburing_path do
@@ -76,8 +74,11 @@ $defs << '-DHAVE_IO_URING_PREP_BIND'            if config[:prep_bind]
 $defs << '-DHAVE_IO_URING_PREP_LISTEN'          if config[:prep_listen]
 $defs << '-DHAVE_IO_URING_SEND_VECTORIZED'      if config[:send_vectoized]
 
-$CFLAGS << ' -Wno-pointer-arith'
+$CFLAGS << ' -Werror -Wall -Wextra'
 
-CONFIG['optflags'] << ' -fno-strict-aliasing'
+if ENV['SANITIZE']
+  $CFLAGS << ' -fsanitize=undefined,address -lasan'
+  $LDFLAGS << ' -fsanitize=undefined,address -lasan'
+end
 
 create_makefile 'um_ext'

data/ext/um/um.c

@@ -38,6 +38,8 @@ void um_setup(VALUE self, struct um *machine, uint size, uint sqpoll_timeout_mse
   if (ret) rb_syserr_fail(-ret, strerror(-ret));
   machine->ring_initialized = 1;
 
+  bp_setup(machine);
+
   if (machine->sidecar_mode) um_sidecar_setup(machine);
 }
 
@@ -56,7 +58,8 @@ inline void um_teardown(struct um *machine) {
   io_uring_queue_exit(&machine->ring);
   machine->ring_initialized = 0;
 
-  um_free_buffer_linked_list(machine);
+  bp_discard_buffer_freelist(machine);
+  bp_teardown(machine);
 }
 
 inline struct io_uring_sqe *um_get_sqe(struct um *machine, struct um_op *op) {
@@ -981,7 +984,7 @@ struct send_recv_fd_ctx {
   struct msghdr msgh;
   char iobuf[1];
   struct iovec iov;
-  union { // Ancillary data buffer, wrapped in a union for alignment 
+  union { // Ancillary data buffer, wrapped in a union for alignment
     char buf[CMSG_SPACE(sizeof(int))];
     struct cmsghdr align;
   } u;
@@ -1296,6 +1299,13 @@ VALUE accept_each_start(VALUE arg) {
     struct um_op_result *result = &ctx->op->result;
     while (result) {
       if (unlikely(result->res < 0)) {
+        if (result->res == -EINVAL) {
+          // An EINVAL indicates the socket was shutdown, so we just break of of
+          // the loop. We also need to prevent raising error in
+          // um_verify_op_completion.
+          result->res = 0;
+          break;
+        }
         rb_syserr_fail(-result->res, strerror(-result->res));
       }
       rb_yield(INT2NUM(result->res));
@@ -1326,6 +1336,13 @@ VALUE accept_into_queue_start(VALUE arg) {
     struct um_op_result *result = &ctx->op->result;
     while (result) {
       if (unlikely(result->res < 0)) {
+        if (result->res == -EINVAL) {
+          // An EINVAL indicates the socket was shutdown, so we just break of of
+          // the loop. We also need to prevent raising error in
+          // um_verify_op_completion.
+          result->res = 0;
+          break;
+        }
         rb_syserr_fail(-result->res, strerror(-result->res));
       }
       um_queue_push(ctx->machine, ctx->queue, INT2NUM(result->res));
@@ -1533,26 +1550,38 @@ extern VALUE SYM_ops_free;
 extern VALUE SYM_ops_transient;
 extern VALUE SYM_time_total_cpu;
 extern VALUE SYM_time_total_wait;
+extern VALUE SYM_buffer_groups;
+extern VALUE SYM_buffers_allocated;
+extern VALUE SYM_buffers_free;
+extern VALUE SYM_segments_free;
+extern VALUE SYM_buffer_space_allocated;
+extern VALUE SYM_buffer_space_commited;
 
 VALUE um_metrics(struct um *machine, struct um_metrics *metrics) {
   VALUE hash = rb_hash_new();
 
-  rb_hash_aset(hash, SYM_size,            UINT2NUM(machine->size));
+  rb_hash_aset(hash, SYM_size,                    UINT2NUM(machine->size));
+
+  rb_hash_aset(hash, SYM_total_ops,               ULONG2NUM(metrics->total_ops));
+  rb_hash_aset(hash, SYM_total_switches,          ULONG2NUM(metrics->total_switches));
+  rb_hash_aset(hash, SYM_total_waits,             ULONG2NUM(metrics->total_waits));
 
-  rb_hash_aset(hash, SYM_total_ops,       ULONG2NUM(metrics->total_ops));
-  rb_hash_aset(hash, SYM_total_switches,  ULONG2NUM(metrics->total_switches));
-  rb_hash_aset(hash, SYM_total_waits,     ULONG2NUM(metrics->total_waits));
+  rb_hash_aset(hash, SYM_ops_pending,             UINT2NUM(metrics->ops_pending));
+  rb_hash_aset(hash, SYM_ops_unsubmitted,         UINT2NUM(metrics->ops_unsubmitted));
+  rb_hash_aset(hash, SYM_ops_runqueue,            UINT2NUM(metrics->ops_runqueue));
+  rb_hash_aset(hash, SYM_ops_free,                UINT2NUM(metrics->ops_free));
+  rb_hash_aset(hash, SYM_ops_transient,           UINT2NUM(metrics->ops_transient));
 
-  rb_hash_aset(hash, SYM_ops_pending,     UINT2NUM(metrics->ops_pending));
-  rb_hash_aset(hash, SYM_ops_unsubmitted, UINT2NUM(metrics->ops_unsubmitted));
-  rb_hash_aset(hash, SYM_ops_runqueue,    UINT2NUM(metrics->ops_runqueue));
-  rb_hash_aset(hash, SYM_ops_free,        UINT2NUM(metrics->ops_free));
-  rb_hash_aset(hash, SYM_ops_transient,   UINT2NUM(metrics->ops_transient));
+  rb_hash_aset(hash, SYM_buffers_allocated,       UINT2NUM(metrics->buffers_allocated));
+  rb_hash_aset(hash, SYM_buffers_free,            UINT2NUM(metrics->buffers_free));
+  rb_hash_aset(hash, SYM_segments_free,           UINT2NUM(metrics->segments_free));
+  rb_hash_aset(hash, SYM_buffer_space_allocated,  ULONG2NUM(metrics->buffer_space_allocated));
+  rb_hash_aset(hash, SYM_buffer_space_commited,   ULONG2NUM(metrics->buffer_space_commited));
 
   if (machine->profile_mode) {
     double total_cpu = um_get_time_cpu() - metrics->time_first_cpu;
-    rb_hash_aset(hash, SYM_time_total_cpu,  DBL2NUM(total_cpu));
-    rb_hash_aset(hash, SYM_time_total_wait, DBL2NUM(metrics->time_total_wait));
+    rb_hash_aset(hash, SYM_time_total_cpu,        DBL2NUM(total_cpu));
+    rb_hash_aset(hash, SYM_time_total_wait,       DBL2NUM(metrics->time_total_wait));
   }
 
   return hash;