zsh/

exec_jobs.rs

//! Executor-side bg-job tracker. NOT a port of `Src/jobs.c`.
//!
//! `Src/jobs.c` uses a flat `struct job jobtab[]` global keyed by pid
//! (ported to `crate::ported::jobs::JOBTAB`). C tracks child processes
//! through their pid + waitpid(2). Rust prefers safe-Rust ownership
//! of `std::process::Child` handles so the executor needs a parallel
//! registry that owns those handles. That's what this file is.
//!
//! This module is segregated from `src/ported/jobs.rs` (the faithful
//! C port) so the port file contains only direct ports of jobs.c
//! decls. `JobState` / `JobInfo` / `JobTable` here are zshrs runtime
//! state with no C counterpart by design.

use std::process::Child;
use std::sync::Mutex;

use crate::ported::jobs::stat;
use crate::ported::jobs::{deletejob, CURJOB, MAXJOB, PREVJOB, THISJOB};
use crate::ported::zsh_h::job;

/// !!! WARNING: RUST-ONLY ADAPTER !!! The job status C derives from a
/// finished process's wait status — update_job's `val`
/// (c:Src/jobs.c:492-496): `WIFSIGNALED ? 0200 | WTERMSIG : WIFSTOPPED ?
/// 0200 | WSTOPSIG : WEXITSTATUS`. zshrs waits on its foreground externals
/// through `std::process::ExitStatus`, whose `code()` is `None` for a
/// signalled child; the call sites turned that into 1, so
/// `sh -c 'kill $$'; print $?` printed 1 where zsh prints 143.
pub fn wait_status_val(s: std::process::ExitStatus) -> i32 {
    use std::os::unix::process::ExitStatusExt as _;
    if let Some(sig) = s.signal() {
        0o200 | sig // c:493
    } else if let Some(sig) = s.stopped_signal() {
        0o200 | sig // c:495
    } else {
        s.code().unwrap_or(0) // c:496
    }
}

thread_local! {
    /// Non-zero while a pipeline's in-shell last stage runs. update_job's
    /// foreground tail reads the status of the job's process-group leader
    /// (c:Src/jobs.c:497-498), which is the FIRST stage, so the externals
    /// the last stage waits for do not drive it.
    ///
    /// !!! WARNING: RUST-ONLY COUNTER — C READS `jn->gleader` !!!
    pub static NOT_JOB_LEADER: std::cell::Cell<u32> = const { std::cell::Cell::new(0) };
}

/// !!! WARNING: RUST-ONLY HELPER — C WRITES THROUGH THE `shout` FILE* !!!
/// printjob's asynchronous report goes to `fout = (synch == 2 || !shout) ?
/// stdout : shout` (c:Src/jobs.c:1153), and an interactive shell's `shout`
/// is the terminal, `fdopen(SHTTY, "w")`, or stderr when there is no tty
/// (c:Src/init.c:734-748). Writing to fd 2 instead sent the report through
/// the command's own redirection: `sh -c 'kill -HUP $$' 2>/dev/null` lost
/// its `zsh: hangup` line.
fn shout_write(s: &str) {
    let tty = crate::ported::init::SHTTY.load(std::sync::atomic::Ordering::Relaxed);
    let fd = if tty >= 0 { tty } else { libc::STDERR_FILENO };
    let _ = crate::ported::utils::write_loop(fd, s.as_bytes());
}

