Bringing Linux pidfd to Ruby

RubyKaigi 2025

About Me

• Maciej Mensfeld
• Software Architect
• 17+ years in Ruby

Work @ Mend.io

Supply Chain Security & AI/LLM Security

Creator of Karafka

Ruby & Rails Kafka Processing Framework

Maintainer of Shoryuken

A efficient Amazon SQS processor for Ruby

(no logo yet, working on it)

RubyGems Security Team Member

Today's Journey

1. Challenges
2. Solutions
3. Implementation
4. Lessons & Future Directions

I Love RubyKaigi

But I'm Not Delusional

The Challenge

The I/O-bound Myth

The Goal

Add CPU-friendly Parallelization to Karafka and Shoryuken

CPU Parallelization Options

Ractors: Current Reality

no Ractor:
  1.742630   0.023948   1.766578 (  1.770248)
Ractor
  12.724407   1.142691  13.867098 (  4.854311)
    

So... forks!

The Architecture

First Attempt

"Like any good Rubyist, I KISS..."

PID-Based Fork

def fork_workers(count = 4)
  count.times do
    pid = fork do
      Karafka::Cli::Server.call
    end
    
    @worker_pids << pid
  end
end

PID-Based Signals

def stop_workers
  @worker_pids.each do |pid|
    Process.kill(:TERM, pid)
  end
end

PID-Based Wait

def wait_for_workers
  @worker_pids.each do |pid|
    Process.waitpid(pid)
  end
end

Initial Results

It worked!

(in development)

The Code Review

I showed my work to KJ Tsanaktsidis from the Ruby Core team...

KJ's Feedback

My Reaction

🤔

The Problems

There were some flaws in my approach

Problem 1

PID Reuse

PID Reuse

• PIDs are just numbers
• Limited pool
• Recycled when processes terminate

PID Reuse Visualized

A Familiar Experience?

ps aux | grep ruby
user     12345  2.5  0.8  Sl   10:25   0:18 ruby app.rb

kill -9 12345
bash: kill: (12345) - No such process

PID Reuse Impact

• Sending signals to wrong processes
• Incorrect monitoring results
• Potential security issues

PID Security Issues

• CVE-2019-6133: PID race allowed sandbox escape
• PID recycling enables privilege escalation attacks
• Mistakenly terminating critical system processes

Problem 2

Signal Race Conditions

The Execution Environment Challenge

Signal Races

• SIGCHLD sent when child exits
• Any code can set a SIGCHLD handler
• First handler to call waitpid wins
• Exit status can only be retrieved once

# Process level handler
Signal.trap(:CHLD) do
  begin
    pid, status = Process.waitpid2(-1, Process::WNOHANG)
    if pid
      puts "MAIN: Signal handler reaped child" \
        " PID #{pid} (exit code: #{status.exitstatus})"
    end
  rescue Errno::ECHILD
    # No children left to reap
  end
end

# Library level handler
begin
  waited_pid, status = Process.waitpid2(pid)
  puts "LIBRARY: Successfully reaped PID #{waited_pid}"
  return status
rescue Errno::ECHILD
  puts "LIBRARY: ERROR - Child PID #{pid} was reaped"
  return nil
end

Exit Code Races: Not Solved fully by pidfd

Problem 3

Process Hierarchy Limitations

• SIGCHLD only sent to immediate parent
• No built-in tracking of process trees
• Orphaned processes reassigned to init (PID 1)
• No direct way to monitor non-child processes

PID-based Polling

# Poll every second
Thread.new do
  loop do
    begin
      # Try sending signal 0 to check existence
      Process.kill(0, pid)
      puts "Process #{pid} is running"
    rescue Errno::ESRCH
      puts "Process #{pid} has exited"
      break
    end
    sleep 1  # CPU waste, latency
  end
end

PID usage in Ruby

• Puma, Unicorn, Sidekiq, Pitchfork already handle forking
• All use PID-based tracking
• io-event is the only Ruby lib using pidfd (so far)

pidfd to the rescue

• Process File Descriptor
• Added in Linux 5.3 (2019)
• Stable reference to a process
• Solves two out of our three problems

What is a File Descriptor?

file = File.open("example.txt")
puts file.fileno  # Returns the file descriptor number

pidfd Benefits

• Stable Process Reference
• Immune to PID Reuse
• Pollable (select/poll/epoll)
• Race-Free Signal Delivery

PID vs pidfd

Core pidfd API

