cargo/util/
job.rs

Help
1//! Job management (mostly for windows)
2//!
3//! Most of the time when you're running cargo you expect Ctrl-C to actually
4//! terminate the entire tree of processes in play, not just the one at the top
5//! (cargo). This currently works "by default" on Unix platforms because Ctrl-C
6//! actually sends a signal to the *process group* rather than the parent
7//! process, so everything will get torn down. On Windows, however, this does
8//! not happen and Ctrl-C just kills cargo.
9//!
10//! To achieve the same semantics on Windows we use Job Objects to ensure that
11//! all processes die at the same time. Job objects have a mode of operation
12//! where when all handles to the object are closed it causes all child
13//! processes associated with the object to be terminated immediately.
14//! Conveniently whenever a process in the job object spawns a new process the
15//! child will be associated with the job object as well. This means if we add
16//! ourselves to the job object we create then everything will get torn down!
17
18pub use self::imp::Setup;
19
20pub fn setup() -> Option<Setup> {
21    unsafe { imp::setup() }
22}
23
24#[cfg(unix)]
25mod imp {
26    use std::env;
27
28    pub type Setup = ();
29
30    pub unsafe fn setup() -> Option<()> {
31        // There's a test case for the behavior of
32        // when-cargo-is-killed-subprocesses-are-also-killed, but that requires
33        // one cargo spawned to become its own session leader, so we do that
34        // here.
35        //
36        // ALLOWED: For testing cargo itself only.
37        #[allow(clippy::disallowed_methods)]
38        if env::var("__CARGO_TEST_SETSID_PLEASE_DONT_USE_ELSEWHERE").is_ok() {
39            libc::setsid();
40        }
41        Some(())
42    }
43}
44
45#[cfg(windows)]
46mod imp {
47    use std::io;
48    use std::mem;
49    use std::ptr;
50    use std::ptr::addr_of;
51
52    use tracing::info;
53
54    use windows_sys::Win32::Foundation::CloseHandle;
55    use windows_sys::Win32::Foundation::HANDLE;
56    use windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE;
57    use windows_sys::Win32::System::JobObjects::AssignProcessToJobObject;
58    use windows_sys::Win32::System::JobObjects::CreateJobObjectW;
59    use windows_sys::Win32::System::JobObjects::JobObjectExtendedLimitInformation;
60    use windows_sys::Win32::System::JobObjects::SetInformationJobObject;
61    use windows_sys::Win32::System::JobObjects::JOBOBJECT_EXTENDED_LIMIT_INFORMATION;
62    use windows_sys::Win32::System::JobObjects::JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
63    use windows_sys::Win32::System::Threading::GetCurrentProcess;
64
65    pub struct Setup {
66        job: Handle,
67    }
68
69    pub struct Handle {
70        inner: HANDLE,
71    }
72
73    fn last_err() -> io::Error {
74        io::Error::last_os_error()
75    }
76
77    pub unsafe fn setup() -> Option<Setup> {
78        // Creates a new job object for us to use and then adds ourselves to it.
79        // Note that all errors are basically ignored in this function,
80        // intentionally. Job objects are "relatively new" in Windows,
81        // particularly the ability to support nested job objects. Older
82        // Windows installs don't support this ability. We probably don't want
83        // to force Cargo to abort in this situation or force others to *not*
84        // use job objects, so we instead just ignore errors and assume that
85        // we're otherwise part of someone else's job object in this case.
86
87        let job = CreateJobObjectW(ptr::null_mut(), ptr::null());
88        if job == INVALID_HANDLE_VALUE {
89            return None;
90        }
91        let job = Handle { inner: job };
92
93        // Indicate that when all handles to the job object are gone that all
94        // process in the object should be killed. Note that this includes our
95        // entire process tree by default because we've added ourselves and
96        // our children will reside in the job once we spawn a process.
97        let mut info: JOBOBJECT_EXTENDED_LIMIT_INFORMATION;
98        info = mem::zeroed();
99        info.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
100        let r = SetInformationJobObject(
101            job.inner,
102            JobObjectExtendedLimitInformation,
103            addr_of!(info) as *const _,
104            mem::size_of_val(&info) as u32,
105        );
106        if r == 0 {
107            return None;
108        }
109
110        // Assign our process to this job object, meaning that our children will
111        // now live or die based on our existence.
112        let me = GetCurrentProcess();
113        let r = AssignProcessToJobObject(job.inner, me);
114        if r == 0 {
115            return None;
116        }
117
118        Some(Setup { job })
119    }
120
121    impl Drop for Setup {
122        fn drop(&mut self) {
123            // On normal exits (not ctrl-c), we don't want to kill any child
124            // processes. The destructor here configures our job object to
125            // **not** kill everything on close, then closes the job object.
126            unsafe {
127                let info: JOBOBJECT_EXTENDED_LIMIT_INFORMATION;
128                info = mem::zeroed();
129                let r = SetInformationJobObject(
130                    self.job.inner,
131                    JobObjectExtendedLimitInformation,
132                    addr_of!(info) as *const _,
133                    mem::size_of_val(&info) as u32,
134                );
135                if r == 0 {
136                    info!("failed to configure job object to defaults: {}", last_err());
137                }
138            }
139        }
140    }
141
142    impl Drop for Handle {
143        fn drop(&mut self) {
144            unsafe {
145                CloseHandle(self.inner);
146            }
147        }
148    }
149}
cargo/util/job.rs

cargo/util/
job.rs