/// !!! WARNING: RUST-ONLY ADAPTER !!! update_job's report for the foreground
/// job (c:Src/jobs.c:645-650), for a simple external zshrs waited for outside
/// the job table: `if ((isset(NOTIFY) || job == thisjob) && (jn->stat &
/// STAT_LOCKED)) printjob(jn, !!isset(LONGLISTJOBS), 0);`. The job is one
/// process whose text is the command's job text (`None` when the dispatch
/// carried none, e.g. inside a function, c:Src/exec.c:3536-3538).
///
/// printjob prints nothing for a job marked STAT_NOPRINT, and execpline marks
/// every job run while another pipeline is executing (`pline_level`,
/// c:Src/exec.c:1829-1831): a command inside a function, `eval`, a loop, a
/// `{ … }` or an `if` is never reported, only one at the top of the command
/// line — including either side of `&&`/`||`. `nested` is the caller's
/// in-process `( … )` (C forks it, and the child has no MONITOR).
///
/// Then printjob's own gate (exec_jobs::printjob_async): an interactive
/// shell with MONITOR reports a signal other than SIGINT/SIGPIPE as
/// `zsh: terminated  cmd`, and a SIGINT only with a newline (c:1203-1205,
/// c:1260-1263, c:1338-1341).
pub fn foreground_job_report(status: i32, text: Option<String>, nested: bool) {
    use crate::ported::zsh_h::{CS_CMDAND, CS_CMDOR, SFC_NONE};
    use std::sync::atomic::Ordering;
    let Some(text) = text else { return };
    if nested
        || !libc::WIFSIGNALED(status)
        || NOT_JOB_LEADER.with(|d| d.get()) > 0
        || crate::ported::exec::sfcontext.load(Ordering::Relaxed) != SFC_NONE
        || crate::vm_helper::EVAL_RECURSION_DEPTH.with(|d| d.get()) > 0
    {
        return;
    }
    // c:Src/exec.c:1829-1831 — nested in a compound command (cmdstack holds
    // more than the `&&`/`||` list connectors).
    let in_compound = crate::ported::prompt::CMDSTACK.with(|s| {
        s.borrow()
            .iter()
            .any(|&cs| cs as i32 != CS_CMDAND as i32 && cs as i32 != CS_CMDOR as i32)
    });
    if in_compound {
        return;
    }
    let jn = job {
        stat: stat::INUSE | stat::LOCKED | stat::DONE | stat::CHANGED,
        procs: vec![crate::ported::zsh_h::process {
            pid: 0,
            text,
            status,
            ti: Default::default(),
            bgtime: None,
            endtime: None,
        }],
        ..Default::default()
    };
    // The job sits at index 1 and is `thisjob` (c:Src/jobs.c:645).
    let tab = vec![job::default(), jn];
    printjob_async(&tab, 1, 1);
}

/// !!! WARNING: RUST-ONLY ADAPTER !!! The tail of C `update_job` for the
/// FOREGROUND job (`job == thisjob`, not STAT_CURSH, so `inforeground = 2`,
/// c:Src/jobs.c:558-561), for an external zshrs waited for outside the job
/// table. `status` is the raw wait status of the job's last process.
///
/// c:Src/jobs.c:654-679 —
/// ```c
/// /* When MONITOR is set, the foreground process runs in a different *
///  * process group from the shell, so the shell will not receive     *
///  * terminal signals, therefore we pretend that the shell got       *
///  * the signal too.                                                 */
/// if (inforeground == 2 && isset(MONITOR) && WIFSIGNALED(status)) {
///     int sig = WTERMSIG(status);
///     if (sig == SIGINT || sig == SIGQUIT) {
///         if (sigtrapped[sig]) {
///             dotrap(sig);
///             if (errflag) breaks = loops;
///         } else {
///             breaks = loops;
///             errflag |= ERRFLAG_INT;
///         }
///         check_cursh_sig(sig);
///     }
/// }
/// ```
/// So a child that dies of SIGINT/SIGQUIT ends the rest of the command line
/// (`for i in 1 2; do sh -c 'kill -INT $$'; print $i; done` prints nothing)
/// unless a trap for the signal returns zero.
pub fn foreground_job_signalled(status: i32) {
    use crate::ported::zsh_h::{isset, ERRFLAG_INT, MONITOR};
    use std::sync::atomic::Ordering;
    if NOT_JOB_LEADER.with(|d| d.get()) > 0 || !isset(MONITOR) || !libc::WIFSIGNALED(status) {
        return;
    }
    let sig = libc::WTERMSIG(status); // c:659
    if sig != libc::SIGINT && sig != libc::SIGQUIT {
        return; // c:661
    }
    let loops = crate::ported::builtin::LOOPS.load(Ordering::Relaxed);
    let trapped = crate::ported::signals::sigtrapped
        .lock()
        .ok()
        .and_then(|t| t.get(sig as usize).copied())
        .unwrap_or(0);
    if trapped != 0 {
        crate::ported::signals::dotrap(sig); // c:663
        if crate::ported::utils::errflag.load(Ordering::Relaxed) != 0 {
            crate::ported::builtin::BREAKS.store(loops, Ordering::Relaxed); // c:671-672
        }
    } else {
        crate::ported::builtin::BREAKS.store(loops, Ordering::Relaxed); // c:674
        crate::ported::utils::errflag.fetch_or(ERRFLAG_INT, Ordering::Relaxed); // c:675
    }
    // c:677 — `check_cursh_sig(sig);`
    if let Some(tab) = crate::ported::jobs::JOBTAB.get() {
        if let Ok(jt) = tab.lock() {
            crate::ported::jobs::check_cursh_sig(&jt, sig);
        }
    }
}

