Runner

runner

Defines helpers for running the blocking external command calls defined in the launcher's core (Environment Checks, Docker Lifecycle Commands, ...) in a separate OS thread tied to the main page

The core's checks and lifecycle operations block (subprocess calls), so they are run via page.run_thread to keep the Flet UI responsive. Results are delivered back through callbacks that update controls

run_blocking(page, fn, on_done, on_error=None)

Runs a blocking function in a background thread

The on_done / on_error callbacks mutate UI controls, so they are marshalled back onto the page's event loop with page.run_task instead of running on the worker thread. Touching Flet controls off the event loop races the loop's own diffing and corrupts the control tree

Parameters:

Name	Type	Description	Default
page	Page	The page used to schedule the worker thread	required
fn	Callable[[], _T]	The blocking function to run	required
on_done	Callable[[_T], None]	Called with the result on success	required
on_error	Callable[[Exception], None] | None	Called on failures	None

run_stream(page, gen, terminal, *, on_done=None, on_error=None)

Runs a launcher.core generator on a background thread and streams its yielded output into a TerminalSurface

Behaviour

• Yielded lines are buffered and flushed to terminal in batches on the page's event loop, at most once per _FLUSH_INTERVAL_S, so a busy stream doesn't repaint the page per line

• All UI work (appending lines, the on_done / on_error callbacks) runs on the event loop via page.run_task

• The worker thread never touches Flet controls directly, which would race the loop's diff and corrupt the control tree

• The generator's return value is delivered to on_done

• launcher / process errors are mapped to a message for on_error

Parameters:

Name	Type	Description	Default
page	Page	The page used to schedule the worker thread	required
gen	Generator[str, None, Any]	The launcher.core generator to run	required
terminal	TerminalSurface	The surface in which to append output lines	required
on_done	Callable[[Any], None] | None	Called with the return value	None
on_error	Callable[[str], None] | None	Called with an error message	None