Linux Kernel pidfd + timerfd：AI Agent 子进程看门狗工程 —— 无竞态超时与生命周期管理

当 AI Agent 需要管理数十个并发子进程（代码执行、工具调用、沙箱容器）时，传统的 SIGCHLD + waitpid 模型充满了竞态条件。本文深入分析 Linux 5.x 引入的 pidfd 和 timerfd 如何彻底重构 Agent 子进程的生命周期管理系统，实现毫秒级精度的无竞态超时控制。

一、为什么传统的子进程管理模型在 AI Agent 场景下会崩

大多数 Python/Node.js 的后端子进程管理依赖于 SIGCHLD 信号 + waitpid(-1, WNOHANG) 的经典组合。但当你部署一个 AI Agent 服务，需要同时管理 20-50 并发子进程（代码解释器、数据库查询代理、文件处理器）时，这个模型有三个致命问题：

1. SIGCHLD 的丢失问题

如果多个子进程在同一毫秒内退出，SIGCHLD 是非排队的（non-queueing）。内核只会发送一次信号，而你的 handler 里 waitpid(-1) 只能收割一个僵尸。剩下的子进程将永远处于 ZOMBIE 状态，直到某个 loop iteration 碰巧执行了非阻塞 waitpid。在生产环境中，这表现为 RSS 缓慢泄漏。

2. 超时竞态窗口

你的 Agent 框架说"工具调用必须在 30 秒内完成"。但 SIGALRM 的精度只在秒级，而且与主线程的其他 I/O 操作产生竞态——如果主线程在处理一个 epoll_wait 时收到 SIGALRM，alarm 到 waitpid 收割之间可能有数十毫秒的延迟窗口，恰好足够子进程完成一次非法的 sys_write。

3. PID 复用竞态

在多线程进程池中，子进程退出和 waitpid 收割之间存在时间窗口。如果另一个线程在此窗口内 fork 并得到相同的 PID，waitpid 会收割错误的子进程。在 AI Agent 的异步循环中，这种竞态虽然概率低但后果严重。

这三个问题的共同根源是：经典模型将"子进程退出通知"和"事件分发"解耦了。内核通过异步信号通知用户态，用户态还要自己处理事件合并、超时定时器、信号竞争的复杂性。

二、pidfd：将子进程生命周期转化为文件事件

Linux 5.3（2019）引入了 CLONE_PIDFD flag 和 pidfd_open() 系统调用，允许你获得一个表示子进程的文件描述符。这个 FD 在子进程退出时变为可读（POLLIN），可以直接嵌入 epoll/select 事件循环。

2.1 核心 API

// 方法1：fork 时直接获取 pidfd
pid_t pid = clone(child_func, stack, CLONE_PIDFD | SIGCHLD, &pidfd_arg, sizeof(ino_t), &pidfd);

// 方法2：对已有 pidfd
int pidfd = pidfd_open(target_pid, 0);

// 嵌入 epoll
struct epoll_event ev = { .events = EPOLLIN, .data.ptr = &child_ctx };
epoll_ctl(epoll_fd, EPOLL_CTL_ADD, pidfd, &ev);

// 收割（获取退出状态）
struct pollfd pfd = { .fd = pidfd, .events = POLLIN };
poll(&pfd, 1, timeout_ms);
if (pfd.revents & POLLIN) {
    siginfo_t info;
    pidfd_getfd(pidfd, 0, 0);  // 必要时跨 ns 传递 fd
    waitid(P_PIDFD, pidfd, &info, WEXITED | WNOHANG);
}

2.2 解决竞态的核心：epoll 的统一事件循环

有了 pidfd，你的 AI Agent 主循环变成了一个纯粹的 epoll_wait：

┌─────────────────────────────────────────────────────┐
│                  AI Agent Main Loop                  │
├─────────────────────────────────────────────────────┤
│  epoll_wait() → 统一事件源                          │
│    ├── pidfd_ready → 子进程退出，收割状态            │
│    ├── timerfd_ready → 超时期限到达                   │
│    ├── socket_ready → LLM API 响应                   │
│    └── eventfd_ready → 内部任务信号                  │
└─────────────────────────────────────────────────────┘

这种设计优雅地消除了 SIGCHLD 的丢失问题：每个子进程都有一个独立的 FD，FD可读=子进程退出，不存在信号合并。同时，超时不再依赖 SIGALRM 中断主线程，而是通过 timerfd 集成到同一个 epoll_wait 中。