/// Executor-side stand-in for C `printjob`'s done-job delete tail,
/// `Src/jobs.c:1350-1363`:
/// ```c
/// if (jn->stat & STAT_DONE) {
///     ...
///     deletejob(jn, 0);
///     if (job == curjob) { curjob = prevjob; prevjob = job; }
///     if (job == prevjob) setprevjob();
/// }
/// ```
/// The ported `printjob` (src/ported/jobs.rs) is a pure formatter
/// returning a String; C's version mutates the table as a side
/// effect. Every site that calls (or would call) printjob on a
/// possibly-done job runs this tail so finished jobs leave the table
/// exactly when they do in C. Lives here (not src/ported/) because
/// it has no C name of its own — it is the side-effect half of
/// printjob, split out by the Rust purity refactor.
pub fn printjob_delete_tail(tab: &mut [job], idx: usize) {
    if idx >= tab.len() || (tab[idx].stat & stat::DONE) == 0 {
        return;
    }
    deletejob(&mut tab[idx], false); // c:Src/jobs.c:1356
    let mut cj = CURJOB.get_or_init(|| Mutex::new(-1)).lock().unwrap();
    let mut pj = PREVJOB.get_or_init(|| Mutex::new(-1)).lock().unwrap();
    if *cj == idx as i32 {
        // c:Src/jobs.c:1357-1360
        *cj = *pj;
        *pj = idx as i32;
    }
    let need_setprev = *pj == idx as i32; // c:Src/jobs.c:1361
    drop(cj);
    drop(pj);
    if need_setprev {
        setprevjob_locked(tab); // c:Src/jobs.c:1362
    }
}

