uringmachine 0.23.1 → 0.24.0

data/benchmark/http_server_multi_accept.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'uringmachine', path: '..'
+end
+
+require 'uringmachine'
+
+RE_REQUEST_LINE = /^([a-z]+)\s+([^\s]+)\s+(http\/[0-9\.]{1,3})/i
+RE_HEADER_LINE = /^([a-z0-9\-]+)\:\s+(.+)/i
+
+def stream_get_request_line(stream, buf)
+  line = stream.get_line(buf, 0)
+  m = line&.match(RE_REQUEST_LINE)
+  return nil if !m
+
+  {
+    'method'   => m[1].downcase,
+    'path'     => m[2],
+    'protocol' => m[3].downcase
+  }
+end
+
+class InvalidHeadersError < StandardError; end
+
+def get_headers(stream, buf)
+  headers = stream_get_request_line(stream, buf)
+  return nil if !headers
+
+  while true
+    line = stream.get_line(buf, 0)
+    break if line.empty?
+
+    m = line.match(RE_HEADER_LINE)
+    raise InvalidHeadersError, "Invalid header" if !m
+
+    headers[m[1]] = m[2]
+  end
+
+  headers
+end
+
+BODY = "Hello, world!" * 1000
+
+def send_response(machine, fd)
+  headers = "HTTP/1.1 200\r\nContent-Length: #{BODY.bytesize}\r\n\r\n"
+  machine.sendv(fd, headers, BODY)
+end
+
+def handle_connection(machine, fd)
+  stream = UM::Stream.new(machine, fd)
+  buf = String.new(capacity: 65536)
+
+  while true
+    headers = get_headers(stream, buf)
+    break if !headers
+
+    send_response(machine, fd)
+  end
+rescue InvalidHeadersError, SystemCallError => e
+  # ignore
+ensure
+  machine.close_async(fd)
+end
+
+N = ENV['N']&.to_i || 1
+PORT = ENV['PORT']&.to_i || 1234
+
+workers = N.times.map do |idx|
+  Thread.new do
+    machine = UM.new
+
+    listen_fd = machine.socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
+    machine.setsockopt(listen_fd, UM::SOL_SOCKET, UM::SO_REUSEADDR, true)
+    machine.setsockopt(listen_fd, UM::SOL_SOCKET, UM::SO_REUSEPORT, true)
+    machine.bind(listen_fd, '127.0.0.1', PORT)
+    machine.listen(listen_fd, 128)
+
+    machine.accept_each(listen_fd) { |fd|
+      machine.spin { handle_connection(machine, fd) }
+    }
+  rescue Exception => e
+    p e
+    p e.backtrace
+    exit!
+  end
+end
+
+puts "Listening on localhost:#{PORT}, #{N} worker thread(s)"
+workers.each(&:join)

