qp.runtime_call¶
- runtime_call(target, *args, signature=None, out_bytes=0, address=None, library=None)[source]¶
Call a declared runtime symbol, in-process or on the executor it is addressed to.
A symbol is declared once with
runtime_declare(), then called by name from inside aqjit()program. For a one-off call, pass its signature withsignature=or pass aCSignatureastarget.Passing
addressdispatches the call: it is recorded into the program and sent to that executor, which invokes the symbol on the machine the runtime lives on. Omittingaddressmakes the call local: the symbol is invoked in the process running the compiled program, through the ordinary in-process C ABI.Dispatched (
addressset): A dispatched call is run by the Catalyst executor. The lower-runtime-dispatch pass turns it into anexecutor.call, which reaches__catalyst__executor__call_wrapperon the addressed machine. That calls the symbol through LLVM ORC’s wrapper convention. You need to have a catalyst executor running on the addressed machine, which can be enabled from within a backline-controlled QJIT function.Local (
addressisNone): A local call is run in the process running the compiled program. The symbol is resolved and invoked directly through its declared C ABI. Scalars are passed by value,ptris a native pointer, andstrisconst char *. Abuforoutuses compiler-internal bufferization to obtain its data pointer.libraryis recorded on the compiled module so the driver links the shared library that exports the symbol.- Parameters:
target (str, CSignature) – the declared symbol name, or its complete signature
*args – one argument per declared parameter except
out, in declaration ordersignature (str, CSignature, None) – the signature for a symbol not yet declared, using the
"(parameter, ...) -> result"form or aCSignatureout_bytes (int, Sequence[int]) – the compile-time size of each
outbufferaddress (str, None) – the executor to dispatch to, as
"host:port".Nonemakes the call local (in-process).library (str, None) – for a local call, the shared library exporting the symbol, recorded so the driver links it. Overrides the library set at
runtime_declare()time. Ignored for a dispatched call.
- Returns:
The symbol’s declared result. A symbol with one
outparameter returns(result, buffer). With several, the buffers follow the result in the order they are declared. A local call to avoidsymbol returnsNone.
Example
import pennylane as qp qp.runtime_declare("example_call_rounds", "(ptr, u32) -> u64") def program(session): # the body of a qjit program return qp.runtime_call("example_call_rounds", session, 100000, address="board:9000")
A symbol that fills a buffer declares it as an
outparameter. The caller does not pass one: it asks forout_bytes=and gets the filled buffer back alongside the result.qp.runtime_declare("example_call_collect", "(ptr, out, u64) -> i32") def collect(session): status, reply = qp.runtime_call( "example_call_collect", session, 64, out_bytes=64, address="board:9000", ) return reply
For example, the above call to this symbol declared
(ptr, out, u64) -> i32:sessionis theptr.The
outtakes no argument. The symbol writes that buffer, so there is nothing to pass in.64is theu64: this symbol’s own argument for how many bytes it may write.out_bytes=64says how big a buffer to give it. The number shows up twice because one is what you tell the symbol and the other is what you hand it, so keep the two in step.The call returns two results:
status, thei32the symbol returned, andreply, which corresponds to theoutbuffer it filled in, as auint8array ofout_bytesbytes.
A symbol can declare more than one
out. Giveout_bytesone size per buffer, and they return in the order they are declared, for example:qp.runtime_declare("example_call_two_regions", "(ptr, out, out, u64) -> i32") def collect_both(session): status, first, second = qp.runtime_call( "example_call_two_regions", session, 96, out_bytes=(32, 64), address="board:9000", ) return first, second
See also