2.3 生产级 Rust 封装：async 子进程管理

use rustix::process::{pidfd_open, Pid, PidfdFlags};
use rustix::fd::{AsFd, AsRawFd, OwnedFd};
use std::os::unix::io::FromRawFd;
use tokio::io::unix::AsyncFd;

pub struct ChildWatcher {
    pid: Pid,
    pidfd: AsyncFd<OwnedFd>,
    timeout_ms: u64,
    progress: Arc<AtomicU64>,
}

impl ChildWatcher {
    pub fn new(pid: Pid, timeout_ms: u64) -> io::Result<Self> {
        let pidfd = pidfd_open(pid, PidfdFlags::empty())?;
        // 设置为非阻塞 + 注册到 tokio 的 epoll reactor
        let async_fd = AsyncFd::with_interest(
            OwnedFd::from(pidfd),
            tokio::io::Interest::READABLE,
        )?;
        Ok(Self { pid, pidfd: async_fd, timeout_ms, progress: Arc::new(AtomicU64::new(0)) })
    }

    pub async fn wait_with_timeout(self) -> Result<ExitStatus, WatchdogError> {
        // 创建 timerfd
        let timer = TimerFd::new(ClockId::Monotonic)?;
        timer.set_timeout_interval(self.timeout_ms);

        tokio::select! {
            // 子进程正常退出
            status = self.wait_pidfd() => status,
            // 超时
            _ = timer.expired() => {
                // 优雅终止 → SIGTERM → 500ms → SIGKILL
                self.graceful_shutdown().await?;
                Err(WatchdogError::Timeout(self.timeout_ms))
            }
        }
    }
}

三、timerfd：毫秒级精度的无中断超时引擎

Linux 的 timerfd_create() 将定时器转化为文件描述符，解决了传统定时器的三个问题：精度不足（从秒级到微秒/纳秒级）、信号投递竞态（无需 SIGALRM handler）、事件循环集成（直接 epoll）。

3.1 核心 API 与 AI Agent 场景选择

// 创建高精度单调时钟定时器
int tfd = timerfd_create(CLOCK_MONOTONIC, TFD_NONBLOCK | TFD_CLOEXEC);

// 单次触发：子进程执行超时
struct itimerspec its = {
    .it_value = { .tv_sec = 30, .tv_nsec = 0 },  // 30 秒超时
    .it_interval = { 0 },  // 单次触发
};
timerfd_settime(tfd, 0, &its, NULL);

// 周期性触发：Agent 心跳检测
struct itimerspec heartbeat = {
    .it_value = { .tv_sec = 5, .tv_nsec = 0 },
    .it_interval = { .tv_sec = 5, .tv_nsec = 0 },
};

关键设计决策：为什么用 CLOCK_MONOTONIC 而非 CLOCK_REALTIME

当 AI Agent 运行在容器或虚拟机上时，NTP 校时、主机时间跳跃 (adjtimex) 都会导致 CLOCK_REALTIME 回退或跳跃。如果你的超时基于 REALTIME，NTP 向前跳 3 秒会导致你预期 10 秒的子进程超时提前触发。CLOCK_MONOTONIC 从系统启动开始单调递增，不受外部时间源影响——这是生产环境 Agent 系统的铁律。

3.2 高精度超时 + epoll 的完美协作

pub struct AgentTimeoutEngine {
    inner: TimerFd,  // rustix::time::TimerFd
}

impl AgentTimeoutEngine {
    /// 配置自适应超时：根据 Agent 当前负载动态调整
    pub fn set_adaptive_timeout(&mut self, base_ms: u64, load_factor: f64) -> io::Result<()> {
        // 高负载时放宽超时，低负载时收紧超时
        let adjusted = (base_ms as f64 * load_factor) as u64;
        let clamped = adjusted.clamp(5000, 120_000);  // 5s - 120s
        
        let spec = TimerSpec {
            value: Duration::from_millis(clamped),
            interval: Duration::ZERO,
        };
        self.inner.set(TimerSetTimeFlags::Default, &spec)
    }
}

四、实战：构建 AI Agent 生产级看门狗系统

现在我们将 pidfd 和 timerfd 组合构建一个真实的 AI Agent 子进程管理框架。

4.1 架构总览

