userfaultfd 1.0.0

data/lib/userfaultfd/handler.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+class UserfaultFD
+  # Owns either a Ruby callback thread or a GVL-free native handler thread.
+  class Handler
+    attr_reader :error
+
+    def initialize(uffd, mode: nil, io: nil, source: nil, &block)
+      raise ArgumentError, "choose a block or mode, not both" if mode && block
+      raise ArgumentError, "a block or mode is required" unless mode || block
+
+      @uffd = uffd
+      if block
+        raise DeadlockError, "strict mode cannot verify raw pointer faults" if UserfaultFD.strict
+
+        warn "userfaultfd: Ruby handlers require Region#read/write or a separate faulting process"
+        start_ruby_handler(block)
+      else
+        native_source = mode == :backing_file ? io : source
+        @native = uffd.__send__(:start_native_handler, mode, native_source)
+      end
+    end
+
+    def stop
+      if @native
+        @native.stop
+        return self
+      end
+      return self unless @thread
+      raise Error, "handler cannot stop itself" if Thread.current == @thread
+
+      @stop_writer.write_nonblock(".") rescue nil
+      @thread.join
+      @thread = nil
+      raise @error if @error
+
+      self
+    end
+
+    def running?
+      @native ? @native.running? : !!@thread&.alive?
+    end
+
+    private
+
+    def start_ruby_handler(block)
+      @stop_reader, @stop_writer = IO.pipe
+      @event_reader = @uffd.__send__(:start_event_reader)
+      @event_io = IO.for_fd(@event_reader.fileno, autoclose: false)
+      @children = []
+      @thread = Thread.new do
+        loop do
+          ready = IO.select([@event_io, @stop_reader])&.first
+          break if ready&.include?(@stop_reader)
+
+          @event_reader.read_events.each do |event|
+            @children << event.child_uffd if event.is_a?(ForkEvent)
+            block.call(event)
+          end
+        end
+      rescue StandardError => e
+        @error = e
+      ensure
+        begin
+          @event_reader.stop
+        rescue StandardError => e
+          @error ||= e
+        end
+        @children.each(&:close)
+        @stop_reader.close
+        @stop_writer.close
+      end
+      @thread.report_on_exception = false
+    end
+  end
+end

data/lib/userfaultfd/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class UserfaultFD
+  VERSION = "1.0.0"
+end

data/lib/userfaultfd.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "userfaultfd/version"
+
+# Linux userfaultfd descriptor and capability API.
+#
+# @!method self.supported?(user_mode_only: true)
+#   @param user_mode_only [Boolean] restrict faults to userspace; set false only
+#     on Linux before 5.11 when the caller has the required privilege
+#   @return [Boolean] whether a permitted userfaultfd can be initialized
+# @!method self.features(user_mode_only: true)
+#   @return [Array<Symbol>] features available from the running kernel
+# @!method initialize(features: nil, user_mode_only: true)
+#   @param features [Array<Symbol>, nil] features to require; by default fork
+#     events are attempted and omitted when the kernel denies permission
+#   @param user_mode_only [Boolean] restrict faults to userspace
+# @!method register(region, mode:)
+#   @param region [UserfaultFD::Region]
+#   @param mode [Symbol, Array<Symbol>] `:missing`, `:wp`, or `:minor`
+#   @return [Integer] ioctl bitmask supported for the range
+# @!method unregister(region)
+#   @return [nil]
+# @!method enabled_features
+#   @return [Array<Symbol>] features enabled for this descriptor
+class UserfaultFD
+  class Error < StandardError; end
+  class UnsupportedError < Error; end
+  class DeadlockError < Error; end
+
+  class << self
+    attr_accessor :strict
+  end
+
+  self.strict = false
+end
+
+require "userfaultfd/userfaultfd"
+require_relative "userfaultfd/handler"
+
+class UserfaultFD
+  def to_io
+    IO.for_fd(fileno, autoclose: false)
+  end
+
+  def start_handler(mode: nil, io: nil, source: nil, &block)
+    Handler.new(self, mode: mode, io: io, source: source, &block)
+  end
+end
+
+# A page-fault event. Resolution methods wake the faulting thread by default.
+class UserfaultFD::Fault
+  def write? = flags.include?(:write)
+  def wp? = flags.include?(:wp)
+  def minor? = flags.include?(:minor)
+end
+
+# Compatibility with the constant generated by the original gem skeleton.
+Userfaultfd = UserfaultFD