/// `printjob(jn, !!isset(LONGLISTJOBS), 0)` — the asynchronous (synch 0)
/// report update_job issues at `Src/jobs.c:647` when a job changes state.
/// Returns 1-as-true when something was printed (C's `doneprint`).
///
/// Lives here (not src/ported/) because it has no C name of its own. The Rust `printjob` is a pure formatter with no
/// print gate; this is the gate + output half of C's printjob for synch 0.
/// The done-job delete tail (c:1350-1363) stays with the caller
/// (`printjob_delete_tail`), which runs it whether or not this printed —
/// exactly as C falls through to it.
///
/// This path was missing entirely: update_bg_job deleted a finished job
/// without reporting it, so `: &` + `wait` never said `[1]  + done  :`,
/// `kill %1` never said `[1]  + terminated  ...`, and a foreground job
/// killed by a signal never said `zsh: terminated  ...`.
///
/// NOT PORTED: the STAT_SUPERJOB -> subjob redirect (c:1171-1185) and the
/// `(pwd now: …)` line (c:1349-1353).
///
/// WARNING: param names don't match C — Rust=(tab, ji, thisjob) vs
/// C=(jn, lng, synch)
pub fn printjob_async(tab: &[job], ji: usize, thisjob: i32) -> bool {
    use crate::ported::builtins::sched::zleactive;
    use crate::ported::zsh_h::{isset, INTERACTIVE, LONGLISTJOBS, PRINTEXITVALUE, SHINSTDIN, SP_RUNNING};
    use std::sync::atomic::Ordering;
    let jn = &tab[ji];
    // c:1163-1164 — `if (jn->stat & STAT_NOPRINT) skip_print = 1;`
    let mut skip_print = (jn.stat & stat::NOPRINT) != 0;
    let mut sflag = false; // c:1150
    let mut doputnl = false; // c:1151
    let is_thisjob = ji as i32 == thisjob;
    // c:1190-1221 — does any finished process force a report?
    for pn in jn.procs.iter() {
        if pn.status == SP_RUNNING {
            continue; // c:1193
        }
        if libc::WIFSIGNALED(pn.status) {
            let sig = libc::WTERMSIG(pn.status); // c:1195
            if sig != libc::SIGINT && sig != libc::SIGPIPE {
                sflag = true; // c:1202-1203
            }
            if is_thisjob && sig == libc::SIGINT {
                doputnl = true; // c:1204-1205
            }
            if isset(PRINTEXITVALUE) && isset(SHINSTDIN) {
                sflag = true; // c:1206-1208
                skip_print = false;
            }
        } else if libc::WIFSTOPPED(pn.status) {
            let sig = libc::WSTOPSIG(pn.status); // c:1210
            if is_thisjob && sig == libc::SIGTSTP {
                doputnl = true; // c:1214-1215
            }
        } else if isset(PRINTEXITVALUE) && isset(SHINSTDIN) && libc::WEXITSTATUS(pn.status) != 0
        {
            sflag = true; // c:1216-1219
            skip_print = false;
        }
    }
    // c:1224-1238 — a skipped job is only deleted (caller's tail).
    if skip_print {
        return false;
    }
    let interact = isset(INTERACTIVE);
    let stopped = (jn.stat & stat::STOPPED) != 0;
    // c:1248-1250 — `(interact || synch) && jobbing &&
    //                ((jn->stat & STAT_STOPPED) || sflag || job != thisjob)`
    if interact && crate::ported::zsh_h::jobbing() && (stopped || sflag || !is_thisjob) {
        // c:1258-1259 — `if (!synch) zleentry(ZLE_CMD_TRASH);` (trashzle
        // itself is a no-op unless zleactive).
        if zleactive.load(Ordering::Relaxed) != 0 {
            crate::ported::init::zleentry(crate::ported::zsh_h::ZLE_CMD_TRASH);
        }
        let curjob = *CURJOB.get_or_init(|| Mutex::new(-1)).lock().unwrap();
        let prevjob = *PREVJOB.get_or_init(|| Mutex::new(-1)).lock().unwrap();
        let s = crate::ported::jobs::printjob(
            jn,
            ji,
            isset(LONGLISTJOBS) as i32,
            (curjob >= 0).then_some(curjob as usize),
            (prevjob >= 0).then_some(prevjob as usize),
            is_thisjob, // c:1255 — `thisfmt = job == thisjob && synch != 2`
        );
        // c:1260-1263 — `if (doputnl && !synch) putc('\n', fout);`
        let nl = if doputnl { "\n" } else { "" };
        shout_write(&format!("{}{}\n", nl, s));
        return true;
    } else if doputnl && interact {
        // c:1338-1341
        shout_write("\n");
        return true;
    }
    false
}


/// `setprevjob` (Src/jobs.c:698-717) body operating on an
/// already-locked table slice — `printjob_delete_tail` callers hold
/// the JOBTAB lock, so the re-locking ported `setprevjob()` would
/// deadlock. Same walk, same candidate order.
fn setprevjob_locked(tab: &[job]) {
    let maxjob = *MAXJOB
        .get_or_init(|| Mutex::new(0))
        .lock()
        .expect("maxjob poisoned");
    let curjob = *CURJOB.get_or_init(|| Mutex::new(-1)).lock().unwrap();
    let thisjob = *THISJOB.get_or_init(|| Mutex::new(-1)).lock().unwrap();
    let pick = |want_stopped: bool| -> i32 {
        for i in (1..=maxjob).rev() {
            if i >= tab.len() {
                continue;
            }
            let j = &tab[i];
            let stat_ok = if want_stopped {
                (j.stat & (stat::INUSE | stat::STOPPED)) == (stat::INUSE | stat::STOPPED)
            } else {
                (j.stat & stat::INUSE) != 0
            };
            if stat_ok && (j.stat & stat::SUBJOB) == 0 && i as i32 != curjob && i as i32 != thisjob
            {
                return i as i32;
            }
        }
        -1
    };
    let mut found = pick(true); // c:Src/jobs.c:702-707
    if found < 0 {
        found = pick(false); // c:Src/jobs.c:709-714
    }
    *PREVJOB.get_or_init(|| Mutex::new(-1)).lock().unwrap() = found; // c:716
}