The Problem

Ruby has no pidfd support

Building the Bridge

How to use pidfd from Ruby?

Bringing pidfd to Ruby

Foreign Function Interface

• Ruby's FFI lets us call C functions
• We can use it to access Linux syscalls
• Requires mapping syscall numbers
• Needs platform detection code

FFI Implementation

class Pidfd
  extend FFI::Library
  
  begin
    ffi_lib FFI::Library::LIBC

    attach_function :fdpid_open, :syscall, 
                   %i[long int uint], :int
    attach_function :fdpid_signal, :syscall, 
                   %i[long int int pointer uint], :int
    attach_function :waitid, 
                   %i[int int pointer uint], :int
                   
    # Syscall numbers (Linux x86_64)
    PIDFD_OPEN = 434
    PIDFD_SEND_SIGNAL = 424

    API_SUPPORTED = true
  rescue LoadError
    API_SUPPORTED = false
  end
end

Platform Detection

def self.supported?
  # If FFI failed to load
  return false unless API_SUPPORTED
  
  # Won't work on macOS or Windows
  return false if RUBY_DESCRIPTION.include?('darwin')
  return false if RUBY_DESCRIPTION.match?(/mswin|ming|cygwin/)
  
  # Not all OSes may support this (BSD)
  new(::Process.pid)
  true
rescue Errors::PidfdOpenFailedError
  false
end

Pidfd Initialization

def initialize(pid)
  @mutex = Mutex.new
  @pid = pid
  # Call syscall to get pidfd
  @pidfd = open(pid)
  # Wrap as Ruby IO for polling
  @pidfd_io = IO.new(@pidfd)
end

private

def open(pid)
  pidfd = fdpid_open(
    pidfd_open_syscall,
    pid,
    0
  )
  
  return pidfd if pidfd != -1
  
  raise Errors::PidfdOpenFailedError, pidfd
end

Process Status Check

def alive?
  @pidfd_select ||= [@pidfd_io]
  
  @mutex.synchronize do
    return false if @cleaned
    
    # pidfd becomes readable when process terminates
    # nil means not readable = still alive
    IO.select(@pidfd_select, nil, nil, 0).nil?
  end
end

Signal Delivery

def signal(sig_name)
  @mutex.synchronize do
    return false if @cleaned
    # Never signal dead processes
    return false unless alive?
    
    result = fdpid_signal(
      pidfd_signal_syscall,
      @pidfd,
      Signal.list.fetch(sig_name),
      nil,
      0
    )
    
    return true if result.zero?
    
    raise Errors::PidfdSignalFailedError, result
  end
end

Zombie Process Cleanup

def cleanup
  @mutex.synchronize do
    return if @cleaned
    
    # Reap the process
    begin
      waitid(P_PIDFD, @pidfd, nil, WEXITED)
    rescue Errno::ECHILD
      # Ignore
      # should not happen unless traps overwritten
    end
    
    # Clean up resources
    @pidfd_io.close
    @pidfd_select = nil
    @pidfd_io = nil
    @pidfd = nil
    @cleaned = true
  end
end

Pidfd API Capabilities

pidfd.alive?    # Check process state
pidfd.signal()  # Send signals safely
pidfd.cleanup() # Prevent zombie processes

State Machine Management

def control
  @nodes.each do |node|
    if node.alive?
      next if terminate_if_hanging(node)
      next if stop_if_not_healthy(node)
      next if stop_if_not_responding(node)
    else
      next if cleanup_one(node)
      next if restart_after_timeout(node)
    end
  end
end

Orphan Detection Code

def on_statistics_emitted(_event)
  periodically do
    Kernel.exit!(orphaned_exit_code) if node.orphaned?

    node.healthy
  end
end

No orphaned processes if supervisor crashes

Orphan Check Implementation

def orphaned?
  # Check if supervisor is still alive
  !@parent_pidfd.alive?
end

Each worker tracks its parent with pidfd

Limitations

• Linux 5.3+ only
• Not available on macOS or Windows
• Requires FFI and syscall mapping
• Limited to processes in same PID namespace
• No built-in process group operations
• Can't access descendants automatically

When to Use pidfd

Lessons Learned

• There are so many cool low-level OS features
• Process management is much harder than it appears
• Ruby core team members are amazing!
• Stable process references are safer than PIDs

pidfd is a solution for specific edge cases, not a general replacement for PIDs

Future Directions

Thank You

Questions?