catalyst.Executor

class Executor(address: str | None = None, *, host: str | None = None, user: str = '', port: int | None = None, workspace: str | None = None, plugins: list[str] | None = None, deploy: list[str | Path] | None = None, ready_timeout: float = 60.0, name: str = 'executor', sudo: bool = False, sudo_password: str | None = None, executor_bin: str | None = None, triple: str | None = None, env: dict[str, str] | None = None, verbose: int = 1)

Bases: object

A catalyst-executor process, addressable over TCP at address. Construction is inert; launch() / stop() are idempotent, and with Executor(...) as ex: launches on entry and stops on exit.

Three modes:

• host=<addr>: remote over forwarded SSH. deploy=[...] first scp’s those directories and files into the workspace.

• address: attach to an executor whose lifetime is managed elsewhere.

• neither: subprocess on 127.0.0.1 (no SSH).

Attributes

address	The host:port the executor serves on.
triple	explicit triple= if given, else auto-detected via uname.

address

The host:port the executor serves on. Raises RuntimeError if it is neither launched nor committed to an address by resolve().

triple

explicit triple= if given, else auto-detected via uname. None when undetectable (the compiler falls back to the host triple).

Type:

LLVM target triple

Methods

launch()	Deploy the executor and return self.
remove_workspace([force])	Remote only.
resolve()	Commit to the address this executor will serve on, without deploying it.
setup_workspace()	Remote only.
stop()	Tear down the executor + tunnel and deregister from the atexit hook.

launch() → Self

Deploy the executor and return self. Idempotent, chainable. See the class docstring for the three modes.

remove_workspace(force: bool = False) → None

Remote only. Delete a pinned workspace. Refuses to delete / or $HOME.

force=True re-raises SSH errors; default swallows them. The safety refusal always raises.

Raises:

ValueError – If host or workspace is missing.

resolve() → Executor | None

Commit to the address this executor will serve on, without deploying it.

Compiled programs carry their executor’s address, so it has to be known before the executor runs; committing to it here lets the deployment wait until execution. Only possible when the address is predictable: an attached executor already has one, and a deployed one needs port= pinned, since a free-port search settles the address only at launch.

Returns:

self if an address could be committed to, None if it is only knowable by launching and the caller should do that.

Return type:

Executor | None

setup_workspace() → Self

Remote only. Deploy the bundle to a persistent workspace without starting the executor.

Requires host, pinned workspace=, and deploy=. Idempotent; a later launch() (or a fresh Executor(..., workspace=<same>)) reuses it. Delete via remove_workspace().

Raises:

ValueError – If host, workspace, or deploy is missing.

stop() → None

Tear down the executor + tunnel and deregister from the atexit hook. Idempotent. Auto-generated workspaces are removed; a pinned workspace= stays for remove_workspace(). Shutdown errors are swallowed (best-effort).

code/api/catalyst.Executor

 

Download Python script

 

Download Notebook

 

View on GitHub