pidfd 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b451bbd5118d146b771d9163937c333e2b1bb648388844e3a3701020e9ce6c9c
-  data.tar.gz: c453e8405ab02686a13c1431e2bed5eebba174a4f1abd053c9a0c522727fd280
+  metadata.gz: 7c498e89e5d07cb2d256846016a70bf0aece20a8bf145664cf6516637b7b4b84
+  data.tar.gz: 45ef88b384618b3d83b9fcc147b582154e01dd05fad36875e529d56cbe964d97
 SHA512:
-  metadata.gz: 9ed79dfc7bac514be6b9decbb4ccd6a8e25e4f1f8c917c9d7e8142fb3e7d564c9f530a541a1b762322e40d87eb4b5450c3d8e5d7ec03fe3b79ac7d7a3ce05e08
-  data.tar.gz: aaacf4562f99d333976ff5227038c0c50972e8bcc82c9f188bb9188760122d146c62c4e7d4c9761eef92a5cc4b36b9d45ba8899be66109f8da21f7fc7264672e
+  metadata.gz: e0454d5fe4fefd3a5095a63a79666e1d7ea794ce8b4cfd5b96475c79bab981ddc82a750fb77a26ae8fb04fbf5416ffda053eca8efa64b0fa4d049b5c2cc0f544
+  data.tar.gz: 3b034e4305df0eba9ccd3e718a32e6a47632602a1176064f36e9684b626e406922538687065c5f32dc005e7f94f9508038a9a8018b8719bfadb66c6942917e2b

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Pidfd Changelog
 
+## 1.0.1 (2026-11-02)
+- [Breaking] Drop support for Ruby 3.2 (EOL March 2026). Minimum required Ruby is now 3.3.
+- [Enhancement] Use dynamic Ruby warning category opt-in in test helpers
+- [Change] Document Linux 5.4 as the minimum kernel. `#cleanup` uses `waitid(P_PIDFD)`, which Linux supports since 5.4. The 0.5.0 entry stated 5.3.
+
 ## 1.0.0 (2025-09-05)
 - [Change] No changes. Just versioning update.
 

data/README.md

@@ -24,7 +24,7 @@ Pidfds provide a **stable reference** to a process that remains valid even if th
 - **Race-free signal delivery** - Signals always go to the intended process
 - **Reliable process monitoring** - Know definitively when a process exits
 - **Thread-safe operations** - No TOCTTOU races
-- **Pollable file descriptors** - Integrate with event loops efficiently
+- **Pollable file descriptors** - The kernel marks a pidfd readable when its process exits
 
 ## When to Use This Gem
 
@@ -38,7 +38,7 @@ Use pidfd when you need:
 
 Don't use pidfd for:
 - macOS or Windows (Linux-only feature)
-- Kernels older than Linux 5.3
+- Kernels older than Linux 5.4
 - Simple parent-child relationships (traditional wait works fine)
 
 ## Installation
@@ -63,8 +63,8 @@ gem install pidfd
 
 ## Requirements
 
-- Linux kernel 5.3 or newer
-- Ruby 3.2 or newer
+- Linux kernel 5.4 or newer
+- Ruby 3.3 or newer
 - FFI gem
 
 ## Usage
@@ -115,13 +115,13 @@ pidfd = Pidfd.new(pid)
 pidfd.signal('TERM') # Guaranteed to hit the right process or fail safely
 ```
 
-### Integration with Event Loops
+### Waiting for a Process to Exit
+
+`Pidfd` does not expose its file descriptor, so you cannot pass a `Pidfd` to `IO.select` or an event loop. `alive?` checks the pidfd with a zero timeout, so the check does not wait for the process to exit. To wait for a process to exit, poll `alive?`:
 
 ```ruby
-# Pidfd provides a pollable file descriptor
 pidfd = Pidfd.new(child_pid)
 
-# Use with IO.select for non-blocking monitoring
 loop do
   if pidfd.alive?
     # Process still running
