Skip to main content

Module shell_driver

Module shell_driver 

Source
Expand description

Dedicated-thread async drivers for !Send language-shell interpreters (and, via NamespaceDriver, for direct Namespace access that doesn’t need an interpreter at all).

The synchronous slash-command path (ChatApp::handle_vfs_command) needs to run async VFS futures to completion from a key-event handler that must not spin. A Poll::Pending on a VFS read that legitimately blocks on an external event (e.g. an /exec/instances/<id>/exit read awaiting a worker-completion signal) must park the caller, not hot-spin a core — which a noop-waker poll loop cannot do, because a noop waker never delivers the wake-up.

§The driver

ShellOwner spawns one dedicated OS thread per shell. That thread runs a single-threaded tokio::runtime::Runtime (Builder::new_current_thread()) driving a tokio::task::LocalSet, the same pattern used by hyprstream-workers::workflow::runner’s per-job TclShell owner (crates/hyprstream-workers/src/workflow/runner.rs, run_job). Because the shell never leaves that thread, a Pending future registers a real waker tied to the runtime’s reactor/timer/notify machinery — the executor parks the thread (zero CPU) until something actually wakes it, instead of spinning.

TclShell’s !Send constraint (it wraps a molt Interp, which is Rc-based) is load-bearing here: the shell is constructed on, and never leaves, its owner thread — the whole point of a single-threaded LocalSet owner.

§The blocking eval() leg

ShellOwner::eval round-trips a request to the owner thread and waits for the reply over a plain std::sync::mpsc channel — deliberately NOT tokio::sync::oneshot::Receiver::blocking_recv(), because handle_input runs in two different contexts depending on how the TUI is hosted:

  • a bare OS thread with no tokio runtime at all (spawn_app_process / run_app_loop, the TuiService-hosted path), and
  • directly inside an active tokio runtime (the CLI shell’s event loop in crates/hyprstream/src/cli/shell_handlers.rs, which calls app.handle_input() from within a tokio::select! arm).

tokio::sync::oneshot::Receiver::blocking_recv() panics (“Cannot block the current thread from within a runtime”) in the second context. std::sync::mpsc has no opinion about tokio and parks the calling OS thread via a condvar in both contexts, so it is safe everywhere handle_vfs_command is called from. This blocks the calling (input-handling) thread for the duration of one eval — a parked wait, not a spinning one. Making handle_vfs_command fully non-blocking would mean enqueue-and-poll against ShellOwner rather than waiting inline.

Structs§

NamespaceDriver
Dedicated-thread driver for direct Namespace access (cat/ls), with no Tcl interpreter involved at all.
ShellOwner
Dedicated-thread owner for a TclShell.