┌─────────────────────────────────────────────────────────────┐
│                   AI Agent Process Manager                    │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│   ┌───────────┐    ┌──────────────┐    ┌──────────────────┐  │
│   │ Tool Call │───▶│ Spawner      │───▶│ pidfd + timerfd  │  │
│   │ Executor  │    │ (fork/clone) │    │ Monitor Task     │  │
│   └───────────┘    └──────────────┘    └────────┬─────────┘  │
│                                                  │            │
│   ┌──────────────────────────────────────────────▼─────────┐ │
│   │              Event Reactor (epoll/io_uring)             │ │
│   │                                                         │ │
│   │   pidfd[0] ─▶ ChildExit                                 │ │
│   │   pidfd[1] ─▶ ChildExit                                 │ │
│   │   timer[0] ─▶ ToolTimeout                               │ │
│   │   timer[1] ─▶ HeartbeatTimeout                          │ │
│   └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

4.2 核心实现：自适应超时与优雅终止

use std::collections::HashMap;
use std::sync::Arc;
use tokio::sync::RwLock;

pub struct AiAgentProcessManager {
    children: Arc<RwHashMap<u32, ChildHandle>>,
    reactor: Arc<Reactor>,
    config: ManagerConfig,
}

struct ChildHandle {
    pidfd: AsyncFd<OwnedFd>,
    timer: TimerFd,
    task_id: TaskId,
    started_at: Instant,
    cancel_token: CancellationToken,
}

impl AiAgentProcessManager {
    pub async fn spawn_tool_process(
        &self,
        spec: ToolProcessSpec,
    ) -> Result<ChildHandleId, SpawnError> {
        let (pid, pidfd) = self.fork_child(&spec).await?;
        let task_id = self.generate_task_id();
        
        // 自适应超时：基础超时 × 工具复杂度因子 × 当前系统负载
        let timeout_ms = self.compute_adaptive_timeout(&spec);
        
        let timer = TimerFd::new(ClockId::Monotonic)?
            .set_timeout_millis(timeout_ms);
        
        let handle = ChildHandle {
            pidfd: AsyncFd::nonblocking(pidfd, Interest::READABLE)?,
            timer: timer.clone(),
            task_id,
            started_at: Instant::now(),
            cancel_token: CancellationToken::new(),
        };
        
        let id = self.children.insert(handle).await;
        
        // 监控任务：同时等待 pidfd 和 timer 就绪
        let handle_clone = self.children.clone();
        tokio::spawn(async move {
            monitor_child_lifecycle(id, handle_clone, spec.graceful_shutdown_timeout_ms).await;
        });
        
        Ok(ChildHandleId(id))
    }
}

async fn monitor_child_lifecycle(
    id: ChildHandleId,
    handles: Arc<RwHashMap<u32, ChildHandle>>,
    graceful_timeout_ms: u64,
) {
    let handle = handles.get(&id).await.unwrap();
    
    tokio::select! {
        // 子进程退出（正常/异常）
        result = handle.pidfd.readable() => {
            if let Some(status) = reap_child(&handle).await {
                match status {
                    ExitStatus::Code(0) => log::info!("[{}] 子进程正常退出", handle.task_id),
                    ExitStatus::Code(c) => log::warn!("[{}] 子进程异常退出，code={}", handle.task_id, c),
                    ExitStatus::Signal(s) => log::error!("[{}] 被信号终止 signal={:?}", handle.task_id, s),
                }
            }
        },
        
        // 超时触发
        _ = handle.timer.expired() => {
            log::warn!("[{}] 执行超时，启动优雅终止序列", handle.task_id);
            
            // Phase 1: SIGTERM + 500ms 宽限期
            unsafe { libc::kill(handle.raw_pid, libc::SIGTERM) };
            
            let grace_timer = TimerFd::new(ClockId::Monotonic)
                .unwrap()
                .set_timeout_millis(graceful_timeout_ms);
            
            tokio::select! {
                _ = handle.pidfd.readable() => {
                    // 子进程在宽限期内退出，正常收割
                    reap_child(&handle).await;
                }
                _ = grace_timer.expired() => {
                    // Phase 2: SIGKILL 强制终止
                    log::error!("[{}] 优雅终止失败，执行 SIGKILL", handle.task_id);
                    unsafe { libc::kill(handle.raw_pid, libc::SIGKILL) };
                    // 等待直到内核收割
                    handle.pidfd.readable().await.ok();
                    reap_child(&handle).await;
                }
            }
        }
    }
    
    handles.remove(&id).await;
}

