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 callsapp.handle_input()from within atokio::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§
- Namespace
Driver - Dedicated-thread driver for direct
Namespaceaccess (cat/ls), with no Tcl interpreter involved at all. - Shell
Owner - Dedicated-thread owner for a
TclShell.