iou 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 81760683a4ded7963311f6d8961dff7d0f13edd164afb4cf3056f151889f612d
+  data.tar.gz: c700916bbe4b519bc95522da3855fa084f40ab56d8c8cebd2f1d04521681add2
+SHA512:
+  metadata.gz: f1aba30375539d2f16083bce2db47a3807abd2a2fa484c270d57a8954bbe3a21d9785408bba667c48e991b47805b38686a4b263602b2b57cf17f30fd32c59187
+  data.tar.gz: e812e047b19ea89c9a0731de4f216dbacf3e1bdc62e363bc5f31fb843b19fc072a3b0e3272152ff215efd90591ec220bc23aff12d7a6dae755153c9fe6892a76

data/.github/dependabot.yml

@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for more information:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# https://containers.dev/guide/dependabot
+
+version: 2
+updates:
+ - package-ecosystem: "devcontainers"
+   directory: "/"
+   schedule:
+     interval: weekly

data/.gitignore

@@ -0,0 +1,59 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# Ignore compiled extension
+lib/*.so
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vendor/liburing"]
+	path = vendor/liburing
+	url = https://github.com/axboe/liburing

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Digital Fabric
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,106 @@
+# IOU: io_uring for Ruby
+
+<a href="http://rubygems.org/gems/iou">
+  <img src="https://badge.fury.io/rb/iou.svg" alt="Ruby gem">
+</a>
+<a href="https://github.com/digital-fabric/iou/actions?query=workflow%3ATests">
+  <img src="https://github.com/digital-fabric/iou/workflows/Tests/badge.svg" alt="Tests">
+</a>
+<a href="https://github.com/digital-fabric/iou/blob/master/LICENSE">
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
+</a>
+
+## What is IOU?
+
+IOU is a Ruby gem for working with the io_uring API. IOU provides a simple and
+idiomatic API for working with io_uring. IOU does not make any assumptions about
+the concurrency model in your application. It can be used in multi-threaded,
+multi-fibered, or callback-based apps. It largely follows the
+[liburing](https://github.com/axboe/liburing/) API, but provides certain
+Ruby-esque amenities to make it easier to use io_uring in Ruby apps.
+
+## Features
+
+- Prepare and submit operations: accept, read, write, timeout, nop.
+- Cancel operations.
+- Multishot timeout, accept, read.
+- Setup buffer ring for multishot read (provides a nice boost for read performance).
+- Associate arbitrary data with operations.
+- Run callback on completion of operations.
+- Emit arbitrary values for in-app signalling.
+
+## Basic Usage
+
+Operations are performed by preparing them (using the different `#prep_xxx`
+methods), submitting them, then waiting or polling for completion of those
+operations. Here's a simple example of how IOU is used:
+
+```ruby
+ring = IOU::Ring.new
+# prepare a 3 second timeout operation
+ring.prep_timeout(interval: 3)
+
+# submit all unsubmitted operations to io_uring
+ring.submit
+
+# wait for completion, this will block for 3 seconds!
+ring.wait_for_completion
+#=> { id: 1, op: :timeout, interval: 3}
+```
+
+## Cancelling operations
+
+Any operation can be cancelled by calling `#prep_cancel`:
+
+```ruby
+id = ring.prep_timeout(interval: 3)
+...
+ring.prep_cancel(id)
+```
+
+## Callback-style completions
+
+Callback-style handling of completions can be done using `#process_completions`:
+
+```ruby
+timeout_id = ring.prep_timeout(interval: 3)
+ring.submit
+
+# passing true to process_completions means wait for at least one completion
+# to be available
+ring.process_completions(true) do |completion|
+  # the completion is a hash containing the operation spec
+  if completion[:id] == timeout_id
+    puts "timeout elapsed!"
+  end
+end
+
+# another way to do callbacks is to provide a block to prep_timeout:
+timeout_id = ring.prep_timeout(interval: 3) do
+  puts "timeout elapsed"
+end
+
+# wait for completion and trigger the callback
+ring.process_completions(true)
+```
+
+## I/O with IOU
+
+I/O operations, such as `read`, `write`, `recv`, `send`, `accept` etc are done
+using raw fd's.
+
+```ruby
+# write to STDOUT using IOU
+ring.prep_write(fd: STDOUT.fileno, buffer: 'Hello world!')
+ring.submit
+ring.wait_for_completion
+```
+
+## Examples
+
+Examples for using IOU can be found in the examples directory:
+
+- [v] Echo server
+- [v] HTTP server
+- [v] Event loop (in the style of EventMachine)
+- [ ] Fiber-based concurrency

data/Rakefile

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/clean"
+require "rake/testtask"
+require "rake/extensiontask"
+
+Rake::ExtensionTask.new("iou_ext") do |ext|
+  ext.ext_dir = "ext/iou"
+end
+
+task :recompile => [:clean, :compile]
+task :default => [:compile, :test]
+
+test_config = -> (t) {
+  t.libs << "test"
+  t.test_files = FileList["test/**/test_*.rb"]
+}
+Rake::TestTask.new(test: :compile, &test_config)
+
+task :stress_test do
+  exec 'ruby test/stress.rb'
+end
+
+CLEAN.include "**/*.o", "**/*.so", "**/*.so.*", "**/*.a", "**/*.bundle", "**/*.jar", "pkg", "tmp"
+
+task :release do
+  require_relative './lib/iou/version'
+  version = IOU::VERSION
+
+  puts 'Building iou...'
+  `gem build iou.gemspec`
+
+  puts "Pushing iou #{version}..."
+  `gem push iou-#{version}.gem`
+
+  puts "Cleaning up..."
+  `rm *.gem`
+end

data/TODO.md

@@ -0,0 +1,4 @@
+# io_uring ops
+
+- [ ] recv
+- [ ] send

