uringmachine 0.20.0 → 0.21.0

data/grant-2025/tasks.md

@@ -1,38 +1,83 @@
 - [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
-
+- [ ] UringMachine low-level API
+  - [v] Add support for IO::Buffer in UM API.
   - [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
+  - [v] Add optional ring size 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] Add debugging code suggested by Samuel
+  - [v] Add support for SQPOLL
+        https://unixism.net/loti/tutorial/sq_poll.html
+
+  - [ ] Add support for using IO::Buffer in association with io_uring registered
+    buffers / buffer rings
+  - [ ] Set `IOSQE_CQE_SKIP_SUCCESS` flag for `#close_async` and `#write_async`
+  - [ ] In `UM#spin` always start fibers as non-blocking.
+  - [ ] Add some way to measure fiber CPU time.
+        https://github.com/socketry/async/issues/428
+
+- [ ] UringMachine Fiber::Scheduler implementation
   - [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
+  - [v] Implement `fiber_interrupt` hook
+  - [v] Add `#address_resolve` hook with same impl as Async:
+        https://github.com/socketry/async/blob/ea8b0725042b63667ea781d4d011786ca3658256/lib/async/scheduler.rb#L285-L296
+  - [v] Implement other hooks:
+    - [v] `#timeout_after`
+          https://github.com/socketry/async/blob/ea8b0725042b63667ea781d4d011786ca3658256/lib/async/scheduler.rb#L631-L644
+    - [v] `#io_pread`
+    - [v] `#io_pwrite`
+    - [v] `#io_select`
+    - [v] Add timeout handling in different I/O hooks
+  - [v] Experiment more with fork:
+    - [v] what happens to schedulers on other threads (those that don't make it post-fork)
+          - do they get GC'd?
+          - do they get closed (`#scheduler_close` called)?
+          - are they freed cleanly (at least for UM)?
+
+          ```ruby
+          class S
+            def respond_to?(sym) = true
+          end
+          o = S.new
+          ObjectSpace.define_finalizer(o, ->(*){ puts 'scheduler finalized' })
+          t1 = Thread.new { Fiber.set_scheduler(o); sleep }
+          t2 = Thread.new {
+            fork { p(t1:, t2:) }
+            GC.start
+          }
+
+          # output:
+          # scheduler finalized
+          ```
+
+          So, apparently there's no problem!
+  - [v] Implement multi-thread worker pool for `blocking_operation_wait`
+        Single thread pool at class level, shared by all schedulers
+        With worker count according to CPU count
+  - [v] Test working with non-blocking files, it should be fine, and we shouldn't need to reset `O_NONBLOCK`.
+  - [v] Implement timeouts (how do timeouts interact with blocking ops?)
+  - [ ] Implement `#yield` hook (https://github.com/ruby/ruby/pull/14700)
+  - [ ] Finish documentation for the `FiberScheduler` class.
+
+  - [v] tests:
+    - [v] Wrap the scheduler interface such that we can verify that specific
+      hooks were called. Add asserts for called hooks for all tests.
+    - [v] Sockets (only io_wait)
+    - [v] Files
+    - [v] Mutex / Queue
+    - [v] Thread.join
+    - [v] Process.wait
+    - [v] fork
+    - [v] system / exec / etc.
+    - [v] popen
+  - [ ] "Integration tests"
+    - [ ] queue: multiple concurrent readers / writers
+    - [ ] net/http test: ad-hoc HTTP/1.1 server + `Net::HTTP` client
+    - [ ] sockets: echo server + many clients
+    - [ ] IO - all methods!
 
   - [ ] Benchmarks
     - [ ] UM queue / Ruby queue (threads) / Ruby queue with UM fiber scheduler
@@ -52,15 +97,39 @@
         - 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
+- [ ] Ruby Fiber::Scheduler interface
+  - [ ] Make a PR for resetting the scheduler and resetting the fiber non-blocking flag.
+  - [ ] Missing hook for close
+  - [ ] Missing hooks for send/recv/sendmsg/recvmsg
+  - [ ] Writes to a file (including `IO.write`) do not invoke `#io_write` (because writes to files cannot be non-blocking?) Instead, `blocking_operation_wait` is invoked.
 
 - [ ] SSL
   - [ ] openssl gem: custom BIO?
 
     - curl: https://github.com/curl/curl/blob/5f4cd4c689c822ce957bb415076f0c78e5f474b5/lib/vtls/openssl.c#L786-L803
 
+- [ ] UringMachine website
+  - [ ] domain: uringmachine.dev
+  - [ ] logo: ???
+  - [ ] docs (similar to papercraft docs)
+
+- [ ] Uma - web server
+  - [ ] child process workers
+  - [ ] reforking (following https://github.com/Shopify/pitchfork)
+        see also: https://byroot.github.io/ruby/performance/2025/03/04/the-pitchfork-story.html
+        - Monitor worker memory usage - how much is shared
+        - Choose worker with most served request count as "mold" for next generation
+        - Perform GC out of band, preferably when there are no active requests
+          https://railsatscale.com/2024-10-23-next-generation-oob-gc/
+        - When a worker is promoted to "mold", it:
+          - Stops `accept`ing requests
+          - When finally idle, calls `Process.warmup`
+          - Starts replacing sibling workers with forked workers
+        see also: https://www.youtube.com/watch?v=kAW5O2dkSU8
+  - [ ] Each worker is single-threaded (except for auxiliary threads)
+  - [ ] Rack 3.0-compatible
+        see: https://github.com/socketry/protocol-rack
+  - [ ] Rails integration (Railtie)
+        see: https://github.com/socketry/falcon
+  - [ ] Benchmarks
+  - [ ] Add to the TechEmpower bencchmarks

data/lib/uringmachine/fiber_scheduler.rb

@@ -1,10 +1,65 @@
 # frozen_string_literal: true
 
+require 'resolv'
+require 'etc'
+
 class UringMachine
+  # Implements a thread pool for running blocking operations.
+  class BlockingOperationThreadPool
+    def initialize
+      @blocking_op_queue = UM::Queue.new
+      @pending_count = 0
+      @worker_count = 0
+      @max_workers = Etc.nprocessors
+      @worker_mutex = UM::Mutex.new
+      @workers = []
+    end
+
+    def process(machine, job)
+      queue = UM::Queue.new
+
+      if @worker_count == 0 || (@pending_count > 0 && @worker_count < @max_workers)
+        start_worker(machine)
+      end
+      machine.push(@blocking_op_queue, [queue, job])
+      machine.shift(queue)
+    end
+
+    private
+
+    def start_worker(machine)
+      machine.synchronize(@worker_mutex) do
+        return if @worker_count == @max_workers
+
+        @workers << Thread.new { run_worker_thread }
+        @worker_count += 1
+      end
+    end
+
+    def run_worker_thread
+      machine = UM.new(4).mark(1)
+      loop do
+        q, op = machine.shift(@blocking_op_queue)
+        @pending_count += 1
+        res = begin
+          op.()
+        rescue Exception => e
+          e
+        end
+        @pending_count -= 1
+        machine.push(q, res)
+      rescue => e
+        UM.debug("worker e: #{e.inspect}")
+      end
+    end
+  end
+
   # UringMachine::FiberScheduler implements the Fiber::Scheduler interface for
   # creating fiber-based concurrent applications in Ruby, in tight integration
   # with the standard Ruby I/O and locking APIs.
   class FiberScheduler
+    @@blocking_operation_thread_pool = BlockingOperationThreadPool.new
+
     attr_reader :machine, :fiber_map
 
     # Instantiates a scheduler with the given UringMachine instance.
@@ -17,7 +72,6 @@ class UringMachine
     # @return [void]
     def initialize(machine = nil)
       @machine = machine || UM.new
-      @ios = ObjectSpace::WeakMap.new
       @fiber_map = ObjectSpace::WeakMap.new
     end
 
@@ -29,9 +83,8 @@ class UringMachine
     # automatically after a fork).
     #
     # @return [self]
-    def post_fork
+    def process_fork
       @machine = UM.new
-      @ios = ObjectSpace::WeakMap.new
       @fiber_map = ObjectSpace::WeakMap.new
       self
     end
@@ -51,11 +104,6 @@ class UringMachine
       join()
     end
 
-    # fiber_interrupt hook: to be implemented.
-    def fiber_interrupt(fiber, exception)
-      raise NotImplementedError, "Implement me!"
-    end
-
     # For debugging purposes
     def p(o) = UM.debug(o.inspect)
 
@@ -79,11 +127,18 @@ class UringMachine
     # @param blocking_operation [callable] blocking operation
     # @return [void]
     def blocking_operation_wait(blocking_operation)
-      start_blocking_operation_thread if !@blocking_op_queue
+      # naive_blocking_peration_wait(blocking_operation)
+      @@blocking_operation_thread_pool.process(@machine, blocking_operation)
+    end
 
-      queue = UM::Queue.new
-      @machine.push(@blocking_op_queue, [queue, blocking_operation])
-      @machine.shift(queue)
+    def naive_blocking_peration_wait(blocking_operation)
+      res = nil
+      Thread.new do
+        res = blocking_operation.()
+      rescue => e
+        res = e
+      end.join
+      res
     end
 
     # block hook: blocks the current fiber by yielding to the machine. This hook
@@ -92,11 +147,17 @@ class UringMachine
     #
     # @param blocker [any] blocker object
     # @param timeout [Number, nil] optional
-    # timeout @return [void]
+    # timeout @return [bool] was the operation successful
     def block(blocker, timeout = nil)
-      raise NotImplementedError, "Implement me!" if timeout
+      if timeout
+        @machine.timeout(timeout, Timeout::Error) { @machine.yield }
+      else
+        @machine.yield
+      end
 
-      @machine.yield
+      true
+    rescue Timeout::Error
+      false
     end
 
     # unblock hook: unblocks the given fiber by scheduling it. This hook is
@@ -108,6 +169,7 @@ class UringMachine
     # @return [void]
     def unblock(blocker, fiber)
       @machine.schedule(fiber, nil)
+      @machine.wakeup
     end
 
     # kernel_sleep hook: sleeps for the given duration.
@@ -132,15 +194,28 @@ class UringMachine
       timeout ||= io.timeout
       if timeout
         @machine.timeout(timeout, Timeout::Error) {
-          @machine.poll(io.fileno, events).tap { p 3 }
+          @machine.poll(io.fileno, events)
         }
       else
-        @machine.poll(io.fileno, events).tap { p 6 }
+        @machine.poll(io.fileno, events)
+      end
+    end
+
+    def io_select(rios, wios, eios, timeout = nil)
+      map_r = map_io_fds(rios)
+      map_w = map_io_fds(wios)
+      map_e = map_io_fds(eios)
 
+      r, w, e = nil
+      if timeout
+        @machine.timeout(timeout, Timeout::Error) {
+          r, w, e = @machine.select(map_r.keys, map_w.keys, map_e.keys)
+        }
+      else
+        r, w, e = @machine.select(map_r.keys, map_w.keys, map_e.keys)
       end
-    rescue => e
-      p e: e
-      raise
+
+      [unmap_fds(r, map_r), unmap_fds(w, map_w), unmap_fds(e, map_e)]
     end
 
     # fiber hook: creates a new fiber with the given block. The created fiber is
@@ -156,6 +231,53 @@ class UringMachine
       fiber
     end
 
+    # io_read hook: reads from the given IO.
+    #
+    # @param io [IO] IO object
+    # @param buffer [IO::Buffer] read buffer
+    # @param length [Integer] read length
+    # @param offset [Integer] buffer offset
+    # @return [Integer] bytes read
+    def io_read(io, buffer, length, offset)
+      length = buffer.size if length == 0
+
+      if (timeout = io.timeout)
+				@machine.timeout(timeout, Timeout::Error) do
+          @machine.read(io.fileno, buffer, length, offset)
+        rescue Errno::EINTR
+          retry
+        end
+      else
+        @machine.read(io.fileno, buffer, length, offset)
+      end
+    rescue Errno::EINTR
+      retry
+    end
+
+    # io_pread hook: reads from the given IO at the given offset
+    #
+    # @param io [IO] IO object
+    # @param buffer [IO::Buffer] read buffer
+    # @param from [Integer] read offset
+    # @param length [Integer] read length
+    # @param offset [Integer] buffer offset
+    # @return [Integer] bytes read
+    def io_pread(io, buffer, from, length, offset)
+      length = buffer.size if length == 0
+
+      if (timeout = io.timeout)
+				@machine.timeout(timeout, Timeout::Error) do
+          @machine.read(io.fileno, buffer, length, offset, from)
+        rescue Errno::EINTR
+          retry
+        end
+      else
+        @machine.read(io.fileno, buffer, length, offset, from)
+      end
+    rescue Errno::EINTR
+      retry
+    end
+
     # io_write hook: writes to the given IO.
     #
     # @param io [IO] IO object
@@ -164,72 +286,77 @@ class UringMachine
     # @param offset [Integer] write offset
     # @return [Integer] bytes written
     def io_write(io, buffer, length, offset)
-      if offset > 0
-        raise NotImplementedError, "UringMachine currently does not support writing at an offset"
-      end
+      # p(io_write: io, length:, offset:, timeout: io.timeout)
+      length = buffer.size if length == 0
+      buffer = buffer.slice(offset) if offset > 0
 
-      ensure_nonblock(io)
-      @machine.write(io.fileno, buffer)
+      if (timeout = io.timeout)
+				@machine.timeout(timeout, Timeout::Error) do
+          @machine.write(io.fileno, buffer, length)
+        rescue Errno::EINTR
+          retry
+        end
+      else
+        @machine.write(io.fileno, buffer, length)
+      end
     rescue Errno::EINTR
       retry
     end
 
-    # io_read hook: reads from the given IO.
+    # io_pwrite hook: writes to the given IO at the given offset.
     #
     # @param io [IO] IO object
-    # @param buffer [IO::Buffer] read buffer
-    # @param length [Integer] read length
-    # @param offset [Integer] read offset
-    # @return [Integer] bytes read
-    def io_read(io, buffer, length, offset)
-      if offset > 0
-        raise NotImplementedError, "UringMachine currently does not support reading at an offset"
-      end
-
-      ensure_nonblock(io)
+    # @param buffer [IO::Buffer] write buffer
+    # @param length [Integer] file offset
+    # @param length [Integer] write length
+    # @param offset [Integer] buffer offset
+    # @return [Integer] bytes written
+    def io_pwrite(io, buffer, from, length, offset)
+      # p(io_pwrite: io, from:, length:, offset:, timeout: io.timeout)
       length = buffer.size if length == 0
-      @machine.read(io.fileno, buffer, length)
+      buffer = buffer.slice(offset) if offset > 0
+
+      if (timeout = io.timeout)
+				@machine.timeout(timeout, Timeout::Error) do
+          @machine.write(io.fileno, buffer, length, from)
+        rescue Errno::EINTR
+          retry
+        end
+      else
+        @machine.write(io.fileno, buffer, length, from)
+      end
     rescue Errno::EINTR
       retry
     end
 
-    if UM.instance_methods.include?(:waitid_status)
+    if UM.method_defined?(:waitid_status)
       def process_wait(pid, flags)
         flags = UM::WEXITED if flags == 0
         @machine.waitid_status(UM::P_PID, pid, flags)
       end
     end
 
-    private
+    def fiber_interrupt(fiber, exception)
+      @machine.schedule(fiber, exception)
+      @machine.wakeup
+    end
 
-    # Ensures the given IO is in blocking mode.
-    #
-    # @param io [IO] IO object
-    # @return [void]
-    def ensure_nonblock(io)
-      return if @ios.key?(io)
+		def address_resolve(hostname)
+			Resolv.getaddresses(hostname)
+		end
 
-      @ios[io] = true
-      UM.io_set_nonblock(io, false)
+    def timeout_after(duration, exception, message, &block)
+      @machine.timeout(duration, exception, &block)
     end
 
-    # Starts a background thread for running blocking operations.
-    #
-    # @return [void]
-    def start_blocking_operation_thread
-      @blocking_op_queue = UM::Queue.new
-      @blocking_op_thread = Thread.new do
-        m = UM.new
-        loop do
-          q, op = m.shift(@blocking_op_queue)
-          res = begin
-            op.()
-          rescue Exception => e
-            e
-          end
-          m.push(q, res)
-        end
-      end
+    private
+
+    def map_io_fds(ios)
+      ios.each_with_object({}) { |io, h| h[io.fileno] = io }
+    end
+
+    def unmap_fds(fds, map)
+      fds.map { map[it] }
     end
 
   end

data/lib/uringmachine/version.rb

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