uringmachine 0.4 → 0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a9efd4af7de9fdb8db6888b9f6347e9dbc63aae9e26fa0f81d43984d265bd90
-  data.tar.gz: 5289699ce1e3e173d3766e0211fc77b57f3c123e2a6e041e9e751a3bf5ce07b2
+  metadata.gz: 2067cd0f88d6dbc341410ca6911916f510132ee23ce3f6d5fb5978259eeaef11
+  data.tar.gz: f816a9478f714a3a9770740bc14fc03ae2687f2fe7d0e29cbc0b8632994bad1f
 SHA512:
-  metadata.gz: 3cf02bbaae5a9e19b9ea994d1c2bf4b327a96121b083ca6756eca70629738f6c24aca10096bb49a0400678542232062969889ed3f0773591f5dc71f718707fef
-  data.tar.gz: 67b368097ddecd6c9ca9ce360cc918d8e7de91ec83a00d617765c2026fbe08f16f5009b78323e9f314cd1df63a1baaa39e8887b4a90fff0cb8010d810276df7d
+  metadata.gz: 6e0a9ed6e6f131bf6d67a56622786893532a525f4427e134670499997c0461a4df6de3ca1cb9e70851769c1135575986468a83edfd9b5d75c7d592e41bb0ca8c
+  data.tar.gz: 2c73ed9a3268ea96b3a167064251d16279c531ee50e5f9c6de9aa2c56f6a70973ef04ce5d6c44f46e39309f7bf8cb3f3ff5e61bf1512ca07cc5f35b91f7303dc

data/.github/workflows/test.yml

@@ -32,4 +32,5 @@ jobs:
     - name: Compile C-extension
       run: bundle exec rake compile
     - name: Run tests
-      run:  bundle exec rake test
+      # run: bundle exec ruby test/test_um.rb --name test_read_each_raising_2
+      run: bundle exec rake test

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+# 2024-11-14 Version 0.5
+
+- Add `#waitpid`
+- Add `UM.pipe`, `UM.kernel_version`
+- Add `#open`
+- Fix `#spin`
+- Fix handling of signal interruption.
+- Reimplement and simplify um_op
+- Add `UM::Queue`, `#push`, `#pop`, `#shift`, `#unshift`
+- Add `UM::Mutex`, `#synchronize`
+- Add `#recv_each`
+- Add `#getsockopt`, `#setsockopt`
+- Simplify and improve op management
+
 # 2024-10-06 Version 0.4
 
 - Add socket constants

data/README.md

