qp.CoprocessorFunction

class CoprocessorFunction(name, lib_path=None, config='', per_message=False, message_bytes=None)[source]

Bases: object

A precompiled function run on a Coprocessor to process messages received from the Controller.

This is a thin handle over a precompiled library symbol. It contains the information needed to locate and dispatch the function - its symbol name, and the library it lives in. The compiled artifact is produced separately (cross-compiled, or built on the same host, e.g., via Triton) and loaded by the runtime.

Warning

Backline is experimental and only usable through the Catalyst compiler.

Parameters:
  • name (str) – The name the function is known by, used to resolve the precompiled symbol.

  • lib_path (str, None) – Path to the shared library providing the symbol. Defaults to None, in which case the runtime resolves name from the symbols already loaded on the host.

  • config (str) – The function’s configuration, in the form of a semicolon-separated set of keys and values, for example "key1=value1;key2=value2". A function whose library exports lifecycle hooks under <name>_info (for example catalyst_onnx_coprocessor_info) receives these entries in its init hook once, before its first message, and is then called with the context that hook returns. The keys in_bytes and out_bytes are reserved for the message sizes, which Catalyst adds to the entries.

  • per_message (bool) – Whether the function is a host function called once per message, rather than a launcher that starts a persistent GPU kernel. This option applies only on a GPU coprocessor, which then runs the function per message, and only over the "memcpy" transport. On a CPU coprocessor every function is called per message.

  • message_bytes (tuple[int, int] or None) – The (in_bytes, out_bytes) message sizes the function expects, or None to declare none.

Example

A coprocessor function is usually named rather than constructed — passing a string to Coprocessor resolves it:

>>> coproc = qp.Coprocessor(coprocessor_fn="decoder")
>>> coproc.coprocessor_fn
CoprocessorFunction(name='decoder', lib_path=None, config='', per_message=False)

Construct one directly to point at a symbol in a specific shared library. The path is what the coprocessor’s node passes to the runtime as its backend library:

>>> fn = qp.CoprocessorFunction(
...     name="decode_syndrome", lib_path="/opt/backline/libdecoder.so"
... )
>>> fn.symbol_name
'decode_syndrome'

config

The function's configuration, as semicolon-separated keys and values such as "key1=value1;key2=value2", handed to the init hook its library exports under <name>_info.

lib_path

Path to the shared library that provides the symbol.

message_bytes

The (in_bytes, out_bytes) message sizes the function expects, or None when it does not declare them.

per_message

Whether the function is called once per message, rather than launching a persistent GPU kernel.

symbol_name

The symbol the runtime resolves and invokes for this function.

name

The name the function is known by; used to resolve the precompiled symbol.

config = ''

The function’s configuration, as semicolon-separated keys and values such as "key1=value1;key2=value2", handed to the init hook its library exports under <name>_info.

lib_path = None

Path to the shared library that provides the symbol. Defaults to None, in which case the runtime resolves name from the symbols already loaded on the host.

message_bytes = None

The (in_bytes, out_bytes) message sizes the function expects, or None when it does not declare them. A Placement takes the controller’s unset sizes from it, and rejects a controller size that differs.

per_message = False

Whether the function is called once per message, rather than launching a persistent GPU kernel.

symbol_name

The symbol the runtime resolves and invokes for this function.

name = <dataclasses._MISSING_TYPE object>

The name the function is known by; used to resolve the precompiled symbol.