data/benchmark/http_server_multi_ractor.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'uringmachine', path: '..'
+end
+
+require 'uringmachine'
+
+RE_REQUEST_LINE = /^([a-z]+)\s+([^\s]+)\s+(http\/[0-9\.]{1,3})/i
+RE_HEADER_LINE = /^([a-z0-9\-]+)\:\s+(.+)/i
+
+def stream_get_request_line(stream, buf)
+  line = stream.get_line(buf, 0)
+  m = line&.match(RE_REQUEST_LINE)
+  return nil if !m
+
+  {
+    'method'   => m[1].downcase,
+    'path'     => m[2],
+    'protocol' => m[3].downcase
+  }
+end
+
+class InvalidHeadersError < StandardError; end
+
+def get_headers(stream, buf)
+  headers = stream_get_request_line(stream, buf)
+  return nil if !headers
+
+  while true
+    line = stream.get_line(buf, 0)
+    break if line.empty?
+
+    m = line.match(RE_HEADER_LINE)
+    raise InvalidHeadersError, "Invalid header" if !m
+
+    headers[m[1]] = m[2]
+  end
+
+  headers
+end
+
+BODY = "Hello, world!" * 1000
+Ractor.make_shareable(BODY)
+
+def send_response(machine, fd)
+  headers = "HTTP/1.1 200\r\nContent-Length: #{BODY.bytesize}\r\n\r\n"
+  machine.sendv(fd, headers, BODY)
+end
+
+def handle_connection(machine, fd)
+  machine.setsockopt(fd, UM::IPPROTO_TCP, UM::TCP_NODELAY, true)
+  stream = UM::Stream.new(machine, fd)
+  buf = String.new(capacity: 65536)
+
+  while true
+    headers = get_headers(stream, buf)
+    break if !headers
+
+    send_response(machine, fd)
+  end
+# rescue InvalidHeadersError, SystemCallError => e
+  # ignore
+rescue Exception => e
+  p e: e
+  p bt: e.backtrace
+  exit!
+ensure
+  machine.close_async(fd)
+end
+
+N = ENV['N']&.to_i || 1
+PORT = ENV['PORT']&.to_i || 1234
+
+workers = N.times.map do |idx|
+  Ractor.new do
+    machine = UM.new
+
+    listen_fd = machine.socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
+    machine.setsockopt(listen_fd, UM::SOL_SOCKET, UM::SO_REUSEADDR, true)
+    machine.setsockopt(listen_fd, UM::SOL_SOCKET, UM::SO_REUSEPORT, true)
+    machine.bind(listen_fd, '127.0.0.1', PORT)
+    machine.listen(listen_fd, 128)
+
+    machine.accept_each(listen_fd) { |fd|
+      machine.spin { handle_connection(machine, fd) }
+    }
+  rescue Exception => e
+    p e
+    p e.backtrace
+    exit!
+  end
+end
+
+puts "Listening on localhost:#{PORT}, #{N} worker ractor(s)"
+workers.each(&:join)

data/benchmark/http_server_single_thread.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'uringmachine', path: '..'
+end
+
+require 'uringmachine'
+
+RE_REQUEST_LINE = /^([a-z]+)\s+([^\s]+)\s+(http\/[0-9\.]{1,3})/i
+RE_HEADER_LINE = /^([a-z0-9\-]+)\:\s+(.+)/i
+
+def stream_get_request_line(stream, buf)
+  line = stream.get_line(buf, 0)
+  m = line&.match(RE_REQUEST_LINE)
+  return nil if !m
+
+  {
+    'method'   => m[1].downcase,
+    'path'     => m[2],
+    'protocol' => m[3].downcase
+  }
+end
+
+class InvalidHeadersError < StandardError; end
+
+def get_headers(stream, buf)
+  headers = stream_get_request_line(stream, buf)
+  return nil if !headers
+
+  while true
+    line = stream.get_line(buf, 0)
+    break if line.empty?
+
+    m = line.match(RE_HEADER_LINE)
+    raise InvalidHeadersError, "Invalid header" if !m
+
+    headers[m[1]] = m[2]
+  end
+
+  headers
+end
+
+BODY = "Hello, world!" * 1000
+
+def send_response(machine, fd)
+  headers = "HTTP/1.1 200\r\nContent-Length: #{BODY.bytesize}\r\n\r\n"
+  machine.sendv(fd, headers, BODY)
+end
+
+def handle_connection(machine, fd)
+  machine.setsockopt(fd, UM::IPPROTO_TCP, UM::TCP_NODELAY, true)
+  stream = UM::Stream.new(machine, fd)
+  buf = String.new(capacity: 65536)
+
+  while true
+    headers = get_headers(stream, buf)
+    break if !headers
+
+    send_response(machine, fd)
+  end
+rescue InvalidHeadersError, SystemCallError => e
+  # ignore
+ensure
+  machine.close_async(fd)
+end
+
+PORT = ENV['PORT']&.to_i || 1234
+
+machine = UM.new
+fd = machine.socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
+machine.setsockopt(fd, UM::SOL_SOCKET, UM::SO_REUSEADDR, true)
+machine.setsockopt(fd, UM::SOL_SOCKET, UM::SO_REUSEPORT, true)
+machine.bind(fd, '127.0.0.1', PORT)
+machine.listen(fd, 128)
+
+puts "Listening on localhost:#{PORT}"
+machine.accept_each(fd) { |conn| machine.spin { handle_connection(machine, conn) } }

