uringmachine 0.3 → 0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7129b3c8605d5734f7152bddb4fa1b6f034fd1de26262eabfbfc2190846967bd
-  data.tar.gz: 902e6663bac65d56e45d67383e2cd3eb0601534ed2b451f4f76b2812ce6125b1
+  metadata.gz: 2067cd0f88d6dbc341410ca6911916f510132ee23ce3f6d5fb5978259eeaef11
+  data.tar.gz: f816a9478f714a3a9770740bc14fc03ae2687f2fe7d0e29cbc0b8632994bad1f
 SHA512:
-  metadata.gz: 683db63642ddb5d98c9eb137f8121a8cb8cb0fe44456928fca78cf8e322cebc01078efa71379abcceae1a1889140bf5b39f6ac16348db0b77d9c8a5bb9cf5cd0
-  data.tar.gz: 850dce780030b6102371861805f831299d3ea113f8c02141515afe167b0e49f43a51812a6159a91b6335085b41fcb226713eeb963ae69d208818cb1f3cb303b3
+  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,26 @@
+# 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
+- Add `#bind`, `#listen`
+- Add `#spin`
+- Fix bugs in multishot read and other ops
+- Add `#recv`, `#send`
+- Add `#socket`, `#connect`
+
 # 2024-10-04 Version 0.3
 
 - Fix race condition affecting `#timeout` and `#sleep`.

data/README.md

@@ -9,3 +9,131 @@
 <a href="https://github.com/digital-fabric/uringmachine/blob/master/LICENSE">
   <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
 </a>
