arblang 0.1.24

Visualize and modify Unix pipelines: pipe a stream in, arb spawns a dynamic TUI
Documentation
//! Running arb inside somebody else's process.
//!
//! The `arb` binary owns its process: it can `exit()` from anywhere in the
//! command line layer, leave the terminal in whatever mode the TUI put it, and
//! let the kernel reclaim the rest. A host that dispatches `arb` as one command
//! among many — the `arb` shell builtin in zshrs-native, where there is no fork
//! and no exec — can afford none of that. This module is the difference.
//!
//! [`crate::hosted::exit`] keeps `process::exit` when arb owns the process and unwinds when it
//! does not; [`crate::hosted::run`] catches the unwind and turns it back into the status the
//! exit asked for. Unwinding costs nothing on the path that does not take it,
//! and destructors still run — which is what puts the terminal back after a TUI
//! session that left through an exit.
//!
//! Threads are the other thing process exit used to clean up. Every thread an
//! invocation starts that reads a shared descriptor — the stdin feed, the
//! `/dev/tty` key reader — is stopped and joined before the invocation returns
//! (`cli::StdinFeed`, `tui::SessionEnd`, both drop guards). One left running
//! stays in the host: a reader still on fd 0 or the terminal takes the
//! keystrokes meant for the shell prompt and for the next `arb --fzf`.
//!
//! zvcs carries a module of the same shape for the same reason
//! (`src/extensions/src/hosted.rs`). They are deliberately separate: the flag is
//! per-crate state, each crate's payload type is its own, and neither crate
//! should grow a dependency on the other to be embeddable.

use std::cell::Cell;
use std::panic::{self, AssertUnwindSafe};
use std::path::PathBuf;
use std::sync::Once;

thread_local! {
    /// True while this thread is running a hosted invocation.
    static HOSTED: Cell<bool> = const { Cell::new(false) };
}

/// The payload [`exit`] unwinds with, carrying the status the caller wanted.
struct HostedExit(i32);

/// Whether this thread is inside [`run`].
pub fn is_hosted() -> bool {
    HOSTED.with(Cell::get)
}

/// `exit(code)`, in a form a host process survives.
///
/// Outside a host this is `std::process::exit` exactly. Inside one it unwinds
/// to the [`run`] that started the invocation, which returns `code`.
pub fn exit(code: i32) -> ! {
    if is_hosted() {
        panic::panic_any(HostedExit(code));
    }
    std::process::exit(code)
}

/// Teach the panic hook to stay quiet about [`HostedExit`], and to leave every
/// other panic to whatever hook the host installed.
fn install_quiet_hook() {
    static ONCE: Once = Once::new();
    ONCE.call_once(|| {
        let previous = panic::take_hook();
        panic::set_hook(Box::new(move |info| {
            if info.payload().is::<HostedExit>() {
                return;
            }
            previous(info);
        }));
    });
}

/// Run one hosted arb invocation and return the status it left with.
///
/// A panic that is not a `HostedExit` reports through the host's hook and
/// yields 1 — arb's own status for a failed run.
pub fn run<F>(f: F) -> i32
where
    F: FnOnce() -> i32,
{
    install_quiet_hook();

    let cwd: Option<PathBuf> = std::env::current_dir().ok();
    let previously = HOSTED.replace(true);

    let outcome = panic::catch_unwind(AssertUnwindSafe(f));

    HOSTED.set(previously);
    if let Some(dir) = cwd {
        let _ = std::env::set_current_dir(dir);
    }

    match outcome {
        Ok(code) => code,
        Err(payload) => match payload.downcast::<HostedExit>() {
            Ok(exit) => exit.0,
            Err(_) => 1,
        },
    }
}

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

    #[test]
    fn exit_from_inside_becomes_a_return_value() {
        assert_eq!(run(|| exit(2)), 2);
    }

    #[test]
    fn a_normal_return_is_untouched() {
        assert_eq!(run(|| 0), 0);
    }

    #[test]
    fn a_panic_becomes_a_failed_run() {
        assert_eq!(run(|| panic!("boom")), 1);
    }

    #[test]
    fn the_flag_is_off_again_afterwards() {
        assert!(!is_hosted());
        assert_eq!(run(|| if is_hosted() { 1 } else { 0 }), 1);
        assert!(!is_hosted());
    }

    #[test]
    fn the_working_directory_is_restored() {
        let before = std::env::current_dir().unwrap();
        assert_eq!(
            run(|| {
                std::env::set_current_dir(std::env::temp_dir()).unwrap();
                0
            }),
            0
        );
        assert_eq!(std::env::current_dir().unwrap(), before);
    }
}