/// One job slot held by a running synchronous pipeline.
///
/// !!! WARNING: RUST-ONLY ADAPTER !!! C keeps this on the C stack:
/// execpline's locals `pj` and `newjob` (c:Src/exec.c:1637,1656,1666) live
/// exactly as long as the pipeline runs. A compiled chunk has no such frame
/// around the pipeline, and can jump past its end (`break`, `return`, an
/// errflag abort), so the slot is recorded here with the VM that opened it
/// (`frame`) and the pipeline's nesting depth inside that chunk (`depth`).
struct HeldSlot {
    frame: usize,
    depth: u32,
    slot: usize,
    pj: i32,
}

thread_local! {
    /// The job slots of the synchronous pipelines running on this thread,
    /// outermost first. See [`HeldSlot`].
    static HELD_SLOTS: std::cell::RefCell<Vec<HeldSlot>> =
        const { std::cell::RefCell::new(Vec::new()) };
}

/// !!! WARNING: RUST-ONLY ADAPTER !!! The opening half of execpline's job
/// frame, run by BUILTIN_EXECPLINE_CHILD_BLOCK:
/// ```c
/// pj = thisjob;                                  /* c:Src/exec.c:1656 */
/// if ((thisjob = newjob = initjob()) == -1) {   /* c:Src/exec.c:1666 */
/// ```
/// Every synchronous pipeline that is not `execsimple` holds a slot while
/// it runs, including a function call and a builtin. That is visible:
/// a job started inside a function gets the slot after the function's
/// own (`f() { sleep 1 & }; f` prints `[2]`), and setprevjob
/// (c:Src/jobs.c:672-677) can pick the running function's slot as
/// `prevjob`, which deletejob later frees without touching `prevjob`.
///
/// Slots this frame left at `depth` or deeper — skipped by a `break` or a
/// `continue` before their close ran — are released first.
///
/// Worker threads take no slot: the job table is the main shell's, and C
/// has no second thread to allocate from it.
pub fn execpline_slot_open(frame: usize, depth: u32) {
    if crate::worker::in_worker_thread() {
        return;
    }
    execpline_slot_close(frame, depth);
    let table = crate::ported::jobs::JOBTAB.get_or_init(|| Mutex::new(Vec::new()));
    let slot = {
        let mut tab = table.lock().unwrap_or_else(|e| e.into_inner());
        crate::ported::jobs::initjob(&mut tab) // c:Src/exec.c:1666
    };
    let mut tj = THISJOB.get_or_init(|| Mutex::new(-1)).lock().unwrap_or_else(|e| e.into_inner());
    let pj = *tj; // c:Src/exec.c:1656
    *tj = slot as i32; // c:Src/exec.c:1666
    drop(tj);
    HELD_SLOTS.with(|h| h.borrow_mut().push(HeldSlot { frame, depth, slot, pj }));
}

/// !!! WARNING: RUST-ONLY ADAPTER !!! The closing half of execpline's job
/// frame, run by BUILTIN_EXECPLINE_CHILD_UNBLOCK: the procs-less job is
/// deleted (waitonejob, c:Src/jobs.c:1750-1756) and `thisjob = pj` restores
/// the enclosing pipeline's (c:Src/exec.c:1981).
///
/// Closes the slot `frame` holds at `depth` together with every slot opened
/// after it: those belong to pipelines nested inside this one, which have
/// necessarily finished, whether or not their own close ran.
pub fn execpline_slot_close(frame: usize, depth: u32) {
    let start = HELD_SLOTS.with(|h| {
        h.borrow()
            .iter()
            .position(|s| s.frame == frame && s.depth >= depth)
    });
    if let Some(start) = start {
        release_held_slots(start);
    }
}