data/benchmark/ips_io_pipe.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'uringmachine', path: '..'
+  gem 'benchmark'
+  gem 'benchmark-ips'
+end
+
+require 'benchmark/ips'
+require 'uringmachine'
+
+GROUPS = 16
+
+SIZE = 1 << 16
+DATA = '*' * SIZE
+
+def threads_setup
+  @threads_start_queue = Queue.new
+  @threads_stop_queue = Queue.new
+
+  GROUPS.times do
+    r, w = IO.pipe
+    r.sync = true
+    w.sync = true
+    Thread.new do
+      loop do
+        iterations = @threads_start_queue.shift
+        iterations.times { w.write(DATA) }
+        @threads_stop_queue << true
+      end
+    end
+    Thread.new do
+      loop do
+        iterations = @threads_start_queue.shift
+        iterations.times { r.read(SIZE) }
+        @threads_stop_queue << true
+      end
+    end
+  end
+end
+
+def threads_run(times)
+  (GROUPS * 2).times { @threads_start_queue << times }
+  (GROUPS * 2).times { @threads_stop_queue.shift }
+end
+
+def um_setup
+  @machine = UM.new
+
+  @um_start_queue = UM::Queue.new
+  @um_stop_queue = UM::Queue.new
+
+  GROUPS.times do
+    r, w = UM.pipe
+    @machine.spin do
+      loop do
+        iterations = @machine.shift(@um_start_queue)
+        iterations.times { @machine.writev(w, DATA) }
+        @machine.push(@um_stop_queue, true)
+      end
+    end
+    @machine.spin do
+      loop do
+        iterations = @machine.shift(@um_start_queue)
+        iterations.times {
+          left = SIZE
+          left -= @machine.read(r, +'', left) while left > 0
+        }
+        @machine.push(@um_stop_queue, true)
+      end
+    end
+  end
+end
+
+def um_run(times)
+  (GROUPS * 2).times { @machine.push(@um_start_queue, times) }
+  (GROUPS * 2).times { @machine.shift(@um_stop_queue) }
+end
+
+def um2_setup
+  @um2_start_queue = UM::Queue.new
+  @um2_stop_queue = UM::Queue.new
+
+  thread_count = 2
+  tgroups = GROUPS / thread_count
+
+  @um2_machines = []
+  @um2_done = UM::Queue.new
+  @um2_threads = thread_count.times.map do
+    Thread.new do
+      machine = UM.new
+      @um2_machines << machine
+      tgroups.times do
+        r, w = UM.pipe
+        machine.spin do
+          loop do
+            iterations = machine.shift(@um2_start_queue)
+            iterations.times { machine.writev(w, DATA) }
+            machine.push(@um2_stop_queue, true)
+          end
+        end
+        machine.spin do
+          loop do
+            iterations = machine.shift(@um2_start_queue)
+            iterations.times {
+              left = SIZE
+              left -= machine.read(r, +'', left) while left > 0
+            }
+            machine.push(@um2_stop_queue, true)
+          end
+        end
+      end
+      machine.shift(@um2_done)
+    end
+  end
+end
+
+def um2_teardown
+  2.times { @machine.push(@um2_done, true) }
+end
+
+def um2_run(times)
+  @um2_machine ||= UM.new
+  (GROUPS * 2).times { @um2_machine.push(@um2_start_queue, times) }
+  (GROUPS * 2).times { @um2_machine.shift(@um2_stop_queue); @um2_machine.snooze }
+end
+
+threads_setup
+um_setup
+um2_setup
+
+at_exit { um2_teardown }
+
+# um2_run(1)
+# p after_run: 1
+
+Benchmark.ips do |x|
+  x.report('Threads') { |t| threads_run(t) }
+  x.report('UM')      { |t| um_run(t) }
+  x.report('UMx2')    { |t| um2_run(t) }
+
+  x.compare!(order: :baseline)
+end

