uringmachine 0.19 → 0.20.0

data/ext/um/um_const.c

@@ -13,6 +13,7 @@
 #include <netdb.h>
 #include <net/if.h>
 #include <poll.h>
+#include <signal.h>
 
 #define DEF_CONST_INT(mod, v) rb_define_const(mod, #v, INT2NUM(v))
 
@@ -88,12 +89,12 @@ void um_define_net_constants(VALUE mod) {
   DEF_CONST_INT(mod, O_TRUNC);
   DEF_CONST_INT(mod, O_WRONLY);
 
-  DEF_CONST_INT(mod, WNOHANG);
-  DEF_CONST_INT(mod, WUNTRACED);
   DEF_CONST_INT(mod, WCONTINUED);
   DEF_CONST_INT(mod, WEXITED);
-  DEF_CONST_INT(mod, WSTOPPED);
+  DEF_CONST_INT(mod, WNOHANG);
   DEF_CONST_INT(mod, WNOWAIT);
+  DEF_CONST_INT(mod, WSTOPPED);
+  DEF_CONST_INT(mod, WUNTRACED);
 
   DEF_CONST_INT(mod, SOCK_STREAM);
   DEF_CONST_INT(mod, SOCK_DGRAM);
@@ -391,4 +392,51 @@ void um_define_net_constants(VALUE mod) {
   DEF_CONST_INT(mod, EKEYREJECTED);
   DEF_CONST_INT(mod, EOWNERDEAD);
   DEF_CONST_INT(mod, ENOTRECOVERABLE);
+
+  DEF_CONST_INT(mod, P_PID);
+  DEF_CONST_INT(mod, P_PIDFD);
+  DEF_CONST_INT(mod, P_PGID);
+  DEF_CONST_INT(mod, P_ALL);
+
+  DEF_CONST_INT(mod, CLD_EXITED);
+  DEF_CONST_INT(mod, CLD_KILLED);
+  DEF_CONST_INT(mod, CLD_DUMPED);
+  DEF_CONST_INT(mod, CLD_STOPPED);
+  DEF_CONST_INT(mod, CLD_TRAPPED);
+  DEF_CONST_INT(mod, CLD_CONTINUED);
+
+  DEF_CONST_INT(mod, SIGHUP);
+  DEF_CONST_INT(mod, SIGINT);
+  DEF_CONST_INT(mod, SIGQUIT);
+  DEF_CONST_INT(mod, SIGILL);
+  DEF_CONST_INT(mod, SIGTRAP);
+  DEF_CONST_INT(mod, SIGABRT);
+  DEF_CONST_INT(mod, SIGIOT);
+  DEF_CONST_INT(mod, SIGFPE);
+  DEF_CONST_INT(mod, SIGKILL);
+  DEF_CONST_INT(mod, SIGBUS);
+  DEF_CONST_INT(mod, SIGSEGV);
+  DEF_CONST_INT(mod, SIGSYS);
+  DEF_CONST_INT(mod, SIGPIPE);
+  DEF_CONST_INT(mod, SIGALRM);
+  DEF_CONST_INT(mod, SIGTERM);
+  DEF_CONST_INT(mod, SIGURG);
+  DEF_CONST_INT(mod, SIGSTOP);
+  DEF_CONST_INT(mod, SIGTSTP);
+  DEF_CONST_INT(mod, SIGCONT);
+  DEF_CONST_INT(mod, SIGCHLD);
+  DEF_CONST_INT(mod, SIGCLD);
+  DEF_CONST_INT(mod, SIGTTIN);
+  DEF_CONST_INT(mod, SIGTTOU);
+  DEF_CONST_INT(mod, SIGIO);
+  DEF_CONST_INT(mod, SIGXCPU);
+  DEF_CONST_INT(mod, SIGXFSZ);
+  DEF_CONST_INT(mod, SIGVTALRM);
+  DEF_CONST_INT(mod, SIGPROF);
+  DEF_CONST_INT(mod, SIGWINCH);
+  DEF_CONST_INT(mod, SIGUSR1);
+  DEF_CONST_INT(mod, SIGUSR2);
+  DEF_CONST_INT(mod, SIGPWR);
+  DEF_CONST_INT(mod, SIGPOLL);
+
 }

data/ext/um/um_mutex_class.c

@@ -11,7 +11,7 @@ static const rb_data_type_t Mutex_type = {
     .dsize = NULL,
     .dcompact = NULL
   },
-  .flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED | RUBY_TYPED_EMBEDDABLE
+  .flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED
 };
 
 static VALUE Mutex_allocate(VALUE klass) {

data/ext/um/um_queue_class.c

@@ -26,7 +26,7 @@ static const rb_data_type_t Queue_type = {
     .dsize = NULL,
     .dcompact = Queue_compact
   },
-  .flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED | RUBY_TYPED_EMBEDDABLE
+  .flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED
 };
 
 static VALUE Queue_allocate(VALUE klass) {

data/ext/um/um_stream.c

@@ -211,7 +211,7 @@ static inline VALUE resp_decode_simple_error(char *ptr, ulong len) {
   if (!ID_new) ID_new = rb_intern("new");
 
   VALUE msg = rb_str_new(ptr + 1, len - 1);
-  VALUE err = rb_funcall(rb_eRuntimeError, ID_new, 1, msg);
+  VALUE err = rb_funcall(eStreamRESPError, ID_new, 1, msg);
   RB_GC_GUARD(msg);
   return err;
 }
@@ -221,7 +221,7 @@ static inline VALUE resp_decode_error(struct um_stream *stream, VALUE out_buffer
   if (!ID_new) ID_new = rb_intern("new");
 
   VALUE msg = resp_decode_string(stream, out_buffer, len);
-  VALUE err = rb_funcall(rb_eRuntimeError, ID_new, 1, msg);
+  VALUE err = rb_funcall(eStreamRESPError, ID_new, 1, msg);
   RB_GC_GUARD(msg);
   return err;
 }
@@ -264,7 +264,7 @@ VALUE resp_decode(struct um_stream *stream, VALUE out_buffer) {
     case ':': // integer
       return resp_decode_integer(ptr);
     case '(': // big integer
-      rb_raise(rb_eRuntimeError, "Big integers are not supported");
+      um_raise_internal_error("Big integers are not supported");
     case ',': // float
       return resp_decode_float(ptr);
 
@@ -274,7 +274,7 @@ VALUE resp_decode(struct um_stream *stream, VALUE out_buffer) {
       data_len = resp_parse_length_field(ptr, len);
       return resp_decode_error(stream, out_buffer, data_len);
     default:
-      rb_raise(rb_eRuntimeError, "Invalid character encountered");
+      um_raise_internal_error("Invalid character encountered");
   }
 
   RB_GC_GUARD(msg);
@@ -390,6 +390,6 @@ void resp_encode(struct um_write_buffer *buf, VALUE obj) {
         return;
       }
     default:
-      rb_raise(rb_eRuntimeError, "Can't encode object");
+      um_raise_internal_error("Can't encode object");
   }
 }

