proc_cli/commands/
stop.rs

1//! Stop command - Graceful process termination (SIGTERM)
2//!
3//! Usage:
4//!   proc stop 1234              # Stop PID 1234
5//!   proc stop :3000             # Stop process on port 3000
6//!   proc stop node              # Stop the processes named node
7//!   proc stop node --cmd        # ... or with node anywhere in their command line
8//!   proc stop 1234 5678         # Stop several targets: separate arguments
9//!   proc stop :3000 :8080 node  # Mixed targets (port + port + name)
10//!
11//! Commas still work (`proc stop :3000,:8080`) but are deprecated.
12
13#[cfg(unix)]
14use crate::core::parse_signal_name;
15use crate::core::{
16    apply_filters, apply_to_each, flatten_targets, resolve_targets_excluding_self, NameMatch,
17    Process,
18};
19use crate::error::{ProcError, Result};
20use crate::ui::Printer;
21use clap::Args;
22
23/// Stop process(es) gracefully with SIGTERM
24#[derive(Args, Debug)]
25pub struct StopCommand {
26    /// Target(s): process name, PID, or :port (separate arguments for several)
27    #[arg(required = true, num_args = 1.., value_parser = crate::core::validate_target_arg)]
28    target: Vec<String>,
29
30    /// Skip confirmation prompt
31    #[arg(long, short = 'y')]
32    yes: bool,
33
34    /// Show what would be stopped without actually stopping
35    #[arg(long)]
36    dry_run: bool,
37
38    /// Output as JSON
39    #[arg(long, short = 'j')]
40    json: bool,
41
42    /// Show verbose output
43    #[arg(long, short = 'v')]
44    verbose: bool,
45
46    /// Timeout in seconds to wait before force kill
47    #[arg(long, short, default_value = "10")]
48    timeout: u64,
49
50    /// Filter by directory; takes the next word as the directory unless it starts with '-'
51    /// (bare --in is the current directory, --in=DIR is explicit)
52    #[arg(long = "in", short = 'i', num_args = 0..=1, default_missing_value = ".")]
53    pub in_dir: Option<String>,
54
55    /// Filter by process name
56    #[arg(long = "by", short = 'b')]
57    pub by_name: Option<String>,
58
59    /// Match name targets and --by as a substring of the process name or full command line (like pkill -f)
60    #[arg(long)]
61    pub cmd: bool,
62
63    /// Initial signal to send instead of SIGTERM (e.g. HUP, USR1, INT)
64    #[arg(long, short = 'S')]
65    pub signal: Option<String>,
66}
67
68impl StopCommand {
69    /// Executes the stop command, gracefully terminating matched processes.
70    pub fn execute(&self) -> Result<()> {
71        let printer = Printer::from_flags(self.json, self.verbose);
72
73        // Validate --signal first, so a bad name fails the same way with or
74        // without --dry-run, and before the confirmation prompt
75        #[cfg(unix)]
76        let custom_signal = if let Some(ref sig_name) = self.signal {
77            Some(parse_signal_name(sig_name)?)
78        } else {
79            None
80        };
81        // Windows has no signals: say so rather than quietly sending a normal stop
82        #[cfg(not(unix))]
83        if self.signal.is_some() {
84            return Err(ProcError::NotSupported(
85                "stop --signal on Windows (proc stop asks the process to exit)".to_string(),
86            ));
87        }
88
89        // Split each value on commas and resolve to processes
90        // Use resolve_targets_excluding_self to avoid stopping ourselves
91        let targets = flatten_targets(&self.target);
92        let mode = NameMatch::from_flag(self.cmd);
93        let resolved = resolve_targets_excluding_self(&targets, mode);
94
95        // Warn about targets that weren't found
96        if let Some(warning) = resolved.warning() {
97            printer.warning(&warning);
98        }
99        // the JSON results list the targets that matched nothing
100        let printer = printer.with_not_found(&resolved.not_found);
101        let mut processes = resolved.processes;
102
103        // Apply --in and --by filters
104        apply_filters(&mut processes, &self.in_dir, &self.by_name, mode);
105
106        // Real CPU readings whenever the list is shown or returned (dry run, the
107        // confirmation prompt, or the error for a missing `--yes`); only `--yes`
108        // acts at once, without the wait
109        if self.dry_run || !self.yes {
110            Process::measure_cpu(&mut processes);
111        }
112
113        if processes.is_empty() {
114            return Err(ProcError::ProcessNotFound(self.target.join(" ")));
115        }
116
117        // Dry run: just show what would be stopped
118        if self.dry_run {
119            printer.print_dry_run("stop", &processes);
120            return Ok(());
121        }
122
123        // Confirm if not --yes
124        if !printer.ask_confirm("stop", &processes, self.yes)? {
125            return Ok(());
126        }
127
128        // Ask every process first, then wait for them together, so several
129        // processes share one --timeout instead of taking one each
130        let (signalled, mut failed) = apply_to_each(&processes, |proc| {
131            #[cfg(unix)]
132            if let Some(signal) = custom_signal {
133                return proc.send_signal(signal);
134            }
135            ask_to_end(proc)
136        });
137
138        let outlived = self.wait_for_exit(&signalled);
139
140        // Force kill whatever outlived the timeout
141        let (stopped, failed_to_kill) = apply_to_each(&signalled, |proc| {
142            if outlived.contains(&proc.pid) {
143                proc.kill_and_wait()
144            } else {
145                Ok(())
146            }
147        });
148        failed.extend(failed_to_kill);
149        // the failures read in the order of the list that was approved, not
150        // "signal failures, then force-kill failures"
151        in_process_order(&processes, &mut failed);
152
153        // Output results
154        printer.print_action_result("stop", &stopped, &failed)
155    }
156
157    /// Wait up to --timeout for the processes to exit; returns the PIDs still running.
158    fn wait_for_exit(&self, processes: &[Process]) -> Vec<u32> {
159        let start = std::time::Instant::now();
160        let timeout = std::time::Duration::from_secs(self.timeout);
161        let mut running: Vec<&Process> = processes.iter().collect();
162
163        loop {
164            running.retain(|p| p.is_running());
165            if running.is_empty() || start.elapsed() >= timeout {
166                return running.iter().map(|p| p.pid).collect();
167            }
168            std::thread::sleep(std::time::Duration::from_millis(100));
169        }
170    }
171}
172
173/// Put `failed` in the order `processes` lists its processes in. A process that
174/// could not be asked to end and one that outlived the timeout and could not be
175/// force-killed are found by different passes; this merges them.
176fn in_process_order(processes: &[Process], failed: &mut [(Process, String)]) {
177    failed.sort_by_key(|(failed, _)| {
178        processes
179            .iter()
180            .position(|p| p.pid == failed.pid)
181            .unwrap_or(usize::MAX)
182    });
183}
184
185/// Ask one process to end (SIGTERM; on Windows, `taskkill` without `/F`)
186fn ask_to_end(proc: &Process) -> Result<()> {
187    match proc.terminate() {
188        // Windows can't ask a console program to close (taskkill without /F
189        // needs a window); it still gets stopped, by the force kill after
190        // --timeout
191        Err(_) if cfg!(not(unix)) && proc.is_running() => Ok(()),
192        result => result,
193    }
194}
195
196#[cfg(test)]
197mod tests {
198    use super::*;
199    use crate::test_support::{end, gone_record, idle_child, record_of};
200
201    #[test]
202    fn failures_from_both_passes_read_in_the_order_of_the_approved_list() {
203        let mut child = idle_child();
204        let record = record_of(&child);
205        end(&mut child);
206        let with_pid = |pid| Process {
207            pid,
208            ..record.clone()
209        };
210        // typed order, not PID order: 30 was typed first
211        let approved = [with_pid(30), with_pid(10), with_pid(20), with_pid(40)];
212        // the force-kill pass found 20; the signal pass found 40 and 30
213        let mut failed = vec![
214            (with_pid(40), "signal".to_string()),
215            (with_pid(30), "signal".to_string()),
216            (with_pid(20), "kill".to_string()),
217        ];
218        in_process_order(&approved, &mut failed);
219        let order: Vec<(u32, &str)> = failed.iter().map(|(p, e)| (p.pid, e.as_str())).collect();
220        assert_eq!(order, [(30, "signal"), (20, "kill"), (40, "signal")]);
221    }
222
223    #[test]
224    fn a_process_that_is_gone_cannot_be_asked_to_end() {
225        let mut child = idle_child();
226        let record = gone_record(&mut child);
227        // Not running, so the refusal is not the expected one a console
228        // program gives on Windows: it is reported
229        let result = ask_to_end(&record);
230        assert!(
231            matches!(&result, Err(ProcError::ProcessNotFound(_))),
232            "{result:?}"
233        );
234    }
235
236    #[test]
237    fn a_running_process_is_asked_and_the_answer_does_not_matter_on_windows() {
238        let mut child = idle_child();
239        let record = record_of(&child);
240        let result = ask_to_end(&record);
241        end(&mut child);
242        // Unix: SIGTERM was delivered. Windows: taskkill refuses a console
243        // program, and that is not a failure.
244        assert!(result.is_ok(), "{result:?}");
245    }
246}
proc_cli/commands/stop.rs

proc_cli/commands/
stop.rs
