Skip to main content

nu_protocol/engine/
jobs.rs

1use std::{
2    collections::{BTreeMap, BTreeSet, HashMap, HashSet, hash_map::Entry},
3    sync::{
4        Arc, Mutex,
5        mpsc::{Receiver, RecvTimeoutError, Sender, TryRecvError},
6    },
7};
8
9#[cfg(not(target_family = "wasm"))]
10use nu_utils::time::Instant;
11#[cfg(not(target_family = "wasm"))]
12use std::time::Duration;
13
14use nu_system::{ForegroundChild, UnfreezeHandle, kill_by_pid};
15
16use crate::{PipelineData, Signals, shell_error};
17
18use crate::JobId;
19
20#[derive(Debug)]
21pub struct Jobs {
22    next_job_id: usize,
23
24    // this is the ID of the most recently added frozen job in the jobs table.
25    // the methods of this struct must ensure the invariant of this always
26    // being None or pointing to a valid job in the table
27    last_frozen_job_id: Option<JobId>,
28    jobs: HashMap<JobId, Job>,
29}
30
31impl Default for Jobs {
32    fn default() -> Self {
33        Self {
34            next_job_id: 1,
35            last_frozen_job_id: None,
36            jobs: HashMap::default(),
37        }
38    }
39}
40
41impl Jobs {
42    pub fn iter(&self) -> impl Iterator<Item = (JobId, &Job)> {
43        self.jobs.iter().map(|(k, v)| (*k, v))
44    }
45
46    /// The id the next job added to the table will get. Ids only grow, so a job with a lower id
47    /// was started before this call.
48    pub fn next_id(&self) -> JobId {
49        JobId::new(self.next_job_id)
50    }
51
52    /// Whether there are no tracked jobs (running or frozen).
53    pub fn is_empty(&self) -> bool {
54        self.jobs.is_empty()
55    }
56
57    pub fn lookup(&self, id: JobId) -> Option<&Job> {
58        self.jobs.get(&id)
59    }
60
61    pub fn lookup_mut(&mut self, id: JobId) -> Option<&mut Job> {
62        self.jobs.get_mut(&id)
63    }
64
65    pub fn remove_job(&mut self, id: JobId) -> Option<Job> {
66        if self.last_frozen_job_id.is_some_and(|last| id == last) {
67            self.last_frozen_job_id = None;
68        }
69
70        self.jobs.remove(&id)
71    }
72
73    fn assign_last_frozen_id_if_frozen(&mut self, id: JobId, job: &Job) {
74        if let Job::Frozen(_) = job {
75            self.last_frozen_job_id = Some(id);
76        }
77    }
78
79    pub fn add_job(&mut self, job: Job) -> JobId {
80        let this_id = self.next_id();
81
82        self.assign_last_frozen_id_if_frozen(this_id, &job);
83
84        self.jobs.insert(this_id, job);
85        self.next_job_id += 1;
86
87        this_id
88    }
89
90    pub fn most_recent_frozen_job_id(&mut self) -> Option<JobId> {
91        self.last_frozen_job_id
92    }
93
94    // this is useful when you want to remove a job from the list and add it back later
95    pub fn add_job_with_id(&mut self, id: JobId, job: Job) -> Result<(), &'static str> {
96        self.assign_last_frozen_id_if_frozen(id, &job);
97
98        if let Entry::Vacant(e) = self.jobs.entry(id) {
99            e.insert(job);
100            Ok(())
101        } else {
102            Err("job already exists")
103        }
104    }
105
106    /// This function tries to forcefully kill a job from this job table,
107    /// removes it from the job table. It always succeeds in removing the job
108    /// from the table, but may fail in killing the job's active processes.
109    pub fn kill_and_remove(&mut self, id: JobId) -> shell_error::io::Result<()> {
110        if let Some(job) = self.jobs.get(&id) {
111            let err = job.kill();
112
113            self.remove_job(id);
114
115            err?
116        }
117
118        Ok(())
119    }
120
121    /// This function tries to forcefully kill all the background jobs and
122    /// removes all of them from the job table.
123    ///
124    /// It returns an error if any of the job killing attempts fails, but always
125    /// succeeds in removing the jobs from the table.
126    pub fn kill_all(&mut self) -> shell_error::io::Result<()> {
127        self.last_frozen_job_id = None;
128
129        let first_err = self
130            .iter()
131            .map(|(_, job)| job.kill().err())
132            .fold(None, |acc, x| acc.or(x));
133
134        self.jobs.clear();
135
136        if let Some(err) = first_err {
137            Err(err)
138        } else {
139            Ok(())
140        }
141    }
142}
143
144#[derive(Debug)]
145pub enum Job {
146    Thread(ThreadJob),
147    Frozen(FrozenJob),
148}
149
150// A thread job represents a job that is currently executing as a background thread in nushell.
151// This is an Arc-y type, cloning it does not uniquely clone the information of this particular
152// job.
153
154// Although rust's documentation does not document the acquire-release semantics of Mutex, this
155// is a direct undocumentented requirement of its soundness, and is thus assumed by this
156// implementaation.
157// see issue https://github.com/rust-lang/rust/issues/126239.
158#[derive(Clone, Debug)]
159pub struct ThreadJob {
160    signals: Signals,
161    pids: Arc<Mutex<HashSet<u32>>>,
162    description: Option<String>,
163    auto_kill: bool,
164    pub sender: Sender<Mail>,
165}
166
167impl ThreadJob {
168    pub fn new(
169        signals: Signals,
170        description: Option<String>,
171        auto_kill: bool,
172        sender: Sender<Mail>,
173    ) -> Self {
174        ThreadJob {
175            signals,
176            pids: Arc::new(Mutex::new(HashSet::default())),
177            sender,
178            description,
179            auto_kill,
180        }
181    }
182
183    /// Spawn and register an external process while holding the PID lock.
184    ///
185    /// Shutdown must not finish between spawning the process and registering its PID: the
186    /// shell could exit before the job thread gets a chance to kill the unregistered child.
187    /// Returns `None` without spawning if the job has already been interrupted.
188    pub fn try_spawn(
189        &self,
190        spawn: impl FnOnce() -> std::io::Result<ForegroundChild>,
191    ) -> std::io::Result<Option<ForegroundChild>> {
192        let mut pids = self.pids.lock().expect("PIDs lock was poisoned");
193        if self.signals.interrupted() {
194            return Ok(None);
195        }
196
197        let child = spawn()?;
198        pids.insert(child.pid());
199        Ok(Some(child))
200    }
201
202    /// Tries to add the provided pid to the active pid set of the current job.
203    ///
204    /// Returns true if the pid was added successfully, or false if the
205    /// current job is interrupted.
206    pub fn try_add_pid(&self, pid: u32) -> bool {
207        let mut pids = self.pids.lock().expect("PIDs lock was poisoned");
208
209        // note: this signals check must occur after the pids lock has been locked.
210        if self.signals.interrupted() {
211            false
212        } else {
213            pids.insert(pid);
214            true
215        }
216    }
217
218    pub fn collect_pids(&self) -> Vec<u32> {
219        let lock = self.pids.lock().expect("PID lock was poisoned");
220
221        lock.iter().copied().collect()
222    }
223
224    pub fn kill(&self) -> shell_error::io::Result<()> {
225        // it's okay to make this interrupt outside of the mutex, since it has acquire-release
226        // semantics.
227
228        self.signals.trigger();
229
230        let mut pids = self.pids.lock().expect("PIDs lock was poisoned");
231
232        for pid in pids.iter() {
233            kill_by_pid((*pid).into())?;
234        }
235
236        pids.clear();
237
238        Ok(())
239    }
240
241    pub fn remove_pid(&self, pid: u32) {
242        let mut pids = self.pids.lock().expect("PID lock was poisoned");
243
244        pids.remove(&pid);
245    }
246}
247
248impl Job {
249    pub fn kill(&self) -> shell_error::io::Result<()> {
250        match self {
251            Job::Thread(thread_job) => thread_job.kill(),
252            Job::Frozen(frozen_job) => frozen_job.kill(),
253        }
254    }
255
256    pub fn description(&self) -> Option<&String> {
257        match self {
258            Job::Thread(thread_job) => thread_job.description.as_ref(),
259            Job::Frozen(frozen_job) => frozen_job.description.as_ref(),
260        }
261    }
262
263    pub fn is_auto_kill(&self) -> bool {
264        match self {
265            Job::Thread(job) => job.auto_kill,
266            Job::Frozen(_) => false,
267        }
268    }
269
270    pub fn assign_description(&mut self, description: Option<String>) {
271        match self {
272            Job::Thread(thread_job) => thread_job.description = description,
273            Job::Frozen(frozen_job) => frozen_job.description = description,
274        }
275    }
276}
277
278#[derive(Debug)]
279pub struct FrozenJob {
280    pub unfreeze: UnfreezeHandle,
281    pub description: Option<String>,
282}
283
284impl FrozenJob {
285    pub fn kill(&self) -> shell_error::io::Result<()> {
286        #[cfg(unix)]
287        {
288            Ok(kill_by_pid(self.unfreeze.pid() as i64)?)
289        }
290
291        // it doesn't happen outside unix.
292        #[cfg(not(unix))]
293        {
294            Ok(())
295        }
296    }
297}
298
299/// Stores the information about the background job currently being executed by this thread, if any
300#[derive(Clone, Debug)]
301pub struct CurrentJob {
302    pub id: JobId,
303
304    /// The job the main thread spawned that this one descends from: `id` itself when the main
305    /// thread spawned this job, the spawning job's `root` otherwise, and `JobId::ZERO` on the
306    /// main thread.
307    pub root: JobId,
308
309    // The background thread job associated with this thread.
310    // If None, it indicates this thread is currently the main job
311    pub background_thread_job: Option<ThreadJob>,
312
313    // note: although the mailbox is Mutex'd, it is only ever accessed
314    // by the current job's threads
315    pub mailbox: Arc<Mutex<Mailbox>>,
316}
317
318// The storage for unread messages
319//
320// Messages are initially sent over a mpsc channel,
321// and may then be stored in a IgnoredMail struct when
322// filtered out by a message tag.
323#[derive(Debug)]
324pub struct Mailbox {
325    receiver: Receiver<Mail>,
326    ignored_mail: IgnoredMail,
327}
328
329impl Mailbox {
330    pub fn new(receiver: Receiver<Mail>) -> Self {
331        Mailbox {
332            receiver,
333            ignored_mail: IgnoredMail::default(),
334        }
335    }
336
337    #[cfg(not(target_family = "wasm"))]
338    pub fn recv_timeout(
339        &mut self,
340        filter_tag: Option<FilterTag>,
341        timeout: Duration,
342    ) -> Result<PipelineData, RecvTimeoutError> {
343        if let Some(value) = self.ignored_mail.pop(filter_tag) {
344            Ok(value)
345        } else {
346            let mut waited_so_far = Duration::ZERO;
347            let mut before = Instant::now();
348
349            while waited_so_far < timeout {
350                let (tag, value) = self
351                    .receiver
352                    .recv_timeout(timeout.checked_sub(waited_so_far).unwrap_or(Duration::ZERO))?;
353
354                if filter_tag.is_none() || filter_tag == tag {
355                    return Ok(value);
356                } else {
357                    self.ignored_mail.add((tag, value));
358                    let now = Instant::now();
359                    waited_so_far += now - before;
360                    before = now;
361                }
362            }
363
364            Err(RecvTimeoutError::Timeout)
365        }
366    }
367
368    #[cfg(not(target_family = "wasm"))]
369    pub fn try_recv(
370        &mut self,
371        filter_tag: Option<FilterTag>,
372    ) -> Result<PipelineData, TryRecvError> {
373        if let Some(value) = self.ignored_mail.pop(filter_tag) {
374            Ok(value)
375        } else {
376            loop {
377                let (tag, value) = self.receiver.try_recv()?;
378
379                if filter_tag.is_none() || filter_tag == tag {
380                    return Ok(value);
381                } else {
382                    self.ignored_mail.add((tag, value));
383                }
384            }
385        }
386    }
387
388    pub fn clear(&mut self) {
389        self.ignored_mail.clear();
390
391        while self.receiver.try_recv().is_ok() {}
392    }
393}
394
395// A data structure used to store messages which were received, but currently ignored by a tag filter
396// messages are added and popped in a first-in-first-out matter.
397#[derive(Default, Debug)]
398struct IgnoredMail {
399    next_id: usize,
400    messages: BTreeMap<usize, Mail>,
401    by_tag: HashMap<FilterTag, BTreeSet<usize>>,
402}
403
404pub type FilterTag = u64;
405pub type Mail = (Option<FilterTag>, PipelineData);
406
407impl IgnoredMail {
408    pub fn add(&mut self, (tag, value): Mail) {
409        let id = self.next_id;
410        self.next_id += 1;
411
412        self.messages.insert(id, (tag, value));
413
414        if let Some(tag) = tag {
415            self.by_tag.entry(tag).or_default().insert(id);
416        }
417    }
418
419    pub fn pop(&mut self, tag: Option<FilterTag>) -> Option<PipelineData> {
420        if let Some(tag) = tag {
421            self.pop_oldest_with_tag(tag)
422        } else {
423            self.pop_oldest()
424        }
425    }
426
427    pub fn clear(&mut self) {
428        self.messages.clear();
429        self.by_tag.clear();
430    }
431
432    fn pop_oldest(&mut self) -> Option<PipelineData> {
433        let (id, (tag, value)) = self.messages.pop_first()?;
434
435        if let Some(tag) = tag
436            && let Entry::Occupied(mut occupied_entry) = self.by_tag.entry(tag)
437        {
438            occupied_entry.get_mut().remove(&id);
439            if occupied_entry.get().is_empty() {
440                occupied_entry.remove();
441            }
442        }
443
444        Some(value)
445    }
446
447    fn pop_oldest_with_tag(&mut self, tag: FilterTag) -> Option<PipelineData> {
448        let ids = self.by_tag.get_mut(&tag)?;
449
450        let id = ids.pop_first()?;
451
452        if ids.is_empty() {
453            self.by_tag.remove(&tag);
454        }
455
456        Some(self.messages.remove(&id)?.1)
457    }
458}
459
460#[cfg(test)]
461mod tests {
462    use super::*;
463    use std::sync::{atomic::AtomicBool, mpsc};
464
465    #[test]
466    fn interrupted_job_does_not_spawn() {
467        let (sender, _) = mpsc::channel();
468        let signals = Signals::new(Arc::new(AtomicBool::new(false)));
469        let job = ThreadJob::new(signals.clone(), None, false, sender);
470        signals.trigger();
471
472        let child = job.try_spawn(|| panic!("interrupted job must not spawn"));
473        assert!(child.unwrap().is_none());
474    }
475
476    #[test]
477    fn spawned_process_is_registered_before_returning() {
478        let (sender, _) = mpsc::channel();
479        let signals = Signals::new(Arc::new(AtomicBool::new(false)));
480        let job = ThreadJob::new(signals, None, false, sender);
481        // Listing this test binary's tests needs no platform-specific executable, and the
482        // child terminates by itself if an assertion fails.
483        let mut command = std::process::Command::new(std::env::current_exe().unwrap());
484        command
485            .arg("--list")
486            .stdout(std::process::Stdio::null())
487            .stderr(std::process::Stdio::null());
488        let mut child = job
489            .try_spawn(|| {
490                #[cfg(unix)]
491                {
492                    ForegroundChild::spawn(
493                        command,
494                        false,
495                        true,
496                        &Arc::new((
497                            std::sync::atomic::AtomicU32::new(0),
498                            std::sync::atomic::AtomicU32::new(0),
499                        )),
500                    )
501                }
502                #[cfg(not(unix))]
503                {
504                    ForegroundChild::spawn(command)
505                }
506            })
507            .unwrap()
508            .unwrap();
509
510        assert!(job.collect_pids().contains(&child.pid()));
511        child.wait().unwrap();
512        job.remove_pid(child.pid());
513        assert!(job.collect_pids().is_empty());
514    }
515
516    #[test]
517    fn spawn_holds_pid_lock_until_registration() {
518        let (sender, _) = mpsc::channel();
519        let signals = Signals::new(Arc::new(AtomicBool::new(false)));
520        let job = ThreadJob::new(signals, None, false, sender);
521        let (started_tx, started_rx) = mpsc::channel();
522        let (release_tx, release_rx) = mpsc::channel();
523
524        std::thread::scope(|scope| {
525            let job = &job;
526            let spawning = scope.spawn(move || {
527                job.try_spawn(|| {
528                    started_tx.send(()).unwrap();
529                    release_rx.recv_timeout(Duration::from_secs(30)).unwrap();
530                    Err(std::io::Error::other("test spawn failure"))
531                })
532            });
533
534            started_rx.recv_timeout(Duration::from_secs(30)).unwrap();
535            // kill() takes this same lock after triggering the signals, so it cannot finish
536            // while an external is being spawned but has not yet registered its PID.
537            let locked = job.pids.try_lock().is_err();
538            release_tx.send(()).unwrap();
539            assert!(spawning.join().unwrap().is_err());
540            assert!(locked, "shutdown can race with process creation");
541        });
542
543        job.kill().unwrap();
544        assert!(job.collect_pids().is_empty());
545    }
546}