@@ -146,6 +146,8 @@ else
 end
 ```
 
+`Pidfd.supported?` tests only `pidfd_open`, so it also returns `true` on Linux 5.3. On 5.3, `#cleanup` does not reap the process, because `waitid(P_PIDFD)` needs Linux 5.4. If your code can run on 5.3, check the kernel version yourself.
+
 ### Fallback Strategy
 
 ```ruby
@@ -202,7 +204,7 @@ end
 - **Efficient**: Pidfd operations are kernel-level, very fast
 - **Low overhead**: Minimal memory usage per pidfd
 - **Scalable**: Handles thousands of processes efficiently
-- **Non-blocking**: Supports async operation patterns
+- **Non-blocking**: The `alive?` check uses a zero timeout and does not wait for the process to exit
 
 ## Security
 

data/lib/pidfd/errors.rb

@@ -2,14 +2,18 @@
 
 class Pidfd
   # Namespace for all the pidfd errors
+  # @api public
   module Errors
     # Base error class for all pidfd errors
+    # @api public
     BaseError = Class.new(StandardError)
 
     # Error raised when pidfd_open syscall fails
+    # @api public
     PidfdOpenFailedError = Class.new(BaseError)
 
     # Error raised when pidfd_signal syscall fails
+    # @api public
     PidfdSignalFailedError = Class.new(BaseError)
   end
 end

data/lib/pidfd/version.rb

@@ -2,5 +2,6 @@
 
 class Pidfd
   # Current version of the pidfd gem
-  VERSION = '1.0.0'
+  # @api public
+  VERSION = "1.0.1"
 end

data/lib/pidfd.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-require 'ffi'
+require "ffi"
 
 # Main class that wraps Linux pidfd functionality for Ruby
+# @api public
 class Pidfd
   extend FFI::Library
 
@@ -29,29 +30,33 @@ class Pidfd
   # Wait for child processes that have exited
   WEXITED = 4
 
-  # Default syscall numbers for x86_64 Linux
-  # These can be overridden if needed for different architectures
-  # Pidfd open call number
+  # Default syscall numbers for x86_64 Linux. These can be overridden if needed for different
+  # architectures. Pidfd open call number
+  # @api public
   DEFAULT_PIDFD_OPEN_SYSCALL = 434
 
   # Pidfd signal call number
+  # @api public
   DEFAULT_PIDFD_SIGNAL_SYSCALL = 424
 
   private_constant :P_PIDFD, :WEXITED
 
   class << self
     # @return [Integer] syscall number for pidfd_open
+    # @api public
     attr_accessor :pidfd_open_syscall
 
     # @return [Integer] syscall number for pidfd_signal
+    # @api public
     attr_accessor :pidfd_signal_syscall
 
     # @return [Boolean] true if syscall is supported via FFI
+    # @api public
     def supported?
       # If we were not even able to load the FFI C lib, it won't be supported
       return false unless API_SUPPORTED
       # Won't work on macOS because it does not support pidfd
-      return false if RUBY_DESCRIPTION.include?('darwin')
+      return false if RUBY_DESCRIPTION.include?("darwin")
       # Won't work on Windows for the same reason as on macOS
       return false if RUBY_DESCRIPTION.match?(/mswin|ming|cygwin/)
 
@@ -71,6 +76,7 @@ class Pidfd
   self.pidfd_signal_syscall = DEFAULT_PIDFD_SIGNAL_SYSCALL
 
   # @param pid [Integer] pid of the node we want to work with
+  # @api public
   def initialize(pid)
     @mutex = Mutex.new
 
@@ -80,6 +86,7 @@ class Pidfd
   end
 
   # @return [Boolean] true if given process is alive, false if no longer
+  # @api public
   def alive?
     @pidfd_select ||= [@pidfd_io]
 
@@ -98,6 +105,7 @@ class Pidfd
 
   # Cleans the zombie process
   # @note This should run **only** on processes that exited, otherwise will wait
+  # @api public
   def cleanup
     @mutex.synchronize do
       return if @cleaned
@@ -117,6 +125,7 @@ class Pidfd
   # @return [Boolean] true if signal was sent, otherwise false or error raised. `false`
   #   returned when we attempt to send a signal to a dead process
   # @note It will not send signals to dead processes
+  # @api public
   def signal(sig_name)
     @mutex.synchronize do
       return false if @cleaned
@@ -155,5 +164,5 @@ class Pidfd
   end
 end
 
-require_relative 'pidfd/version'
-require_relative 'pidfd/errors'
+require_relative "pidfd/version"
+require_relative "pidfd/errors"

data/pidfd.gemspec

@@ -1,33 +1,34 @@
 # frozen_string_literal: true
 
-require_relative 'lib/pidfd/version'
+require_relative "lib/pidfd/version"
 
 Gem::Specification.new do |spec|
-  spec.name = 'pidfd'
+  spec.name = "pidfd"
   spec.version = Pidfd::VERSION
-  spec.authors = ['Maciej Mensfeld']
-  spec.email = ['maciej@mensfeld.pl']
+  spec.authors = ["Maciej Mensfeld"]
+  spec.email = ["maciej@mensfeld.pl"]
 
-  spec.summary = 'Ruby wrapper for Linux pidfd system calls'
-  spec.homepage = 'https://github.com/mensfeld/pidfd'
-  spec.license = 'MIT'
+  spec.summary = "Ruby wrapper for Linux pidfd system calls"
+  spec.homepage = "https://github.com/mensfeld/pidfd"
+  spec.license = "MIT"
   spec.description = <<~DESC
     Provides race-free process management using Linux pidfd (process file descriptors) for safer
     signal delivery and process monitoring
   DESC
 
-  spec.required_ruby_version = '>= 3.2.0'
+  spec.required_ruby_version = ">= 3.3.0"
 
-  spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
-  spec.metadata['source_code_uri'] = 'https://github.com/mensfeld/pidfd'
-  spec.metadata['changelog_uri'] = 'https://github.com/mensfeld/pidfd/blob/main/CHANGELOG.md'
-  spec.metadata['documentation_uri'] = 'https://github.com/mensfeld/pidfd#readme'
-  spec.metadata['rubygems_mfa_required'] = 'true'
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["source_code_uri"] = "https://github.com/mensfeld/pidfd"
+  spec.metadata["changelog_uri"] = "https://github.com/mensfeld/pidfd/blob/master/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://github.com/mensfeld/pidfd#readme"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/mensfeld/pidfd/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   # Specify which files should be added to the gem when it is released.
-  spec.files = Dir.glob('{lib}/**/*') + %w[LICENSE CHANGELOG.md README.md pidfd.gemspec]
-  spec.require_paths = ['lib']
+  spec.files = Dir.glob("{lib}/**/*") + %w[LICENSE CHANGELOG.md README.md pidfd.gemspec]
+  spec.require_paths = ["lib"]
 
-  spec.add_dependency 'ffi', '>= 1.15'
+  spec.add_dependency "ffi", ">= 1.15"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pidfd
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -46,8 +46,9 @@ metadata:
   homepage_uri: https://github.com/mensfeld/pidfd
   allowed_push_host: https://rubygems.org
   source_code_uri: https://github.com/mensfeld/pidfd
-  changelog_uri: https://github.com/mensfeld/pidfd/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/mensfeld/pidfd/blob/master/CHANGELOG.md
   documentation_uri: https://github.com/mensfeld/pidfd#readme
+  bug_tracker_uri: https://github.com/mensfeld/pidfd/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -56,14 +57,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Ruby wrapper for Linux pidfd system calls
 test_files: []