@@ -32,6 +32,8 @@ UringMachine is based on my experience marrying Ruby and io_uring:
 - [IOU](https://github.com/digital-fabric/iou) - a low-level asynchronous API
   for using io_uring from Ruby.
 
+### Learnings
+
 Some important learnings from those two projects, in no particular order:
 
 - Monkey-patching is not a good solution, long term. You need to deal with
@@ -73,7 +75,25 @@ based on the following principles:
 - Do not insist on structured concurrency, just provide the APIs necessary to
   create actors and to supervise the execution of fibers.
 
-## Example
+### Cancellation
+
+When working with io_uring, managing the life cycle of asynchronous operations
+is quite tricky, especially with regards to cancellation. This is due to the
+fact each operation lives on both sides of the userspace-kernel divide. This
+means that when cancelling an operation, we cannot free, or dispose of any
+resources associated with the operation, until we know for sure that the kernel
+side is also done with the operation.
+
+As stated above, working with fibers allows us to keep operation metadata and
+associated data (such as buffers etc) on the stack, which can greatly simplify
+the managing of the operation's lifetime, as well as significantly reduce heap
+allocations.
+
+When a cancellation does occur, UringMachine issues a cancellation (using
+`io_uring_prep_cancel64`), and then waits for the corresponding CQE (with a
+`-ECANCELED` result).
+
+## Short Example
 
 ```ruby
 require 'uringmachine'
@@ -94,3 +114,26 @@ loop do
   end
 end
 ```
+
+## Concurrent Execution
+
+Concurrent execution is done by calling `#spin`, which creates a fiber:
+
+```ruby
+machine = UringMachine.new
+
+rfd, wfd = machine.pipe
+
+f1 = machine.spin do
+  machine.write(wfd, 'hello')
+  machine.write(wfd, 'world')
+  machine.close(wfd)
+end
+
+bgid = machine.setup_buffer_ring(4096, 1024)
+f2 = machine.spin do
+  machine.read_each(rfd, bgid) do |str|
+    puts str
+  end
+end
+```

data/TODO.md

@@ -1,5 +1,14 @@
-- splice
+- splice / - tee
 - sendto
 - recvfrom
-
-- queues
+- poll_add / poll_remove / poll_multishot / poll_update
+- fsync
+- mkdir / mkdirat
+- statx
+- link / linkat / unlink / unlinkat / symlink
+- rename / renameat
+- fadvise
+- madvise
+- getxattr / setxattr
+- shutdown
+- send_bundle / recv_bundle (kernel >= 6.10)

data/examples/bm_snooze.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'uringmachine', path: '..'
+  gem 'benchmark-ips'
+end
+
+require 'benchmark/ips'
+require 'uringmachine'
+
+ITERATIONS = 1000
+
+$machine = UringMachine.new
+
+def run_snooze
+  count = 0
+  main = Fiber.current
+
+  f1 = Fiber.new do
+    loop do
+      count += 1
+      if count == ITERATIONS
+        $machine.schedule(main, nil)
+        break
+      else
+        $machine.snooze
+      end
+    end
+  end
+
+  f2 = Fiber.new do
+    loop do
+      count += 1
+      if count == ITERATIONS
+        $machine.schedule(main, nil)
+        break
+      else
+        $machine.snooze
+      end
+    end
+  end
+
+  $machine.schedule(f1, nil)
+  $machine.schedule(f2, nil)
+  $machine.yield
+end
+
+def run_raw_transfer
+  count = 0
+  main = Fiber.current
+  f2 = nil
+  f1 = Fiber.new do
+    loop do
+      count += 1
+      if count == ITERATIONS
+        main.transfer(nil)
+        break
+      else
+        f2.transfer(nil)
+      end
+    end
+  end
+
+  f2 = Fiber.new do
+    loop do
+      count += 1
+      if count == ITERATIONS
+        main.transfer(nil)
+        break
+      else
+        f1.transfer(nil)
+      end
+    end
+  end
+
+  f1.transfer(nil)
+end
+
+bm = Benchmark.ips do |x|
+  x.config(:time => 5, :warmup => 2)
+
+  x.report("snooze")        { run_snooze }
+  x.report("raw transfer")  { run_raw_transfer }
+
+  x.compare!
+end

data/examples/bm_write.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'uringmachine', path: '..'
+  gem 'benchmark'
+end
+
+require 'benchmark'
+require 'uringmachine'
+
+ITERATIONS = 100000
+BUF = ('*' * 8192).freeze
+FN = '/tmp/bm_write'
+
+def run_io_write(num_threads)
+  FileUtils.rm(FN) rescue nil
+  fio = File.open(FN, 'w')
+  
+  threads = num_threads.times.map do |i|
+    Thread.new do
+      ITERATIONS.times { fio.write(BUF) }
+    end
+  end
+  threads.each(&:join)
+ensure
+  fio.close
+end
+
+def run_um_write(num_fibers)
+  FileUtils.rm(FN) rescue nil
+  fio = File.open(FN, 'w')
+  fd = fio.fileno
+  
+  machine = UringMachine.new
+  done = UringMachine::Queue.new
+  num_fibers.times do
+    machine.spin do
+      ITERATIONS.times { machine.write(fd, BUF) }
+      machine.push(done, true) 
+    end
+  end
+  num_fibers.times { machine.pop(done) }
+ensure
+  fio.close
+end
+
+Benchmark.bm do |x|
+  [1, 2, 4, 8].each do |c|
+    x.report("IO (#{c} threads)")     { run_io_write(c) }
+    x.report("UM (#{c} fibers) ")     { run_um_write(c) }
+    puts
+  end
+end

data/examples/dns_client.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative '../lib/uringmachine'
+require 'resolv'
+
+machine = UM.new
+
+addrs = machine.resolve('status.realiteq.net')
+
+puts '*' * 40
+puts addrs.join("\n")
+puts

data/examples/http_server.rb

@@ -1,56 +1,55 @@
-require_relative '../lib/iou'
-require 'socket'
+# frozen_string_literal: true
+
+require_relative '../lib/uringmachine'
 require 'http/parser'
 
-def log(msg)
-  # return
-  STDERR.puts msg
-end
+@machine = UM.new
+@bgid = @machine.setup_buffer_ring(4096, 1024)
 
-socket = TCPServer.open('127.0.0.1', 1234)
-log 'Listening on port 1234...'
+def http_handle_connection(fd)
+  # puts "Accepting connection on fd #{fd}"
+  parser = Http::Parser.new
+  done = nil
+  parser.on_message_complete = -> do
+    http_send_response(fd, "Hello, world!\n")
+    done = true
+  end
 
-@ring = IOU::Ring.new
-@bg_id = @ring.setup_buffer_ring(count: 1024, size: 4096)
+  @machine.read_each(fd, @bgid) do
+    parser << _1
+    break if done
+  end
 
-@ring.prep_accept(fd: socket.fileno, multishot: true) do |c|
-  setup_connection(c[:result]) if c[:result] > 0
+  # puts "Connection closed on fd #{fd}"
+rescue => e
+  # puts "Error while handling connection on fd #{fd}: #{e.inspect}"
+ensure
+  @machine.close(fd) rescue nil
 end
 
-def setup_connection(fd)
-  log "Connection accepted fd #{fd}"
-
-  parser = Http::Parser.new
-  parser.on_message_complete = -> {
-    http_send_response(fd, "Hello, world!\n") do
-      @ring.prep_close(fd: fd)
-    end
-  }
-
-  http_prep_read(fd, parser)
+def http_send_response(fd, body)
+  # msg = "HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nConnection: keep-alive\r\nContent-Length: #{body.bytesize}\r\n\r\n#{body}"
+  msg = "HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nConnection: close\r\nContent-Length: #{body.bytesize}\r\n\r\n#{body}"
+  @machine.write(fd, msg)
 end
 
-def http_prep_read(fd, parser)
-  buffer = +''
-  @ring.prep_read(fd: fd, buffer: buffer, len: 4096) do |c|
-    if c[:result] > 0
-      http_prep_read(fd, parser)
-      parser << buffer
-    elsif c[:result] == 0
-      log "Connection closed by client on fd #{fd}"
-    else
-      log "Got error #{c[:result]} on fd #{fd}, closing connection..."
-      @ring.prep_close(fd: fd) do |c|
-        log "Connection closed on fd #{fd}, result #{c[:result]}"
-      end
-    end
+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', 1234)
+@machine.listen(server_fd, UM::SOMAXCONN)
+puts 'Listening on port 1234'
+
+@machine.spin do
+  @machine.accept_each(server_fd) do |fd|
+    @machine.spin(fd) { http_handle_connection _1 }
   end
 end
 
-def http_send_response(fd, body)
-  msg = "HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nConnection: keep-alive\r\nContent-Length: #{body.bytesize}\r\n\r\n#{body}"
-  @ring.prep_write(fd: fd, buffer: msg)
-end
+main = Fiber.current
+trap('SIGINT') { @machine.schedule(main, nil) }
+trap('SIGTERM') { @machine.schedule(main, nil) }
 
-trap('SIGINT') { exit! }
-@ring.process_completions_loop
+@machine.yield
+puts "Closing server FD"
+@machine.close(server_fd) rescue nil
+puts "done!"

data/examples/server_client.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative '../lib/uringmachine'
+
+PORT = 1234
+
+@machine = UM.new
+@bgid = @machine.setup_buffer_ring(4096, 1024)
+
+@counter = 0
+
+def handle_connection(fd)
+  buf = +''
+  loop do
+    res = @machine.recv(fd, buf, 8192, 0)
+    break if res == 0
+
+    @machine.write(fd, buf)
+    @counter += 2
+  end
+ensure
+  @machine.close(fd) rescue nil
+end
+
+def run_client
+  fd = @machine.socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
+  @machine.connect(fd, '127.0.0.1', PORT)
+  msg = 'foo' * 30
+  buf = +''
+  loop do
+    @machine.send(fd, msg, msg.bytesize, 0)
+    res = @machine.recv(fd, buf, 8192, 0)
+    @counter += 2
+    
+    break if res == 0
+    raise "Got #{res} bytes instead of #{msg.bytesize}" if res != msg.bytesize
+  end
+end
+
+trap('SIGINT') { exit }
+
+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)
+puts "Listening on port #{PORT}"
+
+at_exit { @machine.close(server_fd) rescue nil }
+
+20.times do
+  @machine.spin { run_client }
+end
+
+@machine.spin do
+  @machine.accept_each(server_fd) do |fd|
+    @machine.spin(fd) { handle_connection _1 }
+  end
+end
+
+t0 = Time.now
+@machine.sleep 3
+t1 = Time.now  
+elapsed = t1 - t0
+puts "Did #{@counter} ops in #{elapsed} seconds (#{(@counter / elapsed)} ops/s)"