4.3 容器化场景：跨 Namespace 的 PIDFD 传递

在 Kubernetes Pod 中运行 AI Agent 时，你的 Agent 进程通常在独立的 PID namespace 中管理子进程。但当你需要 sidecar 监控容器（如日志收集器、安全审计器）来观察 Agent 子进程时，PIDFD 的跨 namespace 传递 + pidfd_getfd 成为关键：

/// 通过 pidfd 跨 namespace 获取子进程的文件描述符
/// 此操作要求目标 namespace 的 user_ns 是当前 ns 的后代
pub fn transfer_fd_from_child(pidfd: &PidFd, target_fd: RawFd) -> io::Result<OwnedFd> {
    // pidfd_getfd: 从目标进程复制 fd 到当前进程
    // 需要 CAP_SYS_PTRACE 能力（由 Kubernetes securityContext 授予）
    let flags = 0;
    let raw = unsafe { pidfd_getfd(pidfd.as_raw_fd(), target_fd, flags) };
    
    if raw < 0 {
        return Err(io::Error::last_os_error());
    }
    
    Ok(unsafe { OwnedFd::from_raw_fd(raw) })
}

// 使用场景：sidecar 通过 pidfd 获取子进程的 stdout/stdout fd 进行日志流转发
let stdout_fd = transfer_fd_from_child(&child_pidfd, 1)?;
let log_stream = tokio::fs::File::from(stdout_fd);

4.4 完整的 epoll 事件分发主循环

pub async fn run_event_loop(&self) -> io::Result<()> {
    let mut events = Events::with_capacity(1024);
    
    loop {
        // 统一等待所有 fd 事件（pidfd、timerfd、网络 socket）
        let timeout = Duration::from_millis(100);  // 最大 100ms 响应延迟
        self.reactor.poll(&mut events, Some(timeout)).await?;
        
        for event in &events {
            match event.token {
                Token::ChildPidFd(idx) => {
                    self.handle_child_exit(idx).await?;
                }
                Token::TimerFd(idx) => {
                    // 读取 timerfd 的到期次数（防止事件合并）
                    let expirations = self.timers[idx].read()?;
                    self.handle_timeout(idx, expirations).await?;
                }
                Token::NetworkSocket => {
                    self.handle_incoming_request().await?;
                }
            }
        }
        
        // 周期性维护：清理超时任务、上报指标
        self.maintenance_tick().await;
    }
}

async fn handle_timeout(&self, timer_idx: usize, count: u64) -> io::Result<()> {
    let timer = &self.timers[timer_idx];
    
    match timer.kind {
        TimerKind::ChildTimeout(child_id) => {
            let handle = self.children.read().await.get(&child_id);
            if let Some(h) = handle {
                // SIGTERM → grace period → SIGKILL 三阶段终止
                self.initiate_graceful_shutdown(h.pid, h.cancel_token.clone()).await;
            }
        }
        TimerKind::Heartbeat => {
            // 检查所有活跃子进程的存活状态
            self.heartbeat_check().await;
        }
    }
    
    Ok(())
}

五、生产陷阱与调优策略

5.1 陷阱一：pidfd 的 PID Namespace 边界

pidfd 在当前 PID namespace 中有效。如果你的 Agent 进程在一个容器内运行，它只能管理同一 PID namespace 内的子进程。常见的错误模式是：

// ❌ 错误：在 init ns 中尝试监控其他 ns 的子进程
let host_pid = 12345;  // 属于不同的 user pid namespace
pidfd_open(host_pid, 0)?;  // 返回 ESRCH 或 EINVAL

// ✅ 正确：只在同一 ns 中使用
let child_pid = fork_inside_current_ns()?;
pidfd_open(child_pid, 0)?;  // OK

对策：如果你的架构需要跨 ns 监控（如 KVM 虚拟机内 Agent 监控 qemu 子进程），应使用 nsenter 进入目标 ns，或通过 Unix domain socket 委托该 ns 内的守护进程来管理。

5.2 陷阱二：PID 复用与 PIDFD 失效

极端情况下（PID 空间耗尽后复用），已存在的 pidfd 仍可指向被复用的进程。AI Agent 必须在使用 PIDFD 前通过 pidfd_send_signal 验证：

use rustix::pidfd::pidfd_send_signal;