+
+UringMachine is a fiber-based library for creating concurrent apps in Ruby on
+modern Linux machines. UringMachine provides a rich API for performing I/O using
+[io_uring](https://en.wikipedia.org/wiki/Io_uring).
+
+## Features
+
+- Automatic fiber switching when performing blocking operations.
+- Automatic cancellation using of ongoing operations with Ruby exceptions.
+- General-purpose API for cancelling any operation on timeout.
+- High performance (needs to be proved).
+- (Eventually) I/O class with buffered reads and an intuitive API.
+
+## Design
+
+UringMachine is based on my experience marrying Ruby and io_uring:
+
+- [Polyphony](https://github.com/digital-fabric/polyphony) - a comprehensive gem
+  providing io_uring functionality, structured concurrency, and monkey-patching
+  for the Ruby standard library.
+- [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
+  changing APIs (Ruby is evolving quite rapidly these days!), and anyways you're
+  always going to get stuck with some standard Ruby API that's implemented as a
+  C extension and just won't play nice with whatever you're trying to do.
+- The design of the Polyphony io_uring backend was an evolution of something
+  that was originally based on libev as an event loop. In hindsight, adapting
+  the design for how io_uring worked led to code that was too complex and even
+  somewhat brittle.
+- IOU showed me that even if we embrace callbacks, the developer experience is
+  substantially inferior to what you can do with a sequential coding style. Even
+  just in terms of line count - with callbacks you end up with roughly double
+  the number of lines of code.
+- Implementing fiber switching on top of IOU was disappointing in terms of
+  performance. In order for a fiber-based solution to be performed it had to be
+  baked in - hence UringMachine.
+- Working with fibers has the very important benefit that you can keep stuff on
+  the stack, instead of passing around all kinds of references to the heap. In
+  addition, you mostly don't need to worry about marking Ruby objects used in
+  operations, since normally they'll already be on the stack as method call
+  parameters.
+- Polyphony was designed as an all-in-one solution that did everything: turning
+  stock APIs into fiber-aware ones, providing a solid structured-concurrency
+  implementation for controlling fiber life times, extensions providing
+  additional features such as compressing streaming data between two fds, other
+  APIs based on splicing etc. Perhaps a more cautious approach would be better.
+- Pending operation lifetime management in Polyphony was based a complex
+  reference counting scheme that proved problematic, especially for multishot
+  operations.
+
+So, based on those two projects, I wanted to design a Ruby API for io_uring
+based on the following principles:
+
+- Automatic fiber switching.
+- No monkey-patching. Instead, provide a simple custom API, as a replacement for
+  the stock Ruby `IO` and `Socket` classes.
+- Simpler management of pending operation lifetime.
+- Do not insist on structured concurrency, just provide the APIs necessary to
+  create actors and to supervise the execution of fibers.
+
+### 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'
+
+machine = UringMachine.new
+stdout_fd = STDOUT.fileno
+stdin_fd = STDIN.fileno
+machine.write(stdout_fd, "Hello, world!\n")
+
+loop do
+  machine.write(stdout_fd, "Say something: ")
+  buf = +''
+  res = machine.read(stdin_fd, buf, 8192)
+  if res > 0
+    machine.write(stdout_fd, "You said: #{buf}")
+  else
+    break
+  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

@@ -0,0 +1,14 @@
+- splice / - tee
+- sendto
+- recvfrom
+- 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/echo_server.rb

@@ -1,52 +1,30 @@
-require_relative '../lib/iou'
+require_relative '../lib/uringmachine'
 require 'socket'
 
 socket = TCPServer.open('127.0.0.1', 1234)
 puts 'Listening on port 1234...'
 
-@ring = IOU::Ring.new
+$machine = UringMachine.new
+$bgid = $machine.setup_buffer_ring(4096, 1024)
 
-@ring.prep_accept(fd: socket.fileno, multishot: true) do |c|
-  setup_connection(c[:result]) if c[:result] > 0
-end
-
-def setup_connection(fd)
-  puts "Connection accepted fd #{fd}"
-
-  buffer = +''
-  echo_prep_read(fd, buffer)
-end
-
-def echo_prep_read(fd, buffer)
-  @ring.prep_read(fd: fd, buffer: buffer, len: 4096, buffer_offset: -1) do |c|
-    if c[:result] > 0
-      echo_lines(fd, buffer)
-      echo_prep_read(fd, buffer)
-    elsif c[:result] == 0
-      puts "Connection closed by client on fd #{fd}"
-    else
-      puts "Got error #{c[:result]} on fd #{fd}, closing connection..."
-      @ring.prep_close(fd: fd) do |c|
-        puts "Connection closed on fd #{fd}, result #{c[:result]}"
-      end
-    end
+def handle_connection(fd)
+  $machine.read_each(fd, $bgid) do |buf|
+    $machine.write(fd, buf)
   end
+  puts "Connection closed by client fd #{fd}"
+rescue Exception => e
+  puts "Got error #{e.inspect}, closing connection"
+  $machine.close(fd) rescue nil
 end
 
-def echo_lines(fd, buffer)
-  sep = $/
-  sep_size = sep.bytesize
-  
-  while true
-    idx = buffer.index(sep)
-    if idx
-      line = buffer.slice!(0, idx + sep_size)
-      @ring.prep_write(fd: fd, buffer: line)
-    else
-      break
-    end
+$machine.spin do
+  loop do
+    $machine.sleep 5
+    puts "pending: #{$machine.pending_count}"
   end
 end
 
-trap('SIGINT') { exit! }
-@ring.process_completions_loop
+$machine.accept_each(socket.fileno) do |fd|
+  puts "Connection accepted fd #{fd}"
+  $machine.spin(fd) { handle_connection(_1) }
+end

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/inout.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../lib/uringmachine'
+
+machine = UringMachine.new
+stdout_fd = STDOUT.fileno
+stdin_fd = STDIN.fileno
+machine.write(stdout_fd, "Hello, world!\n")
+
+loop do
+  machine.write(stdout_fd, "Say something: ")
+  buf = +''
+  res = machine.read(stdin_fd, buf, 8192)
+  if res > 0
+    machine.write(stdout_fd, "You said: #{buf}")
+  else
+    break
+  end
+end

data/examples/nc.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative '../lib/uringmachine'
+require 'socket'
+
+HOST = ARGV[0]
+PORT = ARGV[1].to_i
+
+machine = UringMachine.new
+
+conn_fd = machine.socket(Socket::AF_INET, Socket::SOCK_STREAM, 0, 0);
+machine.connect(conn_fd, HOST, PORT)
+
+stdin_fd = STDIN.fileno
+stdout_fd = STDOUT.fileno
+
+f_writer = Fiber.new do
+  bgidw = machine.setup_buffer_ring(4096, 1024)
+  machine.read_each(stdin_fd, bgidw) do |buf|
+    machine.write(conn_fd, buf)
+  end
+end
+machine.schedule(f_writer, nil)
+
+f_reader = Fiber.new do
+  bgidr = machine.setup_buffer_ring(4096, 1024)
+  machine.read_each(conn_fd, bgidr) do |buf|
+    machine.write(stdout_fd, buf)
+  end
+end
+machine.schedule(f_reader, nil)
+
+trap('SIGINT') { exit! }
+loop do
+  machine.sleep(60)
+end

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"