qp.Coprocessor¶
- class Coprocessor(*, name=None, hardware='cpu', backend=None, remote=False, executor_options=None, executor=None, init_args=<factory>, coprocessor_fn, endpoint=None)[source]¶
Bases:
NodeThe node that runs a coprocessor function per received message.
A coprocessor receives messages from the
controller(e.g., syndromes). Thecoprocessor_fnis used to process the message, and sends the result back (e.g., corrections). Depending on the connection type, acoprocessor_fnmay be a persistent kernel. Pass coprocessors toBacklineto build a device.The coprocessor owns the connection
endpoint: it listens onEndpoint.port, and the controller dialsEndpoint.host:Endpoint.portto bring the connection up.Warning
Backlineis experimental and only usable through the Catalyst compiler.- Keyword Arguments:
name (str, None) – A name identifying the controller. Defaults to
None, letting the compiler derive one from the node’s role.hardware (str) – The hardware the coprocessing function executes on. Defaults to
"cpu"; other allowed values aregpu.fpgais not currently accepted for a coprocessor. The compiler combines this with the placement’sTransportto select the runtime backend.backend (str, None) – The name of the transport backend to run this node on. Defaults to
None, letting the compiler pick the default backend for the transport and hardware.remote (bool) – Whether the controller runs on another machine. Defaults to
False.coprocessor_fn (str, CoprocessorFunction) – The function that processes each received message. A string is wrapped in a
CoprocessorFunctionnaming that symbol, so reading the attribute back always gives aCoprocessorFunction.endpoint (Endpoint, None) – The address the controller dials to reach this coprocessor. Some transports, such as
"rdma", require it; others, such as"memcpy", do not use a network endpoint and may leave it unset.executor_options (dict, None) – Options for the executor to launch for this controller. Defaults to
None, which runs the node in this process. See theexecutor_optionsattribute below for every option it accepts.executor (object, None) – An already-launched executor to attach. Defaults to
None, in which case the compiler builds one fromexecutor_options.init_args (dict) – Backend-specific initialization arguments. Empty by default. See the
init_argsattribute below for the keys it accepts.
See
Nodefor the options every node shares.See also
Example
A coprocessor co-located with the controller needs only a function (and, for
"rdma", a loopback endpoint):>>> coproc = qp.Coprocessor(coprocessor_fn="decoder", endpoint=qp.Endpoint("127.0.0.1", 7760)) >>> coproc.coprocessor_fn.name 'decoder'
A remote GPU decoder names its endpoint, its hardware, and how to deploy to it:
coproc = qp.Coprocessor( name="gpu-decoder", coprocessor_fn="decoder", hardware="gpu", endpoint=qp.Endpoint("198.51.100.2", 7760), remote=True, executor_options={"host": "192.0.2.11", "port": 7813}, init_args={"config": "dev=mlx5_0;gid=3;gpu=0"}, )
Note that
Endpoint.hostandexecutor_options["host"]are two addresses for the same machine: the first is the interface the transport’s data path uses, the second is how the compiler reaches it to deploy code.Coprocessors are passed to
Backlineas a sequence:dev = qp.Backline(controller=qp.Controller(), coprocessors=[coproc], transport="rdma")
Attributes
The name of the transport backend to run this node on, out of those in Catalyst's transport backend registry that implement the placement's transport on this node's hardware.
The address the controller dials to reach this coprocessor.
The launched executor this node runs on.
Options for the executor to launch for this node, passed to it as keyword arguments.
The hardware this node executes on.
An optional name used to reference this node.
Whether this node runs on another machine, so that the libraries it loads are the ones installed beside it there rather than the ones in this installation.
The function for processing each received message.
Backend-specific initialization arguments, forwarded to the transport backend.
- backend = None¶
The name of the transport backend to run this node on, out of those in Catalyst’s transport backend registry that implement the placement’s transport on this node’s hardware. Defaults to
None, letting the compiler pick the default one. Naming one selects a backend that is not a default, such as"fpga_verbs", or one installed by a backend package.
- endpoint = None¶
The address the controller dials to reach this coprocessor. Some transports, such as
"rdma", require it; others, such as"memcpy", do not use a network endpoint and may leave it unset.
- executor = None¶
The launched executor this node runs on. Created automatically by the compiler from
executor_options; set it directly to attach one that is already launched, in which caseexecutor_optionsis ignored.
- executor_options = None¶
Options for the executor to launch for this node, passed to it as keyword arguments.
None(the default) requests no executor, leaving the node in this process.Which machine, and how it is reached
"host"(str) - deploy the executor to this host over ssh. Requires"port", so that the address is known without having to reach the host at compile time."address"(str) -"host:port"of an executor whose lifetime is managed elsewhere. Attach to it rather than launching one."port"(int) - the port the executor binds on the target, and the local end of the ssh tunnel reaching it. Omit it for a local executor and the compiler picks a free port."user"(str) - the ssh account on the remote host. Defaults to the local username.
Naming neither
"host"nor"address"runs the executor as a subprocess on this machine.What is placed on the target
"workspace"(str) - the directory the executor runs in. Defaults to a generatedcatalyst-exec-*directory removed on teardown; one named here is left in place."deploy"(list[str]) - files and directories copied into the workspace before the executor starts. A directory contributes the files inside it, which is how a cross-built set of artifacts travels."plugins"(list[str]) - shared libraries the executor loads at startup, in order. They share one symbol namespace, so the first definition wins. The compiler appends the libraries this node implies - a coprocessor’s decode function, a controller’s device runtime - if they are not already listed."executor_bin"(str) - the command that starts the executor, for wrapping it in something likenumactl.
How the process runs
"env"(dict[str, str]) - environment variables for the executor process."sudo"(bool) - run it as root, for a target whose devices are not world-accessible. Defaults toFalse."sudo_password_env"(str) - name of the environment variable holding the password to pipe tosudo -S, e.g."MY_HOST_SUDO_PW". If unset and sudo is required, a prompt will launch for the password; unnecessary with passwordless sudo."ready_timeout"(float) - seconds to wait for the executor to report that it bound its port. Defaults to60.0."verbose"(int) - how much the launcher logs:0quiet,1normal,2per-command detail.
Code generation and identity
"triple"(str) - the LLVM target triple to compile this node’s code for. Omit it and the executor detects it from the target’suname, which requires reaching the host."name"(str) - the executor’s own label, used in its log filenames. Defaults to this node’sname.
Note that
"port"here is the executor’s, on the channel that ships compiled code. It is unrelated toport, which is the transport’s handshake port. An unrecognized key raises.Warning
These options are defined by the Catalyst compiler, and may not be stable.
- hardware = 'cpu'¶
The hardware this node executes on. The compiler combines this with the placement’s
Transportto select the runtime backend.
- name = None¶
An optional name used to reference this node.
- remote = False¶
Whether this node runs on another machine, so that the libraries it loads are the ones installed beside it there rather than the ones in this installation. Defaults to
False.This is about the machine, not the process: it says where the node’s libraries are resolved, and
executor_optionsindependently says whether its code runs in a process of its own. The three valid combinations are:remote=Truewithexecutor_options: out-of-process on another machine, reached by deploying an executor there. A remote node cannot be reached without one.remote=Falsewithexecutor_options: out-of-process on this machine, in an executor subprocess whose libraries still resolve from this installation.remote=Falsewith noexecutor_options: in-process, the default.
- coprocessor_fn = <dataclasses._MISSING_TYPE object>¶
The function for processing each received message. Accepts a
CoprocessorFunction, or a string naming the symbol, which is wrapped in one on construction - so this attribute always reads back as aCoprocessorFunction. The symbol itself is resolved later, by the runtime.
- init_args = <dataclasses._MISSING_TYPE object>¶
Backend-specific initialization arguments, forwarded to the transport backend. Empty by default (never
None). The keys the compiler forwards are"backend_lib"(str) - explicit path to the transport backend library, taking precedence overhardwareand overlib_path."config"(str) - a;-separatedkey=valuestring configuring the backend on this machine, e.g."dev=mlx5_0;gid=3".devandgidselect the RDMA device and GID index; the remaining keys are backend-specific (a GPU backend takesgpu=, an FPGA engine takessq_mem=/data_mem=/reply_mem=).
Keys outside this set are rejected when the program is compiled.