data/examples/snooze.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative '../lib/uringmachine'
+
+@machine = UM.new
+
+@counter = 0
+@fiber_count = 0
+
+def start_fiber
+  @fiber_count += 1
+  @machine.spin do
+    max_count = @counter + rand(1000)
+    puts "Start #{Fiber.current} #{max_count - @counter}"
+    loop do
+      @machine.sleep 0.001
+      @counter += 1
+      break if @counter >= max_count
+    end
+    puts "Stop #{Fiber.current}"
+  ensure
+    @fiber_count -= 1
+  end
+end
+
+t0 = Time.now
+MAX_FIBERS = 20
+MAX_TIME = 10
+loop do
+  @machine.sleep 0.1
+  puts "pending: #{@machine.pending_count}"
+  break if (Time.now - t0) > MAX_TIME
+  start_fiber while @fiber_count < MAX_FIBERS
+end
+t1 = Time.now  
+elapsed = t1 - t0
+rate = @counter / elapsed
+puts "Did #{@counter} ops in #{elapsed} seconds (#{rate} ops/s)"
+
+puts "Waiting for fibers... (#{@fiber_count})"
+while @fiber_count > 0
+  @machine.sleep 0.1
+end
+puts "Done"

data/examples/write_dev_null.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative '../lib/uringmachine'
+
+ITERATIONS = 1000
+DEV_NULL = File.open('/dev/null', 'w')
+FD = DEV_NULL.fileno
+BUF = ('*' * 8192).freeze
+
+$machine = UringMachine.new
+
+def run_um_write
+  $machine.write(FD, BUF)
+end
+
+1000.times { run_um_write }

