uringmachine 0.3 → 0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7129b3c8605d5734f7152bddb4fa1b6f034fd1de26262eabfbfc2190846967bd
-  data.tar.gz: 902e6663bac65d56e45d67383e2cd3eb0601534ed2b451f4f76b2812ce6125b1
+  metadata.gz: 9a9efd4af7de9fdb8db6888b9f6347e9dbc63aae9e26fa0f81d43984d265bd90
+  data.tar.gz: 5289699ce1e3e173d3766e0211fc77b57f3c123e2a6e041e9e751a3bf5ce07b2
 SHA512:
-  metadata.gz: 683db63642ddb5d98c9eb137f8121a8cb8cb0fe44456928fca78cf8e322cebc01078efa71379abcceae1a1889140bf5b39f6ac16348db0b77d9c8a5bb9cf5cd0
-  data.tar.gz: 850dce780030b6102371861805f831299d3ea113f8c02141515afe167b0e49f43a51812a6159a91b6335085b41fcb226713eeb963ae69d208818cb1f3cb303b3
+  metadata.gz: 3cf02bbaae5a9e19b9ea994d1c2bf4b327a96121b083ca6756eca70629738f6c24aca10096bb49a0400678542232062969889ed3f0773591f5dc71f718707fef
+  data.tar.gz: 67b368097ddecd6c9ca9ce360cc918d8e7de91ec83a00d617765c2026fbe08f16f5009b78323e9f314cd1df63a1baaa39e8887b4a90fff0cb8010d810276df7d

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+# 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,88 @@
 <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.
+
+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.
+
+## 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
+```

data/TODO.md

@@ -0,0 +1,5 @@
+- splice
+- sendto
+- recvfrom
+
+- queues

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/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/ext/um/extconf.rb

@@ -21,14 +21,11 @@ def get_config
   raise "UringMachine requires kernel version 6.4 or newer!" if combined_version < 604
 
   config[:kernel_version]     = combined_version
-  config[:pidfd_open]         = combined_version > 503
-  config[:multishot_accept]   = combined_version >= 519
-  config[:multishot_recv]     = combined_version >= 600
-  config[:multishot_recvmsg]  = combined_version >= 600
-  config[:multishot_timeout]  = combined_version >= 604
   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
 end
@@ -54,16 +51,10 @@ if !find_library('uring', nil, File.join(liburing_path, 'src'))
   raise "Couldn't find liburing.a"
 end
 
-def define_bool(name, value)
-  $defs << "-D#{name}=#{value ? 1 : 0 }"
-end
-
-$defs << '-DHAVE_IO_URING_PREP_MULTISHOT_ACCEPT'  if config[:multishot_accept]
-$defs << '-DHAVE_IO_URING_PREP_RECV_MULTISHOT'    if config[:multishot_recv]
-$defs << '-DHAVE_IO_URING_PREP_RECVMSG_MULTISHOT' if config[:multishot_recvmsg]
-$defs << '-DHAVE_IO_URING_TIMEOUT_MULTISHOT'      if config[:multishot_timeout]
-$defs << '-DHAVE_IORING_SETUP_SUBMIT_ALL'         if config[:submit_all_flag]
-$defs << '-DHAVE_IORING_SETUP_COOP_TASKRUN'       if config[:coop_taskrun_flag]
+$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]
 $CFLAGS << ' -Wno-pointer-arith'
 
 CONFIG['optflags'] << ' -fno-strict-aliasing'