fn validate_pid_still_valid(pidfd: &PidFd, expected_pid: Pid) -> io::Result<bool> {
    // 发送 signal 0：不实际发送信号，仅检查权限和进程存在性
    match pidfd_send_signal(pidfd, None) {
        Ok(()) => {
            // 额外验证：通过 /proc 检查 pid 是否一致
            let link = fs::read_link(format!("/proc/self/fd/{}", pidfd.as_raw_fd()))?;
            Ok(link.to_string_lossy() == format!("pidfd:{}", expected_pid))
        }
        Err(errno) if errno == Errno::ESRCH => Ok(false),  // 进程不存在
        Err(e) => Err(e.into()),
    }
}

实践中，Linux 已将 PID 复用延迟设置为至少 65536 个 PID 的窗口（/proc/sys/kernel/pid_max），且容器中 PID 通常从 1 开始分配，复用风险极低。但对运行时间超过数月的 Agent 服务，建议每次事件收割后重新验证。

5.3 陷阱三：Timerfd 在高频事件下的"到期合并"

如果多个 timerfd 在同一 epoll_wait batch 中触发一次性期，你只会被唤醒一次。读取 timerfd 返回的是"在此期间到期了几次"（对于周期性 timerfd），单次 trigger 的 timerfd 通常返回 1：

// 正确：处理到期次数
let expirations: u64 = unsafe {
    let mut buf = [0u8; 8];
    libc::read(tfd, buf.as_mut_ptr() as *mut _, 8);
    u64::from_ne_bytes(buf)
};

// 即使 event loss，expirations > 0 保证我们不会漏掉超时事件
if expirations > 0 {
    handle_timeout(tfd_handle, expirations);
}

5.4 性能数据：传统模型 vs pidfd+timerfd

在我的 AI Agent 基准测试平台（8 核 EPYC 7763，同时管理 50 个并发子进程，平均执行时间 2-8 秒）上获得的数据：

六、与 io_uring 的下一代表示

Linux 6.10+ 引入了 io_uring 子进程管理能力，包括直接等待子进程退出的 IORING_OP_WAITID。这是否意味着 pidfd 模型过时？

答案是否定的。io_uring 的 waitid 提供了一种批量、异步的收割方式，但 pidfd 的 epoll 集成在单进程内的事件分发场景中仍有优势：

1. 现有代码兼容性：大多数 Agent 框架（tokio、async-std）已经深度整合了 epoll 模型
2. 资源开销：pidfd 的开销（64 字节内核对象）远低于 io_uring 的 SQ/CQ ring pair
3. 与 timerfd 的天然集成：epoll_wait 同时监控 pidfd 和 timerfd，这是 io_uring 目前无法做到的（io_uring 没有原生的 timer 提交类型）

最佳实践：用 epoll(pidfd + timerfd) 处理高频子进程生命周期，用 io_uring 处理高频 I/O（网络、块设备）。两者协同而非竞争。

七、总结

Linux 5.x 引入的 pidfd 和 timerfd 从根本上解决了 AI Agent 子进程管理的三个核心难题：信号丢失（非排队信号问题）、超时竞态（SIGALRM 的异步中断模型）、PID 复用风险（waitpid 的时间窗口）。

核心设计哲学是将子进程生命周期管理统一到文件事件模型中——每个子进程不再是一个需要异步信号收割的潜在僵尸，而是一个可以直接 epoll 监听的文件描述符。配合 timerfd 的高精度单调时钟，你可以在同一个事件循环中实现毫秒级精度的超时控制，同时保持代码的简单性和可测试性。

对于 AI Agent 工程团队而言，这套模式的迁移成本极低：如果你的代码已经使用了 tokio，使用 AsyncFd + TimerFd 的实现量不超过 200 行 Rust。但它带来的收益是：零僵尸泄漏、可预测的超时行为、以及为工具调用隔离层提供的事件原生基础。

---

**关键要点回顾：**

- pidfd 将子进程退出转化为 POLLIN 事件，消除 SIGCHLD 丢失与竞态

- timerfd + CLOCK_MONOTONIC 提供毫秒级精度超时，不受 NTP 影响

- 两者通过 epoll 统一集成到 AI Agent 主事件循环

- 优雅终止三阶段：SIGTERM → grace_period → SIGKILL

- 生产部署注意 PID namespace 边界和 PID 复用验证