data/examples/echo_server.rb

@@ -0,0 +1,52 @@
+require_relative '../lib/iou'
+require 'socket'
+
+socket = TCPServer.open('127.0.0.1', 1234)
+puts 'Listening on port 1234...'
+
+@ring = IOU::Ring.new
+
+@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
+  end
+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
+  end
+end
+
+trap('SIGINT') { exit! }
+@ring.process_completions_loop

data/examples/event_loop.rb

@@ -0,0 +1,69 @@
+require_relative '../lib/iou'
+require 'socket'
+
+class IOUEventLoop
+  attr_reader :ring
+
+  def initialize
+    @ring = IOU::Ring.new
+  end
+
+  def async_queue
+    @async_queue ||= []
+  end
+
+  def async(&block)
+    @async_queue << block
+    signal if @waiting
+  end
+
+  def signal
+    # generate an event to cause process_completions to return
+    ring.prep_nop
+    ring.submit
+  end
+
+  def run_async_tasks
+    pending = @async_queue
+    @async_queue = []
+    pending&.each(&:call)
+  end
+
+  def run
+    yield if block_given?
+    while !@stopped
+      run_async_tasks
+      @waiting = true
+      ring.process_completions
+      @waiting = false
+    end
+  end
+
+  def stop
+    @stopped = true
+    signal if @waiting
+  end
+
+  def timeout(delay, &block)
+    ring.prep_timeout(interval: delay, &block)
+    ring.submit
+  end
+
+  def interval(period, &block)
+    ring.prep_timeout(interval: period, multishot: true, &block)
+    ring.submit
+  end
+end
+
+# exaple usage
+event_loop = IOUEventLoop.new
+
+trap('SIGINT') { event_loop.stop }
+
+event_loop.run do
+  event_loop.interval(1) do
+    puts "The time is #{Time.now}"
+  end
+end
+
+puts "Stopped"

data/examples/http_server.rb

@@ -0,0 +1,56 @@
+require_relative '../lib/iou'
+require 'socket'
+require 'http/parser'
+
+def log(msg)
+  # return
+  STDERR.puts msg
+end
+
+socket = TCPServer.open('127.0.0.1', 1234)
+log 'Listening on port 1234...'
+
+@ring = IOU::Ring.new
+@bg_id = @ring.setup_buffer_ring(count: 1024, size: 4096)
+
+@ring.prep_accept(fd: socket.fileno, multishot: true) do |c|
+  setup_connection(c[:result]) if c[:result] > 0
+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)
+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
+  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
+
+trap('SIGINT') { exit! }
+@ring.process_completions_loop

data/examples/http_server_multishot.rb

@@ -0,0 +1,59 @@
+require_relative '../lib/iou'
+require 'socket'
+require 'http/parser'
+
+def log(msg)
+  # return
+  STDERR.puts msg
+end
+
+socket = TCPServer.open('127.0.0.1', 1234)
+log 'Listening on port 1234... (multishot read)'
+
+@ring = IOU::Ring.new
+@bg_id = @ring.setup_buffer_ring(count: 1024, size: 4096)
+
+@ring.prep_accept(fd: socket.fileno, multishot: true) do |c|
+  setup_connection(c[:result]) if c[:result] > 0
+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)
+end
+
+def http_prep_read(fd, parser)
+  id = @ring.prep_read(fd: fd, multishot: true, buffer_group: @bg_id) do |c|
+    if c[:result] > 0
+      parser << c[:buffer]
+    elsif c[:result] == 0
+      log "Connection closed by client on fd #{fd}"
+    else
+      if c[:result] != -Errno::ECANCELED::Errno
+        log "Got error #{c[:result]} on fd #{fd}, closing connection..."
+      end
+      @ring.prep_close(fd: fd) do |c|
+        log "Connection closed on fd #{fd}, result #{c[:result]}"
+      end
+    end
+  rescue HTTP::Parser::Error
+    puts "Error parsing, closing connection..."
+    @ring.prep_cancel(id)
+  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
+
+trap('SIGINT') { exit! }
+@ring.process_completions_loop

data/ext/iou/extconf.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'rubygems'
+require 'mkmf'
+require 'rbconfig'
+
+dir_config 'iou_ext'
+
+KERNEL_INFO_RE = /Linux (\d)\.(\d+)(?:\.)?((?:\d+\.?)*)(?:\-)?([\w\-]+)?/
+def get_config
+  config = { linux: !!(RUBY_PLATFORM =~ /linux/) }
+  raise "IOU only works on Linux!" if !config[:linux]
+
+  kernel_info = `uname -sr`
+  m = kernel_info.match(KERNEL_INFO_RE)
+  raise "Could not parse Linux kernel information (#{kernel_info.inspect})" if !m
+
+  version, major_revision, distribution = m[1].to_i, m[2].to_i, m[4]
+
+  combined_version = version.to_i * 100 + major_revision.to_i
+  raise "IOU 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
+end
+
+config = get_config
+puts "Building IOU (\n#{config.map { |(k, v)| "  #{k}: #{v}\n"}.join})"
+
+# require_relative 'zlib_conf'
+
+liburing_path = File.expand_path('../../vendor/liburing', __dir__)
+FileUtils.cd liburing_path do
+  system('./configure', exception: true)
+  FileUtils.cd File.join(liburing_path, 'src') do
+    system('make', 'liburing.a', exception: true)
+  end
+end
+
+if !find_header 'liburing.h', File.join(liburing_path, 'src/include')
+  raise "Couldn't find liburing.h"
+end
+
+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]
+$CFLAGS << ' -Wno-pointer-arith'
+
+CONFIG['optflags'] << ' -fno-strict-aliasing'
+
+create_makefile 'iou_ext'