data/sig/userfaultfd.rbs

@@ -0,0 +1,93 @@
+class UserfaultFD
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class UnsupportedError < Error
+  end
+
+  class DeadlockError < Error
+  end
+
+  type feature = :pagefault_flag_wp | :event_fork | :event_remap | :event_remove | :event_unmap | :missing_hugetlbfs | :missing_shmem | :sigbus | :thread_id | :minor_hugetlbfs | :minor_shmem | :exact_address | :wp_hugetlbfs_shmem | :wp_unpopulated | :wp_async | :poison | :move
+  type register_mode = :missing | :wp | :minor
+  type native_mode = :zero_fill | :backing_file | :prefilled
+  type event = Fault | ForkEvent | RemapEvent | RemoveEvent | UnmapEvent
+
+  def self.supported?: (?user_mode_only: bool) -> bool
+  def self.features: (?user_mode_only: bool) -> Array[feature]
+  def self.strict: () -> bool
+  def self.strict=: (bool) -> bool
+
+  def initialize: (?features: Array[feature]?, ?user_mode_only: bool) -> void
+  def features: () -> Array[feature]
+  def enabled_features: () -> Array[feature]
+  def backend: () -> (:device | :syscall)
+  def fileno: () -> Integer
+  def to_io: () -> IO
+  def close: () -> nil
+  def closed?: () -> bool
+  def register: (Region, mode: register_mode | Array[register_mode]) -> Integer
+  def unregister: (Region) -> nil
+  def writeprotect: (Region, enabled: bool) -> nil
+  def read_events: (?Integer max) -> Array[event]
+  def start_handler: (mode: native_mode, ?io: IO?, ?source: Region?) -> Handler
+                   | () { (event) -> void } -> Handler
+
+  class Region
+    def initialize: (size: Integer, ?shared: bool, ?huge: bool) -> void
+    def address: () -> Integer
+    def to_ptr: () -> Integer
+    def size: () -> Integer
+    def page_size: () -> Integer
+    def read: (Integer offset, Integer length) -> String
+    def write: (Integer offset, String data) -> Integer
+    def madvise: (:dontneed | :remove) -> nil
+    def unmap: () -> nil
+    def unmapped?: () -> bool
+  end
+
+  class Fault
+    attr_reader address: Integer
+    attr_reader flags: Array[:write | :wp | :minor]
+    attr_reader thread_id: Integer?
+    def write?: () -> bool
+    def wp?: () -> bool
+    def minor?: () -> bool
+    def copy: (String, ?wake: bool) -> Integer
+    def zero: (?wake: bool) -> Integer
+    def continue: (?wake: bool) -> Integer
+    def poison: (?wake: bool) -> Integer
+    def move: (Region source, ?offset: Integer, ?wake: bool) -> Integer
+    def wake: () -> nil
+  end
+
+  class ForkEvent
+    attr_reader child_uffd: UserfaultFD
+  end
+
+  class RemapEvent
+    attr_reader from: Integer
+    attr_reader to: Integer
+    attr_reader length: Integer
+  end
+
+  class RemoveEvent
+    attr_reader start: Integer
+    attr_reader end: Integer
+  end
+
+  class UnmapEvent
+    attr_reader start: Integer
+    attr_reader end: Integer
+  end
+
+  class Handler
+    attr_reader error: StandardError?
+    def stop: () -> self
+    def running?: () -> bool
+  end
+end
+
+Userfaultfd: singleton(UserfaultFD)

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: userfaultfd
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Handle Linux user-space page faults safely without blocking Ruby's GVL.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions:
+- ext/userfaultfd/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- docs/gvl-and-page-faults.md
+- examples/dirty_tracking.rb
+- examples/lazy_mmap.rb
+- examples/oom_canary.rb
+- examples/post_copy_migration.rb
+- ext/userfaultfd/compat.h
+- ext/userfaultfd/constants.c
+- ext/userfaultfd/extconf.rb
+- ext/userfaultfd/userfaultfd.c
+- lib/userfaultfd.rb
+- lib/userfaultfd/handler.rb
+- lib/userfaultfd/version.rb
+- sig/userfaultfd.rbs
+homepage: https://github.com/ydah/userfaultfd
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/ydah/userfaultfd
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: Ruby bindings for Linux userfaultfd
+test_files: []