data/ext/um/um_stream_class.c

@@ -1,6 +1,7 @@
 #include "um.h"
 
 VALUE cStream;
+VALUE eStreamRESPError;
 
 static void Stream_mark(void *ptr) {
   struct um_stream *stream = ptr;
@@ -94,4 +95,6 @@ void Init_Stream(void) {
 
   rb_define_method(cStream, "resp_decode", Stream_resp_decode, 0);
   rb_define_singleton_method(cStream, "resp_encode", Stream_resp_encode, 2);
+
+  eStreamRESPError = rb_define_class_under(cStream, "RESPError", rb_eStandardError);
 }

data/ext/um/um_sync.c

@@ -56,44 +56,45 @@ void um_futex_wake_transient(struct um *machine, uint32_t *futex, uint32_t num_w
 
 void um_mutex_init(struct um_mutex *mutex) {
   mutex->state = MUTEX_UNLOCKED;
+  mutex->num_waiters = 0;
 }
 
-inline void um_mutex_lock(struct um *machine, uint32_t *state) {
-  while (*state == MUTEX_LOCKED) {
-    um_futex_wait(machine, state, MUTEX_LOCKED);
+inline void um_mutex_lock(struct um *machine, struct um_mutex *mutex) {
+  mutex->num_waiters++;
+  while (mutex->state == MUTEX_LOCKED) {
+    um_futex_wait(machine, &mutex->state, MUTEX_LOCKED);
   }
-  *state = MUTEX_LOCKED;
+  mutex->num_waiters--;
+  mutex->state = MUTEX_LOCKED;
 }
 
-inline void um_mutex_unlock(struct um *machine, uint32_t *state) {
-  *state = MUTEX_UNLOCKED;
-  // Wake up 1 waiting fiber
-  um_futex_wake(machine, state, 1);
+inline void um_mutex_unlock(struct um *machine, struct um_mutex *mutex) {
+  mutex->state = MUTEX_UNLOCKED;
+
+  if (mutex->num_waiters)
+    // Wake up 1 waiting fiber
+    um_futex_wake(machine, &mutex->state, 1);
 }
 
 struct sync_ctx {
   struct um *machine;
-  VALUE mutex;
-  uint32_t *state;
+  struct um_mutex *mutex;
 };
 
 VALUE synchronize_start(VALUE arg) {
   struct sync_ctx *ctx = (struct sync_ctx *)arg;
-  um_mutex_lock(ctx->machine, ctx->state);
+  um_mutex_lock(ctx->machine, ctx->mutex);
   return rb_yield(Qnil);
 }
 
 VALUE synchronize_complete(VALUE arg) {
   struct sync_ctx *ctx = (struct sync_ctx *)arg;
-  // Mutex is an embedded data class, so it might have moved while the operation
-  // was ongoing. We need to update the pointer to the embedded state variable.
-  ctx->state = &Mutex_data(ctx->mutex)->state;
-  um_mutex_unlock(ctx->machine, ctx->state);
+  um_mutex_unlock(ctx->machine, ctx->mutex);
   return Qnil;
 }
 
-inline VALUE um_mutex_synchronize(struct um *machine, VALUE mutex, uint32_t *state) {
-  struct sync_ctx ctx = { .machine = machine, .mutex = mutex, .state = state };
+inline VALUE um_mutex_synchronize(struct um *machine, struct um_mutex *mutex) {
+  struct sync_ctx ctx = { .machine = machine, .mutex = mutex };
   return rb_ensure(synchronize_start, (VALUE)&ctx, synchronize_complete, (VALUE)&ctx);
 }
 
@@ -228,7 +229,6 @@ enum queue_op { QUEUE_POP, QUEUE_SHIFT };
 
 struct queue_wait_ctx {
   struct um *machine;
-  VALUE queue_obj;
   struct um_queue *queue;
   enum queue_op op;
 };
@@ -242,9 +242,9 @@ VALUE um_queue_remove_start(VALUE arg) {
   }
 
   if (ctx->queue->state != QUEUE_READY)
-    rb_raise(rb_eRuntimeError, "Internal error: queue should be in ready state!");
+    um_raise_internal_error("Internal error: queue should be in ready state!");
   if (!ctx->queue->tail)
-    rb_raise(rb_eRuntimeError, "Internal error: queue should be in ready state!");
+    um_raise_internal_error("Internal error: queue should be in ready state!");
 
   ctx->queue->count--;
   return (ctx->op == QUEUE_POP ? queue_remove_tail : queue_remove_head)(ctx->queue);
@@ -252,11 +252,6 @@ VALUE um_queue_remove_start(VALUE arg) {
 
 VALUE um_queue_remove_complete(VALUE arg) {
   struct queue_wait_ctx *ctx = (struct queue_wait_ctx *)arg;
-
-  // the um_queue struct is embedded, so it might have been moved while the op
-  // was ongoing, so we need to get it again on op completion
-  ctx->queue = Queue_data(ctx->queue_obj);
-
   ctx->queue->num_waiters--;
 
   if (ctx->queue->num_waiters && ctx->queue->tail) {
@@ -270,11 +265,11 @@ VALUE um_queue_remove_complete(VALUE arg) {
 }
 
 VALUE um_queue_pop(struct um *machine, struct um_queue *queue) {
-  struct queue_wait_ctx ctx = { .machine = machine, .queue_obj = queue->self, .queue = queue, .op = QUEUE_POP };
+  struct queue_wait_ctx ctx = { .machine = machine, .queue = queue, .op = QUEUE_POP };
   return rb_ensure(um_queue_remove_start, (VALUE)&ctx, um_queue_remove_complete, (VALUE)&ctx);
 }
 
 VALUE um_queue_shift(struct um *machine, struct um_queue *queue) {
-  struct queue_wait_ctx ctx = { .machine = machine, .queue_obj = queue->self, .queue = queue, .op = QUEUE_SHIFT };
+  struct queue_wait_ctx ctx = { .machine = machine, .queue = queue, .op = QUEUE_SHIFT };
   return rb_ensure(um_queue_remove_start, (VALUE)&ctx, um_queue_remove_complete, (VALUE)&ctx);
 }

data/ext/um/um_utils.c

@@ -1,6 +1,7 @@
 #include "um.h"
 #include <sys/mman.h>
 #include <stdlib.h>
+#include <ruby/io/buffer.h>
 
 inline struct __kernel_timespec um_double_to_timespec(double value) {
   double integral;
@@ -32,35 +33,70 @@ inline void um_raise_on_error_result(int result) {
   if (unlikely(result < 0)) rb_syserr_fail(-result, strerror(-result));
 }
 
-inline void * um_prepare_read_buffer(VALUE buffer, unsigned len, int ofs) {
-  unsigned current_len = RSTRING_LEN(buffer);
-  if (ofs < 0) ofs = current_len + ofs + 1;
-  unsigned new_len = len + (unsigned)ofs;
-
-  if (current_len < new_len)
-    rb_str_modify_expand(buffer, new_len);
+inline void * um_prepare_read_buffer(VALUE buffer, ssize_t len, ssize_t ofs) {
+  if (TYPE(buffer) == T_STRING) {
+    size_t current_len = RSTRING_LEN(buffer);
+    if (len == -1) len = current_len;
+    if (ofs < 0) ofs = current_len + ofs + 1;
+    size_t new_len = len + (size_t)ofs;
+
+    if (current_len < new_len)
+      rb_str_modify_expand(buffer, new_len);
+    else
+      rb_str_modify(buffer);
+    return RSTRING_PTR(buffer) + ofs;
+  }
+  else if (IO_BUFFER_P(buffer)) {
+    void *base;
+    size_t size;
+    rb_io_buffer_get_bytes_for_writing(buffer, &base, &size); // writing *to* buffer
+    if (len == -1) len = size;
+    if (ofs < 0) ofs = size + ofs + 1;
+    size_t new_size = len + (size_t)ofs;
+
+    if (size < new_size) {
+      rb_io_buffer_resize(buffer, new_size);
+      rb_io_buffer_get_bytes_for_writing(buffer, &base, &size);
+    }
+    return base + ofs;
+  }
   else
-    rb_str_modify(buffer);
-  return RSTRING_PTR(buffer) + ofs;
+    um_raise_internal_error("Invalid buffer provided");
 }
 
-static inline void adjust_read_buffer_len(VALUE buffer, int result, int ofs) {
-  rb_str_modify(buffer);
-  unsigned len = result > 0 ? (unsigned)result : 0;
-  unsigned current_len = RSTRING_LEN(buffer);
-  if (ofs < 0) ofs = current_len + ofs + 1;
-  rb_str_set_len(buffer, len + (unsigned)ofs);
+static inline void adjust_read_buffer_len(VALUE buffer, int result, ssize_t ofs) {
+  if (TYPE(buffer) == T_STRING) {
+    rb_str_modify(buffer);
+    unsigned len = result > 0 ? (unsigned)result : 0;
+    unsigned current_len = RSTRING_LEN(buffer);
+    if (ofs < 0) ofs = current_len + ofs + 1;
+    rb_str_set_len(buffer, len + (unsigned)ofs);
+  }
+  else if (IO_BUFFER_P(buffer)) {
+    // do nothing?
+  }
 }
 
-inline void um_update_read_buffer(struct um *machine, VALUE buffer, int buffer_offset, __s32 result, __u32 flags) {
+inline void um_update_read_buffer(struct um *machine, VALUE buffer, ssize_t buffer_offset, __s32 result, __u32 flags) {
   if (!result) return;
 
   adjust_read_buffer_len(buffer, result, buffer_offset);
 }
 
+inline void um_get_buffer_bytes_for_writing(VALUE buffer, const void **base, size_t *size) {
+  if (TYPE(buffer) == T_STRING) {
+    *base = RSTRING_PTR(buffer);
+    *size = RSTRING_LEN(buffer);
+  }
+  else if (IO_BUFFER_P(buffer))
+    rb_io_buffer_get_bytes_for_reading(buffer, base, size); // reading *from* buffer
+  else
+    um_raise_internal_error("Invalid buffer provided");
+}
+
 int um_setup_buffer_ring(struct um *machine, unsigned size, unsigned count) {
   if (machine->buffer_ring_count == BUFFER_RING_MAX_COUNT)
-    rb_raise(rb_eRuntimeError, "Cannot setup more than BUFFER_RING_MAX_COUNT buffer rings");
+    um_raise_internal_error("Cannot setup more than BUFFER_RING_MAX_COUNT buffer rings");
 
   struct buf_ring_descriptor *desc = machine->buffer_rings + machine->buffer_ring_count;
   desc->buf_count = count;
@@ -72,7 +108,7 @@ int um_setup_buffer_ring(struct um *machine, unsigned size, unsigned count) {
     NULL, desc->br_size, PROT_READ | PROT_WRITE, MAP_ANONYMOUS | MAP_PRIVATE, 0, 0
   );
   if (mapped == MAP_FAILED)
-    rb_raise(rb_eRuntimeError, "Failed to allocate buffer ring");
+    um_raise_internal_error("Failed to allocate buffer ring");
 
   desc->br = (struct io_uring_buf_ring *)mapped;
   io_uring_buf_ring_init(desc->br);
@@ -88,7 +124,7 @@ int um_setup_buffer_ring(struct um *machine, unsigned size, unsigned count) {
   if (size > 0) {
     if (posix_memalign(&desc->buf_base, 4096, desc->buf_count * desc->buf_size)) {
       io_uring_free_buf_ring(&machine->ring, desc->br, desc->buf_count, bg_id);
-      rb_raise(rb_eRuntimeError, "Failed to allocate buffers");
+      um_raise_internal_error("Failed to allocate buffers");
     }
 
     void *ptr = desc->buf_base;
@@ -143,3 +179,7 @@ inline void um_add_strings_to_buffer_ring(struct um *machine, int bgid, VALUE st
   RB_GC_GUARD(converted);
   io_uring_buf_ring_advance(desc->br, count);
 }
+
+inline void um_raise_internal_error(const char *msg) {
+  rb_raise(eUMError, "UringMachine error: %s", msg);
+}

data/grant-2025/journal.md

@@ -0,0 +1,229 @@
+# 2025-11-14
+
+## Call with Samuel
+
+- I explained the tasks that I want to do:
+
+  1. FiberScheduler implementation for UringMachine
+  2. Async SSL I/O
+  3. Extend UringMachine & FiberScheduler with new functionality
+
+- Samuel talked about two aspects:
+
+  - Experimentation.
+  - Integrating and improving on existing ecosystem, publicly visible changes to
+    interfaces.
+
+So, improve on FiberScheduler interface, and show UringMachine as implementation.
+
+Suggestion for tasks around FiberScheduler from Samuel:
+
+1. Add Fiber::Scheduler#io_splice + IO-uring backing for IO.copy_stream
+
+Summary:
+
+Build an async-aware, zero-copy data-transfer path in Ruby by exposing Linux’s
+splice(2) through the Fiber Scheduler, and wiring it up so IO.copy_stream can
+take advantage of io_uring when available. Why it matters: Large file copies and
+proxying workloads become dramatically faster and cheaper because the data never
+touches user space. This gives Ruby a modern, high-performance primitive for
+bulk I/O.
+
+2. Add support for registered IO-uring buffers via IO::Buffer
+
+Summary:
+
+Integrate io_uring’s “registered buffers” feature with Ruby’s IO::Buffer,
+allowing pre-allocated, pinned buffers to be reused across operations.
+
+Why it matters:
+
+Drastically reduces syscalls and buffer management overhead. Enables fully
+zero-copy, high-throughput network servers and a more direct path to competitive
+I/O performance.
+
+3. Richer process APIs using pidfds (Fiber::Scheduler#process_open)
+
+Summary:
+
+Introduce pidfd-backed process primitives in Ruby so processes can be opened,
+monitored, and waited on safely through the scheduler.
+
+Why it matters:
+
+Pidfds eliminate race conditions, improve cross-thread safety, and make process
+management reliably asynchronous. This enables safer job-runners, supervisors,
+and async orchestration patterns in Ruby.
+
+4. Proper fork support for Fiber Scheduler (Fiber::Scheduler#process_fork)
+
+Summary:
+
+Define how fiber schedulers behave across fork: the child should start in a
+clean state, with hooks to reinitialize or discard scheduler data safely.
+
+Why it matters:
+
+fork + async currently work inconsistently. This project makes forking
+predictable, allowing libraries and apps to do post-fork setup (e.g., reconnect
+I/O, restart loops) correctly and safely.
+
+5. Async-aware IO#close via io_uring prep_close + scheduler hook
+
+Summary:
+
+Introduce a formal closing state in Ruby’s IO internals, add io_uring’s
+prep_close support, and provide Fiber::Scheduler#io_close as an official hook.
+
+Why it matters:
+
+Today, IO#close can be slow or unsafe to call in async contexts because it must
+run synchronously. This project allows deferred/batched closing, avoids races,
+and modernizes Ruby’s internal I/O lifecycle.
+
+GDB/LLDB extensions: https://github.com/socketry/toolbox
+
+# 2025-11-17
+
+## Work on io-event Uring selector
+
+I added an implementation of `process_wait` using `io_uring_prep_waitid`. This
+necessitates being able to create instances of `Process::Status`. For this, I've
+submitted a PR for exposing `rb_process_status_new`:
+https://github.com/ruby/ruby/pull/15213. Hopefully, this PR will be merged
+before the release of Ruby 4.0.
+
+# 2025-11-21
+
+## Work on UringMachine Fiber Scheduler
+
+I've finally made some progress on the UringMachine fiber scheduler. This was a
+process of learning the mchanics of how the scheduler is integrated with the
+Ruby I/O layer. Some interesting warts in the Ruby `IO` implementation:
+
+- When you call `Kernel.puts`, the trailing newline character is actually
+  written separately, which can lead to unexpected output if for example you
+  have multiple fibers writing to STDOUT at the same time. To prevent this, Ruby
+  uses a mutex (per IO instance) to synchronize writes to the same IO.
+- There are inconsistencies in how different kinds of IO objects are handled,
+  with regards to blocking/non-blocking operation
+  ([O_NONBLOCK](https://linux.die.net/man/2/fcntl)):
+
+  - Files and standard I/O are blocking.
+  - Pipes are non-blocking.
+  - Sockets are non-blocking.
+  - OpenSSL sockets are non-blocking.
+
+  The problem is that for io_uring to function properly, the fds passed to it
+  should always be in blocking mode. To rectify this, I've added code to the
+  fiber scheduler implementation that makes sure the IO instance is blocking:
+
+  ```ruby
+  def io_write(io, buffer, length, offset)
+    reset_nonblock(io)
+    @machine.write(io.fileno, buffer.get_string)
+  rescue Errno::EINTR
+    retry
+  end
+
+  def reset_nonblock(io)
+    return if @ios.key?(io)
+
+    @ios[io] = true
+    UM.io_set_nonblock(io, false)
+  end
+  ```
+
+- A phenomenon I've observed is that in some situations of multiple fibers doing
+  I/O, some of those I/O operations would raise an `EINTR`, which should mean
+  the I/O operation was interrupted because of a signal sent to the process.
+  Weird!
+
+- There's some interesting stuff going on when calling `IO#close`. Apparently
+  there's a mutex involved, and I noticed two scheduler hooks are being called:
+  `#blocking_operation_wait` which means a blocking operation that should be ran
+  on a separate thread, and `#block`, which means a mutex is being locked. I
+  still need to figure out what is going on there and why it is so complex.
+  FWIW, UringMachine has a `#close_async` method which, as its name suggests,
+  submits a close operation, but does not wait for it to complete.
+
+- I've added some basic documentation to the `FiberScheduler` class, and started
+  writing some tests. Now that I have a working fiber scheduler implementation
+  and I'm beginning to understand the mechanics of it, I can start TDD'ing...
+
+## Work on io-event Uring selector
+
+- I've submitted a [PR](https://github.com/socketry/io-event/pull/154) for using
+  `io_uring_prep_waitid` in the `process_wait` implementation. This relies on
+  having a recent Linux kernel (>=6.7) and the afore-mentioned Ruby
+  [PR](https://github.com/ruby/ruby/pull/15213) for exposing
+  `rb_process_status_new` being merged. Hopefully this will happen in time for
+  the Ruby 4.0 release.
+
+# 2025-11-26
+
+- Added some benchmarks for measuring mutex performance vs stock Ruby Mutex
+  class. It turns out the `UM#synchronize` was much slower than core Ruby
+  `Mutex#synchronize`. This was because the UM version was always performing a
+  futex wake before returning, even if no fiber was waiting to lock the mutex. I
+  rectified this by adding a `num_waiters` field to `struct um_mutex`, which
+  indicates the number of fibers currently waiting to lock the mutex, and
+  avoiding calling `um_futex_wake` if it's 0.
+
+- I also noticed that the `UM::Mutex` and `UM::Queue` classes were marked as
+  `RUBY_TYPED_EMBEDDABLE`, which means the underlying `struct um_mutex` and
+  `struct um_queue` were subject to moving. Obviously, you cannot just move a
+  futex var while the kernel is potentially waiting on it to change. I fixed
+  this by removing the `RUBY_TYPED_EMBEDDABLE` flag. This is a possible
+  explanation for the occasional segfaults I've been seeing in Syntropy when
+  doing lots of cancelled `UM#shift` ops (watching for file changes). (commit 3b013407ff94f8849517b0fca19839d37e046915)
+
+- Added support for `IO::Buffer` in all low-level I/O APIs, which also means the
+  fiber scheduler doesn't need to convert from `IO::Buffer` to strings in order
+  to invoke the UringMachine API. (commits
+  620680d9f80b6b46cb6037a6833d9cde5a861bcd,
+  16d2008dd052e9d73df0495c16d11f52bee4fd15,
+  4b2634d018fdbc52d63eafe6b0a102c0e409ebca,
+  bc9939f25509c0432a3409efd67ff73f0b316c61,
+  a9f38d9320baac3eeaf2fcb2143294ab8d115fe9)
+
+- Added a custom `UM::Error` exception class raised on bad arguments or other
+  API misuse. I've also added a `UM::Stream::RESPError` exception class to be
+  instantiated on RESP errors. (commit 72a597d9f47d36b42977efa0f6ceb2e73a072bdf)
+
+- I explored the fiber scheduler behaviour after forking. A fork done from a
+  thread where a scheduler was set will result in a main thread with the same
+  scheduler instantance. For the scheduler to work correctly after a fork, its
+  state must be reset. This is because sharing the same io_uring instance
+  between parent and child processes is not possible
+  (https://github.com/axboe/liburing/issues/612), and also because the child
+  process keeps only the fiber from which the fork was made as its main fiber
+  (the other fibers are lost).
+
+  So, the right thing to do here would be to add a `Fiber::Scheduler` hook that
+  will be invoked automatically by Ruby after a fork, and together with Samuel
+  I'll see if I can prepare a PR for that to be merged for the Ruby 4.0 release.
+
+  For the time being, I've added a `#post_fork` method to the UM fiber scheduler
+  which should be manually called after a fork. (commit 2c7877385869c6acbdd8354e2b2909cff448651b)
+
+- Added two new low-level APIs for waiting on processes, instead of
+  `UM#waitpid`, using the io_uring version of `waitid`. The vanilla version
+  `UM#waitid` returns an array containing the terminated process pid, exit
+  status and code. The `UM#waitid_status` method returns a `Process::Status`
+  with the pid and exit status. This method is present only if the
+  `rb_process_status_new` function is available (see above).
+
+- Implemented `FiberScheduler#process_wait` hook using `#waitid_status`.
+
+- For the sake of completeness, I also added `UM.pidfd_open` and
+  `UM.pidfd_send_signal` for working with PID. A simple example:
+
+  ```ruby
+  child_pid = fork { ... }
+  fd = UM.pidfd_open(child_pid)
+  ...
+  UM.pidfd_send_signal(fd, UM::SIGUSR1)
+  ...
+  pid2, status = machine.waitid(P_PIDFD, fd, UM::WEXITED)
+  ```

data/grant-2025/tasks.md

@@ -0,0 +1,66 @@
+- [v] io-event
+
+  - [v] Make PR to use io_uring_prep_waitid for kernel version >= 6.7
+
+    - https://github.com/socketry/io-event/blob/44666dc92ac3e093ca6ce3ab47052b808a58a325/ext/io/event/selector/uring.c#L460
+    - https://github.com/digital-fabric/uringmachine/blob/d5505d7fd94b800c848d186e17585e03ad9af6f2/ext/um/um.c#L697-L713
+
+- [ ] UringMachine
+  - [v] Add support for IO::Buffer in UM API. (How can we detect an IO::Buffer object?)
+        https://docs.ruby-lang.org/capi/en/master/d8/d36/group__object.html#gab1b70414d07e7de585f47ee50a64a86c
+
+  - [v] Add `UM::Error` class to be used instead of RuntimeError
+
+  - [ ] Do batch allocation for `struct um_op`, so they'll be adjacent
+  - [ ] Add optional buffer depth argument to `UM.new` (for example, a the
+    worker thread for the scheduler `blocking_operation_wait` hook does not need
+    a lot of depth, so you can basically do `UM.new(4)`)
+
+  - [ ] Add support for using IO::Buffer in association with io_uring registered buffers / buffer rings
+
+- [ ] FiberScheduler implementation
+4
+  - [v] Check how scheduler interacts with `fork`.
+  - [v] Implement `process_wait` (with `rb_process_status_new`)
+  - [ ] Implement timeouts (how do timeouts interact with blocking ops?)
+  - [ ] Implement address resolution hook
+  - [ ] Add tests:
+    - [ ] Sockets
+    - [ ] Files
+    - [ ] Mutex / Queue
+    - [ ] Thread.join
+    - [ ] Process.wait
+    - [ ] fork
+    - [ ] system / exec / etc.
+    - [ ] popen
+
+  - [ ] Benchmarks
+    - [ ] UM queue / Ruby queue (threads) / Ruby queue with UM fiber scheduler
+    - [ ] UM mutex / Ruby mutex (threads) / Ruby mutex with UM fiber scheduler
+    - [ ] Pipe IO raw UM / Ruby threaded / Ruby with UM fiber scheduler
+    - [ ] Socket IO (with socketpair) raw UM / Ruby threaded / Ruby with UM fiber scheduler
+    - [ ] Measure CPU (thread) time usage for above examples
+
+        - run each version 1M times
+        - measure total real time, total CPU time
+
+        ```ruby
+        real_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        cpu_time = Process.clock_gettime(Process::CLOCK_THREAD_CPUTIME_ID)
+        ```
+
+        - my hunch is we'll be able to show with io_uring real_time is less,
+          while cpu_time is more. But it's just a hunch.
+
+
+  - https://github.com/ruby/ruby/blob/master/doc/fiber.md
+  - https://github.com/ruby/ruby/blob/master/test/fiber/scheduler.rb
+  - https://github.com/socketry/async/blob/main/context/getting-started.md
+- https://github.com/socketry/async/blob/main/context/scheduler.md
+- https://github.com/socketry/async/blob/main/lib/async/scheduler.rb#L28
+
+- [ ] SSL
+  - [ ] openssl gem: custom BIO?
+
+    - curl: https://github.com/curl/curl/blob/5f4cd4c689c822ce957bb415076f0c78e5f474b5/lib/vtls/openssl.c#L786-L803
+