rightkit_child_process/
process_handle.rs

1use std::{
2    io,
3    process::ExitStatus,
4    sync::{Arc, Mutex, MutexGuard},
5    time::{Duration, SystemTime},
6};
7#[cfg(unix)]
8type PlatformChild = crate::unix_child::UnixChild;
9#[cfg(windows)]
10type PlatformChild = crate::spawn_windows::WindowsChild;
11#[cfg(unix)]
12use std::time::Instant;
13
14/// An independent exit reader. On Unix it shares the owner's cached reap state;
15/// on Windows it owns a duplicated process handle, never a borrowed handle value.
16/// Keeping this reader alive does not keep an owned process tree alive.
17///
18/// Unix: `wait`, `try_wait` and `wait_timeout` reap the leader when it has exited. The first
19/// reap by any path, this reader or the owner, permanently ends process-group signalling for
20/// the `OwnedChild` and every clone: the group id may be recycled from then on, so nothing is
21/// sent to it again. A reader that reaps therefore also means the owner can no longer kill
22/// descendants that outlive the leader.
23///
24/// [`wait_exited`](Self::wait_exited) is the monitor's call: it returns once the leader has
25/// exited **without reaping it**, so the owner can still terminate the group (the leader's
26/// zombie pins the group id) and then reap. A monitor thread that only needs to learn of the
27/// exit, to wake a run loop for instance, should use it, and leave the reap to the owner.
28#[derive(Debug)]
29pub struct ProcessHandle {
30    #[cfg(unix)]
31    child: Arc<Mutex<PlatformChild>>,
32    #[cfg(windows)]
33    handle: std::os::windows::io::OwnedHandle,
34    creation_time: Option<SystemTime>,
35    #[cfg(windows)]
36    creation_time_ticks: Option<u64>,
37}
38
39pub(crate) fn lock_child<T>(child: &Mutex<T>) -> MutexGuard<'_, T> {
40    child.lock().unwrap_or_else(|poison| poison.into_inner())
41}
42
43impl ProcessHandle {
44    pub(crate) fn new(
45        child: &Arc<Mutex<PlatformChild>>,
46        spawned_at: SystemTime,
47    ) -> io::Result<Self> {
48        #[cfg(unix)]
49        {
50            #[cfg(target_os = "macos")]
51            let creation_time = macos_creation_time(lock_child(child).id());
52            #[cfg(not(target_os = "macos"))]
53            let creation_time = Some(spawned_at);
54            let _ = spawned_at;
55            Ok(Self {
56                child: Arc::clone(child),
57                creation_time,
58            })
59        }
60        #[cfg(windows)]
61        {
62            use std::os::windows::io::AsHandle;
63            let handle = lock_child(child).as_handle().try_clone_to_owned()?;
64            let ticks = windows_creation_time(&handle);
65            let creation_time = ticks.and_then(|ticks| {
66                // FILETIME epoch precedes Unix by 11,644,473,600 seconds.
67                let ticks = ticks.checked_sub(116_444_736_000_000_000)?;
68                SystemTime::UNIX_EPOCH.checked_add(Duration::new(
69                    ticks / 10_000_000,
70                    ((ticks % 10_000_000) * 100) as u32,
71                ))
72            });
73            let _ = spawned_at;
74            Ok(Self {
75                handle,
76                creation_time,
77                creation_time_ticks: ticks,
78            })
79        }
80    }
81
82    pub fn try_clone(&self) -> io::Result<Self> {
83        Ok(Self {
84            #[cfg(unix)]
85            child: Arc::clone(&self.child),
86            #[cfg(windows)]
87            handle: self.handle.try_clone()?,
88            creation_time: self.creation_time,
89            #[cfg(windows)]
90            creation_time_ticks: self.creation_time_ticks,
91        })
92    }
93
94    /// Native creation time on Windows/macOS; spawn observation time on other Unix hosts.
95    pub fn creation_time(&self) -> Option<SystemTime> {
96        self.creation_time
97    }
98
99    /// Native Windows FILETIME, in 100 ns ticks since 1601-01-01 UTC.
100    #[cfg(windows)]
101    pub fn creation_time_ticks(&self) -> Option<u64> {
102        self.creation_time_ticks
103    }
104
105    pub fn try_wait(&self) -> io::Result<Option<ExitStatus>> {
106        #[cfg(unix)]
107        {
108            lock_child(&self.child).try_wait()
109        }
110        #[cfg(windows)]
111        {
112            self.windows_wait(0)
113        }
114    }
115
116    /// Blocks until the leader exits and reaps it (Unix) or until the process exits (Windows).
117    ///
118    /// Unix: a loop of non-blocking `try_wait` looks. Each look takes the shared lock and
119    /// releases it at once; between looks the thread sleeps, ending early at the child's exit
120    /// where the kernel offers an event (a hint, see `exit_watch`) and otherwise after 5 ms. The
121    /// lock is never held while this thread sleeps, so `kill`, `terminate_tree` and other
122    /// waiters run meanwhile (unless some other thread holds an `OwnedChild::child()` guard,
123    /// which is the lock itself), and no wait system call names the pid outside the lock: a
124    /// blocked `waitid(pid)` entered after another reader reaped the leader and the kernel
125    /// recycled the number would wait on an unrelated child.
126    pub fn wait(&self) -> io::Result<ExitStatus> {
127        #[cfg(unix)]
128        {
129            self.wait_until(None)?
130                .ok_or_else(|| io::Error::other("infinite process wait unexpectedly timed out"))
131        }
132        #[cfg(windows)]
133        {
134            self.windows_wait(u32::MAX)?
135                .ok_or_else(|| io::Error::other("infinite process wait unexpectedly timed out"))
136        }
137    }
138
139    /// The wait shared by `wait` and `wait_timeout`: `Ok(None)` when `deadline` passed first.
140    #[cfg(unix)]
141    fn wait_until(&self, deadline: Option<Instant>) -> io::Result<Option<ExitStatus>> {
142        crate::unix_child::wait_shared(&self.child, deadline)
143    }
144
145    /// Blocks until the leader has exited, and does not reap it.
146    ///
147    /// Unix: returns when the leader is a zombie (or was already reaped by someone). The zombie
148    /// still pins the pid and the process-group id, so the owner can keep signalling the group
149    /// (`OwnedChild::wait_or_kill`, `terminate_tree*`) and then reap. This is the call for an
150    /// exit monitor that must not end the owner's ability to kill descendants that outlive the
151    /// leader; `wait` and `try_wait` reap and do end it. Waits like [`wait`](Self::wait), with
152    /// the non-reaping `waitid(WNOHANG | WNOWAIT)` probe as its look. Hosts with no verified
153    /// non-reaping probe (Unix other than Linux, Android, macOS and iOS) have nothing to
154    /// observe with, so there this reaps exactly like `wait`.
155    ///
156    /// Windows: returns once the process has exited; nothing is reaped there.
157    pub fn wait_exited(&self) -> io::Result<()> {
158        #[cfg(unix)]
159        {
160            if !crate::unix_child::CAN_OBSERVE_WITHOUT_REAPING {
161                return self.wait().map(|_| ());
162            }
163            self.observe_exit(None).map(|_| ())
164        }
165        #[cfg(windows)]
166        {
167            self.windows_wait(u32::MAX)?
168                .map(|_| ())
169                .ok_or_else(|| io::Error::other("infinite process wait unexpectedly timed out"))
170        }
171    }
172
173    /// [`wait_exited`](Self::wait_exited) with a limit: `true` once the leader has exited
174    /// (without reaping it on Linux, Android, macOS and iOS), `false` if `timeout` passed first.
175    /// For a caller that must enforce a deadline and still keep the group killable while it
176    /// drains the leader's pipes; it reaps afterwards with `wait`. Hosts with no non-reaping
177    /// probe behave like [`wait_timeout`](Self::wait_timeout).
178    pub fn wait_exited_timeout(&self, timeout: Duration) -> io::Result<bool> {
179        #[cfg(unix)]
180        {
181            if !crate::unix_child::CAN_OBSERVE_WITHOUT_REAPING {
182                return self.wait_timeout(timeout).map(|status| status.is_some());
183            }
184            self.observe_exit(Some(timeout))
185        }
186        #[cfg(windows)]
187        {
188            self.wait_timeout(timeout).map(|status| status.is_some())
189        }
190    }
191
192    /// Looks at the leader without reaping it until it has exited or `limit` has passed.
193    #[cfg(unix)]
194    fn observe_exit(&self, limit: Option<Duration>) -> io::Result<bool> {
195        let deadline = limit.and_then(|limit| Instant::now().checked_add(limit));
196        crate::unix_child::observe_shared(&self.child, deadline)
197    }
198
199    pub fn wait_timeout(&self, timeout: Duration) -> io::Result<Option<ExitStatus>> {
200        #[cfg(windows)]
201        {
202            let started = std::time::Instant::now();
203            loop {
204                let remaining = timeout.saturating_sub(started.elapsed());
205                // Round up sub-millisecond waits; reserve INFINITE for wait().
206                let millis = remaining.as_millis()
207                    + u128::from(!remaining.subsec_nanos().is_multiple_of(1_000_000));
208                let millis = millis.min(u128::from(u32::MAX - 1)) as u32;
209                if let Some(status) = self.windows_wait(millis)? {
210                    return Ok(Some(status));
211                }
212                if started.elapsed() >= timeout {
213                    return Ok(None);
214                }
215            }
216        }
217        #[cfg(unix)]
218        {
219            self.wait_until(Instant::now().checked_add(timeout))
220        }
221    }
222
223    #[cfg(windows)]
224    fn windows_wait(&self, millis: u32) -> io::Result<Option<ExitStatus>> {
225        use std::os::windows::{io::AsRawHandle, process::ExitStatusExt};
226        use windows::Win32::{
227            Foundation::{HANDLE, WAIT_OBJECT_0, WAIT_TIMEOUT},
228            System::Threading::{GetExitCodeProcess, WaitForSingleObject},
229        };
230        let handle = HANDLE(self.handle.as_raw_handle() as _);
231        match unsafe { WaitForSingleObject(handle, millis) } {
232            WAIT_TIMEOUT => Ok(None),
233            WAIT_OBJECT_0 => {
234                let mut code = 0;
235                unsafe { GetExitCodeProcess(handle, &mut code) }
236                    .map_err(crate::process_windows::os_error)?;
237                Ok(Some(ExitStatus::from_raw(code)))
238            }
239            _ => Err(io::Error::last_os_error()),
240        }
241    }
242}
243
244#[cfg(windows)]
245impl std::os::windows::io::AsHandle for ProcessHandle {
246    fn as_handle(&self) -> std::os::windows::io::BorrowedHandle<'_> {
247        std::os::windows::io::AsHandle::as_handle(&self.handle)
248    }
249}
250
251#[cfg(windows)]
252fn windows_creation_time(handle: &std::os::windows::io::OwnedHandle) -> Option<u64> {
253    use std::os::windows::io::AsRawHandle;
254    use windows::Win32::{
255        Foundation::{FILETIME, HANDLE},
256        System::Threading::GetProcessTimes,
257    };
258    let (mut creation, mut exit, mut kernel, mut user) = (
259        FILETIME::default(),
260        FILETIME::default(),
261        FILETIME::default(),
262        FILETIME::default(),
263    );
264    unsafe {
265        GetProcessTimes(
266            HANDLE(handle.as_raw_handle() as _),
267            &mut creation,
268            &mut exit,
269            &mut kernel,
270            &mut user,
271        )
272    }
273    .ok()?;
274    Some((u64::from(creation.dwHighDateTime) << 32) | u64::from(creation.dwLowDateTime))
275}
276
277#[cfg(target_os = "macos")]
278fn macos_creation_time(pid: u32) -> Option<SystemTime> {
279    let mut info = std::mem::MaybeUninit::<libc::proc_bsdinfo>::zeroed();
280    let size = std::mem::size_of::<libc::proc_bsdinfo>();
281    // libproc writes exactly proc_bsdinfo for this flavor; check size before reading it.
282    let written = unsafe {
283        libc::proc_pidinfo(
284            pid as i32,
285            libc::PROC_PIDTBSDINFO,
286            0,
287            info.as_mut_ptr().cast(),
288            size as i32,
289        )
290    };
291    if written != size as i32 {
292        return None;
293    }
294    let info = unsafe { info.assume_init() };
295    SystemTime::UNIX_EPOCH
296        .checked_add(Duration::from_secs(info.pbi_start_tvsec))?
297        .checked_add(Duration::from_micros(info.pbi_start_tvusec))
298}
rightkit_child_process/process_handle.rs

rightkit_child_process/
process_handle.rs