/// !!! WARNING: RUST-ONLY ADAPTER !!! How many pipeline slots are held now.
/// A chunk runner takes this before running a chunk and hands it to
/// [`execpline_slots_release_to`] afterwards, so a chunk abandoned mid-
/// pipeline (errflag, `return` from a sourced file) holds nothing after it.
pub fn execpline_slots_mark() -> usize {
    HELD_SLOTS.with(|h| h.borrow().len())
}

/// !!! WARNING: RUST-ONLY ADAPTER !!! Close every pipeline slot opened since
/// `mark`, as their closes would have.
pub fn execpline_slots_release_to(mark: usize) {
    release_held_slots(mark);
}

/// !!! WARNING: RUST-ONLY ADAPTER !!! Drop the record of every slot opened
/// since `mark` WITHOUT touching the job table. For the in-process stand-ins
/// for a fork (`$(...)`, `( ... )`): the slots were taken from the child's
/// cleared table, which the parent's restored table has since replaced, so
/// the indices name nothing of the child's any more.
pub fn execpline_slots_forget_to(mark: usize) {
    HELD_SLOTS.with(|h| h.borrow_mut().truncate(mark));
}

/// Port of execcmd_exec's current-shell arm (c:Src/exec.c:3674-3682), for
/// the VM's direct builtin and shell-function dispatch, which does not pass
/// through `execcmd_exec`:
/// ```c
/// } else if (is_cursh) {
///     jobtab[thisjob].stat |= STAT_CURSH;
///     if (!jobtab[thisjob].procs)
///         jobtab[thisjob].stat |= STAT_NOPRINT;
///     if (is_builtin)
///         jobtab[thisjob].stat |= STAT_BUILTIN;
/// ```
/// Without STAT_NOPRINT the running function's own slot is a live job to
/// getjob/bin_fg: `f() { wait %1 }; f` waited on it and returned 0 where
/// zsh reports `%1: no such job` and returns 127 (c:Src/jobs.c:2585-2590).
pub fn mark_thisjob_cursh(is_builtin: bool) {
    let tj = *THISJOB.get_or_init(|| Mutex::new(-1)).lock().unwrap_or_else(|e| e.into_inner());
    if tj < 0 {
        return;
    }
    let table = crate::ported::jobs::JOBTAB.get_or_init(|| Mutex::new(Vec::new()));
    let mut tab = table.lock().unwrap_or_else(|e| e.into_inner());
    if let Some(j) = tab.get_mut(tj as usize) {
        j.stat |= stat::CURSH; // c:3678
        if j.procs.is_empty() {
            j.stat |= stat::NOPRINT; // c:3679-3680
        }
        if is_builtin {
            j.stat |= stat::BUILTIN; // c:3681-3682
        }
    }
}

/// The job slot of the innermost running pipeline, if one is held.
pub fn execpline_slot_current() -> Option<usize> {
    HELD_SLOTS.with(|h| h.borrow().last().map(|s| s.slot))
}

/// Delete the job slots held from position `start` on, innermost first, and
/// put `thisjob` back to what it was before the outermost of them opened.
fn release_held_slots(start: usize) {
    let released: Vec<HeldSlot> = HELD_SLOTS.with(|h| {
        let mut h = h.borrow_mut();
        if start >= h.len() {
            return Vec::new();
        }
        h.split_off(start)
    });
    let Some(outermost) = released.first() else {
        return;
    };
    let table = crate::ported::jobs::JOBTAB.get_or_init(|| Mutex::new(Vec::new()));
    {
        let mut tab = table.lock().unwrap_or_else(|e| e.into_inner());
        for held in released.iter().rev() {
            // A stopped job stays in the table for `fg` (zwaitjob returns on
            // STAT_STOPPED and nothing deletes it), and a superjob belongs to
            // the list_pipe machinery, not to this frame.
            if let Some(jn) = tab.get_mut(held.slot) {
                if (jn.stat & stat::INUSE) != 0
                    && (jn.stat & (stat::STOPPED | stat::SUPERJOB)) == 0
                {
                    deletejob(jn, false); // c:Src/jobs.c:1754
                }
            }
        }
        // c:Src/jobs.c:1441-1443 — freejob's `maxjob` shrink, which the
        // ported freejob (one job, no table) cannot do.
        let mut mj = MAXJOB.get_or_init(|| Mutex::new(0)).lock().unwrap_or_else(|e| e.into_inner());
        while *mj > 0 && tab.get(*mj).map_or(true, |j| (j.stat & stat::INUSE) == 0) {
            *mj -= 1;
        }
    }
    *THISJOB.get_or_init(|| Mutex::new(-1)).lock().unwrap_or_else(|e| e.into_inner()) =
        outermost.pj; // c:Src/exec.c:1981 `thisjob = pj;`
}