data/ext/um/extconf.rb

@@ -8,8 +8,9 @@ dir_config 'um_ext'
 
 KERNEL_INFO_RE = /Linux (\d)\.(\d+)(?:\.)?((?:\d+\.?)*)(?:\-)?([\w\-]+)?/
 def get_config
-  config = { linux: !!(RUBY_PLATFORM =~ /linux/) }
-  raise "UringMachine only works on Linux!" if !config[:linux]
+  if RUBY_PLATFORM !~ /linux/
+    raise "UringMachine only works on Linux!"
+  end
 
   kernel_info = `uname -sr`
   m = kernel_info.match(KERNEL_INFO_RE)
@@ -20,14 +21,18 @@ def get_config
   combined_version = version.to_i * 100 + major_revision.to_i
   raise "UringMachine requires kernel version 6.4 or newer!" if combined_version < 604
 
-  config[:kernel_version]     = combined_version
-  config[:submit_all_flag]    = combined_version >= 518
-  config[:coop_taskrun_flag]  = combined_version >= 519
-  config[:single_issuer_flag] = combined_version >= 600
-  config[:prep_bind]          = combined_version >= 611
-  config[:prep_listen]        = combined_version >= 611
-
-  config
+  {
+    kernel_version:       combined_version,
+    submit_all_flag:      combined_version >= 518,
+    coop_taskrun_flag:    combined_version >= 519,
+    single_issuer_flag:   combined_version >= 600,
+    prep_bind:            combined_version >= 611,
+    prep_listen:          combined_version >= 611,
+    prep_cmd_sock:        combined_version >= 607,
+    prep_futex:           combined_version >= 607,
+    prep_waitid:          combined_version >= 607,
+    prep_read_multishot:  combined_version >= 607
+  }
 end
 
 config = get_config
@@ -51,10 +56,15 @@ if !find_library('uring', nil, File.join(liburing_path, 'src'))
   raise "Couldn't find liburing.a"
 end
 
-$defs << '-DHAVE_IORING_SETUP_SUBMIT_ALL'   if config[:submit_all_flag]
-$defs << '-DHAVE_IORING_SETUP_COOP_TASKRUN' if config[:coop_taskrun_flag]
-$defs << '-DHAVE_IO_URING_PREP_BIND'        if config[:prep_bind]
-$defs << '-DHAVE_IO_URING_PREP_LISTEN'      if config[:prep_listen]
+$defs << "-DUM_KERNEL_VERSION=#{config[:kernel_version]}"
+$defs << '-DHAVE_IORING_SETUP_SUBMIT_ALL'       if config[:submit_all_flag]
+$defs << '-DHAVE_IORING_SETUP_COOP_TASKRUN'     if config[:coop_taskrun_flag]
+$defs << '-DHAVE_IO_URING_PREP_BIND'            if config[:prep_bind]
+$defs << '-DHAVE_IO_URING_PREP_LISTEN'          if config[:prep_listen]
+$defs << '-DHAVE_IO_URING_PREP_CMD_SOCK'        if config[:prep_cmd_sock]
+$defs << '-DHAVE_IO_URING_PREP_FUTEX'           if config[:prep_futex]
+$defs << '-DHAVE_IO_URING_PREP_WAITID'          if config[:prep_waitid]
+$defs << '-DHAVE_IO_URING_PREP_READ_MULTISHOT'  if config[:prep_read_multishot]
 $CFLAGS << ' -Wno-pointer-arith'
 
 CONFIG['optflags'] << ' -fno-strict-aliasing'