data/docs/design/buffer_pool.md

@@ -0,0 +1,183 @@
+# UringMachine Buffer Pool
+
+One of the interesting recent features in io_uring is support for buffer rings.
+A buffer ring is a structure that is shared between the application and the
+kernel. The application can add buffers to the buffer ring to be used by the
+kernel to perform multishot read/recv.
+
+https://www.man7.org/linux/man-pages/man3/io_uring_setup_buf_ring.3.html
+https://www.man7.org/linux/man-pages/man3/io_uring_prep_recv.3.html
+
+On recent kernels (>=6.12), io_uring also supports incremental buffer usage,
+which means it can partially consume buffers, such that buffer space will not be
+wasted in case of a short read/recv.
+
+This documents the API and implementation details of a buffer pool that
+automatically manages multiple buffer rings, and allows partial buffer
+consumption and reuse. We also provide a way to integrate this feature with
+UringMachine *streams*, in effect switching streams from relying on their own
+buffers, to using managed buffers from the buffer pool.
+
+## Design
+
+### The API
+
+- The buffer pool is created and managed automatically. No API is involved.
+
+- To use the buffer pool, two dedicated APIs are added:
+
+  - `UM#stream_read(fd) { |stream| ... }`
+  - `UM#stream_recv(fd) { |stream| ... }`
+
+- The two APIs work equivalently, where they start a multishot read/recv
+  operation, repeating it if necessary, until the given block returns, the fd is
+  closed, or an exception is encountered.
+
+- The stream instance provided to the given block is created automatically, and
+  is used to interact with the data read/received as it becomes available. The
+  stream instance methods may block until enough data is available in the
+  relevant buffers.
+  
+   Example:
+
+  ```ruby
+  machine.stream_recv(fd) do |stream|
+    loop do
+      line = stream.get_line(max: 60)
+      if (size = parse_size(line))
+        data = stream.read(size)
+        process_data(data)
+      else
+        raise "Protocol error!"
+      end
+    end
+  end
+  ```
+
+- Since there is some overhead for setting up streams and multishot operations,
+  this API is intended for use in long-running connections, e.g. HTTP, Redis,
+  PostgreSQL, etc.
+
+- Right now, streams provide support for reading lines (for line-oriented
+  protocols), reading data of arbitrary size, and decoding RESP (Redis protocol)
+  messages. In the future, we may add more built-in support for decoding other
+  protocols, such as HTTP/1.1, HTTP/2, Websocket etc.
+
+### The buffer pool
+
+- Each UringMachine instance has 1 associated buffer pool.
+
+- A buffer pool manages up to 64 buffer groups.
+
+- Each buffer group has its own associated buffer ring, and 64 buffers. The
+  buffer size is fixed at 64KB, for a total size of 64x64KB = 4MB.
+
+- The maximum amount of buffers in a buffer pool is 64X64 = 4096, for a total
+  size of 64X4MB = 256MB.
+
+- The buffer pool is responsible for selecting a buffer group for each multishot
+  read/recv operation, according to the number of buffers available to the
+  kernel.
+
+- The buffer pool is responsible for setting up additional buffer groups (up to
+  64) as needed.
+
+- The buffer pool is responsible for maintaining the state of each buffer, and
+  whether it is currently committed to the kernel, or available to the
+  application.
+
+### Streams
+
+- A stream is automatically created upon a call to `#stream_read` or
+  `#stream_recv`.
+
+- The stream provides methods for the application to consume incoming data.
+
+- The stream holds zero or more *segments* of data that are added to the stream
+  as more data becomes available through CQEs.
+
+- The different methods scan through the different segments, potentially
+  blocking until more segments arrive, and copies data into strings or other
+  data structures according to the APIs used.
+
+- Each stream holds a cursor that tells it from which offset and in which
+  segment data is currently to be consumed.
+
+- As segments are consumed by the application, the underlying buffers are
+  committed back to the kernel to be reused in subsequent CQEs, providing no
+  segment of which is currently used by a stream.
+
+### Principle of Operation
+
+- When a multishot operation is started, a buffer group is selected, and its id
+  is provided in the corresponding SQE. In case when the buffer group is
+  exhausted (no more buffers are available to the kernel), the multishot
+  operation is automatically restarted with a newly selected buffer group.
+  Buffer groups are created automatically as needed if the currently existing
+  buffer groups are exhausted.
+
+- When one or more CQEs are encountered for the multishot operation, the
+  corresponding fiber is resumed, and the multishot results are processed into
+  segments that are added to the stream, to be eventually processed according to
+  the APIs used. Importantly, it is the calls to stream methods that drive the
+  eventual consumption of buffer segments. That is, many pieces of data may be
+  pending actual processing.
+
+- The actual submission of multishot operations is driven by usage of the
+  different stream APIs and the need for more data.
+
+### Data structures
+
+```c
+#define UM_BUFFER_POOL_MAX_GROUPS 64
+#define UM_BUFFER_GROUP_SIZE 64
+#define UM_BUFFER_SIZE (1 << 16)
+
+/*
+  A buffer segment represents a contiguous sequence of bytes coming from a
+  managed buffer. buffer segments are arranged in a linked list, each one
+  pointing to the next. In order to minimize allocations, those structs are
+  reused, and when no longer needed they are added to a freelist on the buffer
+  pool.
+*/
+struct um_buffer_segment {
+  struct um_buffer_segment *next;
+  uint8_t bgid; // buffer group id
+  uint8_t bid; // buffer id
+  void *ptr;
+  size_t len;
+}
+
+/*
+  A stream is made of zero or more buffer segments.
+*/
+struct um_stream {
+  struct um *machine;
+  struct um_buffer_segment *head;
+  struct um_buffer_segment *tail;
+}
+
+/*
+  A managed buffer. It has a fixed size of 64KB
+*/
+struct um_buffer {
+  size_t ofs; // current offset for partial consumption (incremented by CQE result)
+  uint16_t commited; // is buffer available to the kernel
+  uint16_t ref_count; // how many segments currently use the buffer
+  uint8_t data[UM_BUFFER_SIZE]; // buffer space
+}
+
+struct um_buffer_group {
+  struct io_uring_buf_ring *ring;
+  uint commited_count;
+}
+
+/*
+  A buffer pool used for managing buffers.
+*/
+struct um_buffer_pool {
+  struct um_buffer_group[UM_BUFFER_POOL_MAX_GROUPS];
+  uint16_t buffer_group_count;
+  struct um_buffer_segment *free_list;
+}
+```