/// Running-job state tracked alongside each `Child` handle.
/// Maps to C's `STAT_*` bits but is exposed as a typed enum since
/// the executor's safe-Rust path doesn't manipulate the bitfield.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum JobState {
    /// `Running` variant.
    Running,
    /// `Stopped` variant.
    Stopped,
    /// `Done` variant.
    Done,
}

/// One entry in the executor's bg-job registry.
#[derive(Debug)]
pub struct JobInfo {
    /// `id` field.
    pub id: usize,
    /// `pid` field.
    pub pid: i32,
    /// `child` field.
    pub child: Option<Child>,
    /// `command` field.
    pub command: String,
    /// `state` field.
    pub state: JobState,
    /// `is_current` field.
    pub is_current: bool,
}

/// The executor's bg-job registry. Distinct from the C-port
/// `JOBTAB` (a `Vec<Job>` keyed by index that mirrors `jobtab[]`):
/// this table owns the `std::process::Child` handles needed for
/// `try_wait` / `kill` on the safe-Rust path.
pub struct JobTable {
    /// `jobs` field.
    jobs: Vec<Option<JobInfo>>,
    /// `current_id` field.
    current_id: Option<usize>,
    /// `next_id` field.
    next_id: usize,
}

impl Default for JobTable {
    fn default() -> Self {
        Self::new()
    }
}

impl JobTable {
    /// `new` — see implementation.
    pub fn new() -> Self {
        JobTable {
            jobs: Vec::with_capacity(16),
            current_id: None,
            next_id: 1,
        }
    }

    /// Peek at the next id that would be assigned by `add_job`/`add_pid`.
    /// Used by `wait %N` to distinguish a never-issued id (clear user
    /// error) from a job that was issued and already reaped (silent
    /// success in zshrs to keep the `cmd & wait %1` idiom working
    /// across the races introduced by the threaded job table).
    pub fn peek_next_id(&self) -> usize {
        self.next_id
    }

    /// Add a job with a Child process
    pub fn add_job(&mut self, child: Child, command: String, state: JobState) -> usize {
        let id = self.next_id;
        self.next_id += 1;

        let pid = child.id() as i32;
        let job = JobInfo {
            id,
            pid,
            child: Some(child),
            command,
            state,
            is_current: true,
        };

        // Mark previous current as not current
        if let Some(cur_id) = self.current_id {
            if let Some(j) = self.get_mut_internal(cur_id) {
                j.is_current = false;
            }
        }

        // Add new job
        let slot = self.get_free_slot();
        if slot >= self.jobs.len() {
            self.jobs.resize_with(slot + 1, || None);
        }
        self.jobs[slot] = Some(job);
        self.current_id = Some(id);

        id
    }

    /// Register a backgrounded job that was forked via raw `libc::fork()`
    /// (no `std::process::Child` wrapper). The wait path then has to
    /// `waitpid(pid)` instead of `Child::wait()`. Used by
    /// BUILTIN_RUN_BG so `wait` (no args) can synchronize on it.
    pub fn add_pid_job(&mut self, pid: i32, command: String, state: JobState) -> usize {
        let id = self.next_id;
        self.next_id += 1;
        let job = JobInfo {
            id,
            pid,
            child: None,
            command,
            state,
            is_current: true,
        };
        if let Some(cur_id) = self.current_id {
            if let Some(j) = self.get_mut_internal(cur_id) {
                j.is_current = false;
            }
        }
        let slot = self.get_free_slot();
        if slot >= self.jobs.len() {
            self.jobs.resize_with(slot + 1, || None);
        }
        self.jobs[slot] = Some(job);
        self.current_id = Some(id);
        id
    }

