Adapt Rage's buffered I/O scheduler hooks to Ruby 4.1

[samuel-williams-shopify]

Hi — I wanted to share a heads-up about a change to the optional Fiber::Scheduler buffered I/O hooks in Ruby 4.1. It was merged into CRuby's default branch on August 25, 2026.

While checking scheduler implementations against ruby-head, I noticed that lib/rage/fiber_scheduler.rb uses the previous (length, offset) order. The read hook can pause and continue reading, while the write hook passes the whole buffer string together with the old length/offset interpretation, so both paths may behave differently under the new single-transfer contract.

References

• CRuby interface change: ruby/ruby#18483
• CRuby merge commit: ruby/ruby@44da9d7
• io-event compatibility implementation: socketry/io-event#211
• io-event asynchronous io_uring follow-up: socketry/io-event#213

Contract change

Hook	Ruby 4.0 and earlier	Ruby 4.1
io_read	io_read(io, buffer, length, offset)	io_read(io, buffer, offset, length)
io_write	io_write(io, buffer, length, offset)	io_write(io, buffer, offset, length)

Under scheduler interface v4, length is a maximum for one operation. Return a short result directly, return 0 for zero length, and on a readiness backend return -EAGAIN instead of waiting or retrying inside the hook.

One possible update for Rage

• defined?(IO::Buffer::VERSION) && IO::Buffer::VERSION >= 3 could select v4 versus legacy hook definitions.
• The v4 read path could make one bounded Iodine::Scheduler.read request for at most length bytes, copy a successful result to buffer at the requested buffer offset, and return the string's byte size.
• One detail worth checking is Iodine's third argument: the current code passes the buffer offset into Iodine::Scheduler.read, but the Ruby hook's offset refers only to the position within IO::Buffer. I may be missing an Iodine-specific convention here.
• Iodine's would-block result could return -Errno::EAGAIN::Errno directly, without the v4 loop or Fiber.pause retry.
• The v4 write path could extract exactly buffer.get_string(offset, length) and perform one write, passing a separate I/O offset only if the Iodine API requires one.
• A zero-length request could return 0 before calling Iodine, while the existing implementation remains available in the older-interface branch.

The public C/native version gate is RUBY_FIBER_SCHEDULER_VERSION >= 4; IO::Buffer::VERSION >= 3 is the corresponding Ruby-level check.

If this reading of the Iodine API is correct, I would be happy to help prepare or test a patch. Useful Ruby-head cases would use different nonzero offset and length values, plus short-transfer, would-block, and zero-length operations. If Ruby 4.1 is not currently in scope, please feel free to close this.

[rsamoilov]

Hi Samuel,

Thank you so much for the heads-up and such a detailed explanation!

One interesting challenge here is the io_write hook - currently, Rage uses Iodine::Scheduler.write, which only schedules the write and flushes it later. In Rage, io_write is mostly used for log writes, so despite the approach breaks the fiber scheduler contract in theory, it works fine in practice. However, considering the changes in Ruby 4.1, I want to change this approach (and then backport it to 3.4+) so that the write happens immediately and can return a native short-write count or EAGAIN.

Looking at io-event, for v4 you just do one synchronous write(), which looks great. Another idea I had for Iodine::Scheduler.write was calling write() via rb_nogvl+RB_NOGVL_OFFLOAD_SAFE so that large file writes don't stall the reactor, but it currently introduces more problems than it solves - we would then need to update Rage.logger to skirt io_write because having every tiny log write go through blocking_operation_wait sinks the performance.

For the first iteration though, updating the scheduler to support the v4 interface is a good start. Please let me know if you'd like to prepare a patch - that would be amazing. Otherwise, I'll open a PR next week and would be happy if you could review.

One detail worth checking is Iodine's third argument: the current code passes the buffer offset into Iodine::Scheduler.read, but the Ruby hook's offset refers only to the position within IO::Buffer

It's currently a no-op - it's there just in case it's needed later.

[samuel-williams-shopify]

It's okay for io_read and io_write to do scheduled operations - they should be equivalent to calling read(2) or write(2) - and if you want to have a non-blocking read/write followed by an asynchronous read/write, that would be acceptable.

[rsamoilov]

Opened #397. Thanks again!