data/docs/um_api.md

@@ -0,0 +1,91 @@
+# UringMachine API Reeference
+
+## UringMachine Class Methods
+
+- `debug(msg)` - prints a string message to STDERR.
+- `kernel_version` - returns the linux kernel version as an integer, e.g. 607 =>
+  version 6.7.
+- `new(size)` - creates a new UringMachine instance.
+- `pidfd_open(pid)` - creates and returns a file descriptor that refers to the
+  given process.
+- `pidfd_send_signal(pidfd, sig, flags)` - sends a signal to a process
+  identified by a pidfd.
+- `pipe` - creates a pipe and returns read and write fds.
+- `socketpair(domain, type, protocol)` - creates a socket pair and returns the
+  two fds.
+
+
+## UringMachine Instance Methods
+
+- `accept_each(sockfd)  { |fd| ... }` - accepts incoming connections to the
+  given server socket in an infinite loop, yielding each one to the given block.
+- `accept_into_queue(sockfd, queue)` - accepts incoming connections to the given
+  server socket in an infinite loop, pushing each one to the given queue.
+- `accept(sockfd)` - accepts an incoming connection, returning its fd.
+- `bind(sockfd, host, port)` - binds the given socket to the given address.
+- `close_async(fd)` - closes the given fd asynchronously, i.e. <w>ithout waiting
+  for the operation to complete.
+- `close(fd)` - closes the given fd.
+- `connect(sockfd, host, port)` - connects the given socket to the given
+  address.
+- `getsockopt(sockfd, level, opt)` - returns a socket option value.
+- `listen(sockfd)` - starts listening on the given socket.
+- `metrics` - returns metrics for the machine.
+- `open(pathname, flags)` - opens the given path and returns an fd.
+- `pending_fibers` - returns the set of pending fibers, that is, fibers waiting
+  for an operation to complete.
+- `periodically(interval) { ... }` - runs the given block at regular intervals
+  in an infinite loop.
+- `poll(fd, mask)` - waits for the given fd to become ready according to the
+  given event mask.
+- `pop(queue)` - removes and returns a value off the end of the given queue.
+- `prep_timeout(interval)` - returns a timeout AsyncOp with the given interval.
+- `push(queue, value)` - adds the given value to the end of the given queue.
+- `read_each(fd, bgid) { |data| ... }` - reads repeatedly from the given fd
+  using the given buffer group id, yielding each chunk of data to the given
+  block.
+- `read(fd, buffer[, maxlen[, buffer_offset[, file_offset]]])` - reads from the
+  given fd int o the given buffer (String or IO::Buffer).
+- `recv_each(fd, bgid, flags)` - receives from the given fd using the given
+  buffer group id, with the given flags.
+- `recv(fd, buffer, maxlen, flags)` - receives from the given fd into the given
+  buffer.
+- `schedule(fiber, value)` - adds the given fiber to the runqueue with the given
+  resume value.
+- `select(rfds, wfds, efds)` - selects ready fds from the given readable,
+  writable and exeptable fds.
+- `send_bundle(fd, bgid, *strings)` - sends a bundle of buffers to the given fd
+  using the given buffer group id.
+- `send(fd, buffer, len, flags)` - sends to the given fd from the given buffer.
+- `sendv(fd, *buffers)` - sends multiple buffers to the given fd.
+- `setsockopt(fd, level, opt, value)` - sets a socket option.
+- `setup_buffer_ring(size, count)` - sets up a buffer ring and returns the
+  buffer group id.
+- `shift(queue)` - removes and returns a value from the head of given queue.
+- `shutdown_async(fd, how)` - shuts down the given socket fd without blocking.
+- `shutdown(fd, how)` - shuts down the given socket fd.
+- `size` - returns the number of entries in the submission queue.
+- `sleep(duration)` - sleeps for the given duration.
+- `snooze` - adds the current fiber to the end of the runqueue and yields
+  control to the next fiber in the runqueue.
+- `socket(domain, type, protocol, flags)` - creates a socket and returns its fd.
+- `statx(dirfd, path, flags, mask)` - returns information for the given path.
+- `submit` - submits any unsubmitted operations to the submission queue.
+- `switch` - switches to the next fiber in the runqueue.
+- `synchronize(mutex)` - synchronizes access to the given mutex.
+- `timeout(interval, exception_class) { ... }` - runs the given block, raising
+  an exception if the timeout interval has elapsed.
+- `unshift(queue, value)` - adds the given value to the beginning of the given
+  queue.
+- `waitid_status(idtype, id, options)` - waits for the given pid/pidfd and
+  returns a `Process::Status`.
+- `waitid(idtype, id, options)` - waits for the given pid/pidfd and returns
+  `[pid, status]`.
+- `wakeup` - wakes up a machine currently waiting for completions.
+- `write_async(fd, buffer[, len[, offset]])` - writes to the given fd without
+  waiting for completion.
+- `write(fd, buffer[, len[, offset]])` - writes to the given fd.
+- `writev(fd, *buffers[, file_offset])` - writes multiple buffers to the given
+  fd.
+- `yield()` - yields control to the next fiber in the runqueue.
+