    fn get_free_slot(&self) -> usize {
        for (i, slot) in self.jobs.iter().enumerate() {
            if slot.is_none() {
                return i;
            }
        }
        self.jobs.len()
    }

    fn get_mut_internal(&mut self, id: usize) -> Option<&mut JobInfo> {
        self.jobs.iter_mut().flatten().find(|job| job.id == id)
    }

    /// Get a job by ID
    pub fn get(&self, id: usize) -> Option<&JobInfo> {
        self.jobs
            .iter()
            .flatten()
            .find(|&job| job.id == id)
            .map(|v| v as _)
    }

    /// Get a mutable job by ID
    pub fn get_mut(&mut self, id: usize) -> Option<&mut JobInfo> {
        self.get_mut_internal(id)
    }

    /// Remove a job by ID
    pub fn remove(&mut self, id: usize) -> Option<JobInfo> {
        for slot in self.jobs.iter_mut() {
            if slot.as_ref().map(|j| j.id == id).unwrap_or(false) {
                let job = slot.take();
                if self.current_id == Some(id) {
                    self.current_id = None;
                }
                return job;
            }
        }
        None
    }

    /// List all active jobs
    pub fn list(&self) -> Vec<&JobInfo> {
        self.jobs.iter().filter_map(|j| j.as_ref()).collect()
    }

    /// Iterate over jobs with their IDs (for compatibility)
    pub fn iter(&self) -> impl Iterator<Item = (usize, &JobInfo)> {
        self.jobs
            .iter()
            .filter_map(|j| j.as_ref().map(|job| (job.id, job)))
    }

    /// Count number of active jobs
    pub fn count(&self) -> usize {
        self.jobs.iter().filter(|j| j.is_some()).count()
    }

    /// Check if there are any jobs
    pub fn is_empty(&self) -> bool {
        self.count() == 0
    }

    /// Get current job
    pub fn current(&self) -> Option<&JobInfo> {
        self.current_id.and_then(|id| self.get(id))
    }

    /// Reap finished jobs (check for completed processes)
    pub fn reap_finished(&mut self) -> Vec<JobInfo> {
        let mut finished = Vec::new();

        for job in self.jobs.iter_mut().flatten() {
            if let Some(ref mut child) = job.child {
                // Try to check if child has finished without blocking
                match child.try_wait() {
                    Ok(Some(_status)) => {
                        // Child finished
                        job.state = JobState::Done;
                    }
                    Ok(None) => {
                        // Still running
                    }
                    Err(_) => {
                        // Error checking, assume done
                        job.state = JobState::Done;
                    }
                }
            }
        }

        // Remove done jobs
        for slot in self.jobs.iter_mut() {
            if slot
                .as_ref()
                .map(|j| j.state == JobState::Done)
                .unwrap_or(false)
            {
                if let Some(job) = slot.take() {
                    finished.push(job);
                }
            }
        }

        finished
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_job_table_new() {
        let _g = crate::test_util::global_state_lock();
        let table = JobTable::new();
        assert!(table.is_empty());
    }

    #[test]
    fn test_job_state_enum() {
        let _g = crate::test_util::global_state_lock();
        let state = JobState::Running;
        assert_eq!(state, JobState::Running);
        assert_ne!(state, JobState::Stopped);
        assert_ne!(state, JobState::Done);
    }

    #[test]
    fn test_add_pid_job_assigns_id() {
        let _g = crate::test_util::global_state_lock();
        let mut t = JobTable::new();
        let id1 = t.add_pid_job(1234, "cmd1".into(), JobState::Running);
        let id2 = t.add_pid_job(5678, "cmd2".into(), JobState::Running);
        assert_ne!(id1, id2);
        assert_eq!(t.list().len(), 2);
        assert_eq!(t.current().map(|j| j.id), Some(id2));
    }

    #[test]
    fn test_remove_drops_current() {
        let _g = crate::test_util::global_state_lock();
        let mut t = JobTable::new();
        let id = t.add_pid_job(99, "x".into(), JobState::Running);
        assert!(t.remove(id).is_some());
        assert!(t.is_empty());
        assert!(t.current().is_none());
    }
}