Configurable kernel execution request.
More...
#include <launcher.hpp>
Configurable kernel execution request.
Returned after a task count has been supplied through .tasks() or the positional compatibility overload. Call .run() to execute, with optional launch settings chained before it.
- Note
- The Launcher may be temporary. Argument buffers must remain valid until execution completes, including asynchronous execution.
Example:
LaunchBuilder & tasks(uint32_t taskCount)
Sets how many tasks invoke the kernel.
LaunchResult run()
Executes the kernel and waits for completion.
LaunchBuilder & reserve(uint32_t n)
Sets the number of Sub resources to reserve (Mid-Level).
Execution context for kernel launches on XCENA devices.
LaunchBuilder execute(uint32_t taskCount, Args &&... args)
Launches a kernel for deferred execution.
Definition at line 55 of file launcher.hpp.
◆ ~LaunchBuilder()
| pxl::LaunchBuilder::~LaunchBuilder |
( |
| ) |
|
◆ LaunchBuilder() [1/2]
◆ LaunchBuilder() [2/2]
◆ batchSize()
Sets per-task batch size for kernel execution. If not called, the runtime uses an implementation-defined default.
- Parameters
-
| n | Tasks per batch. Must be > 0; n == 0 is invalid and yields a launch failure at run()/runAsync(). |
- Returns
- Reference to this builder for chaining.
◆ clusterBitmap()
| LaunchBuilder& pxl::LaunchBuilder::clusterBitmap |
( |
uint32_t |
bitmap | ) |
|
Sets the cluster bitmap (0 = use all clusters).
Calling clusterBitmap(0) is equivalent to not calling this method at all — both leave the runtime free to use every available cluster. The MapImpl underlying setter requires the bitmap to be <= 0xF on current hardware (4 clusters); passing a higher value is rejected by the lower layer.
- Parameters
-
| bitmap | Cluster mask to restrict execution. |
- Returns
- Reference to this builder for chaining.
◆ enableProfile()
| LaunchBuilder& pxl::LaunchBuilder::enableProfile |
( |
const xpti::ProfileConfig & |
config | ) |
|
Enables profiling for this kernel.
Map::enableProfiling() returns a Result; failures are logged but NOT propagated to run()/runAsync(). The fire-and-forget contract keeps profile-enable failures from masking real kernel errors.
- Parameters
-
| config | Profiling configuration to apply when buildMap() runs. |
- Returns
- Reference to this builder for chaining.
◆ locality()
Sets the locality mode for this kernel. If not called, the runtime uses an implementation-defined default.
- Parameters
-
- Returns
- Reference to this builder for chaining.
◆ onComplete()
Registers a completion callback for successful execution.
Threading contract:
- For
run(): cb fires on the calling thread before run() returns.
- For
runAsync(): cb fires on the runtime worker thread before the returned future is satisfied. arg must remain valid until either run() returns or future.get() (or future destruction) completes.
- Parameters
-
| cb | Callback invoked with arg when the Map completes. |
| arg | Opaque user pointer passed to the callback. |
- Returns
- Reference to this builder for chaining.
◆ onError()
Registers an error callback for execution failure.
Threading contract matches onComplete() — see that doc.
- Parameters
-
| cb | Callback invoked with arg when the Map fails. |
| arg | Opaque user pointer passed to the callback. |
- Returns
- Reference to this builder for chaining.
◆ onMessage()
Registers a message callback for device-originated messages.
Threading contract matches onComplete() — see that doc. Note that device messages may arrive multiple times during a single run() (the device can post messages mid-execution), unlike onComplete/onError which fire at most once per launch.
- Parameters
-
| cb | Callback invoked with the message buffer and arg. The message buffer is owned by the runtime and only valid for the duration of the callback. |
| arg | Opaque user pointer passed to the callback. |
- Returns
- Reference to this builder for chaining.
◆ operator=() [1/2]
◆ operator=() [2/2]
◆ reserve()
Sets the number of Sub resources to reserve (Mid-Level).
If not called, all available resources are used (High-Level).
- Parameters
-
| n | Number of Subs to reserve. |
- Returns
- Reference to this builder for chaining.
◆ run()
Executes the kernel and waits for completion.
run() and runAsync() together share a once-only contract on this builder: calling either of them a second time returns a Failure with the message pxl::kAlreadyCalledMessage (mutually exclusive — the second call fails regardless of which method was used first).
- Returns
- LaunchResult containing result status, error message, and elapsed time. elapsedUs measures kernel execute + synchronize time (excludes IoMem sync overhead). Any exception thrown by the internal executor is converted to Failure with an
errorMessage describing the exception.
◆ runAsync()
Executes the kernel asynchronously.
Returns immediately with a future that resolves when the kernel completes.
Fire-and-forget contract:
- The returned future may be safely dropped without calling .get(); the kernel still executes to completion. (Internally driven by a detached worker thread + shared promise, NOT std::async — the latter's future has a blocking destructor under the async policy.)
- future.get() NEVER throws. Any exception out of the runtime is captured and surfaces as LaunchResult{Failure, …, errorMessage}.
- For graceful shutdown of a fire-and-forget caller, retain at least one outstanding future and call future.wait() before process exit; otherwise a detached worker may be terminated mid-IoMem sync.
Shares the once-only contract with run() — see that doc.
- Returns
- std::future<LaunchResult> that resolves when kernel execution completes.
Example:
auto result = future.get();
std::future< LaunchResult > runAsync()
Executes the kernel asynchronously.
◆ stream()
Routes the kernel through a user-managed stream.
3-state semantics:
- Not calling this method: leaves the Map's default stream untouched (runtime default).
stream(p) with p != nullptr: route through the user-supplied Stream. p must outlive run()/runAsync().stream(nullptr): explicitly reset the Map back to its default stream — distinct from "not calling stream()" so a previously set user stream can be unset via the chain.
- Parameters
-
| s | Stream pointer (or nullptr to reset to default). |
- Returns
- Reference to this builder for chaining.
◆ tasks()
Sets how many tasks invoke the kernel.
This keeps execute() limited to the kernel's own arguments. A count passed positionally to execute() is retained for source compatibility; calling tasks() replaces that value.
- Parameters
-
| taskCount | Task count. Must be > 0. |
- Returns
- Reference to this builder for chaining.
◆ impl::LaunchBuilderTestAccess
| friend class impl::LaunchBuilderTestAccess |
|
friend |
◆ Launcher
The documentation for this class was generated from the following file:
1.9.1