pxl::Launcher Class Reference

Execution context for kernel launches on XCENA devices. More...

#include <launcher.hpp>

Public Member Functions
	Launcher ()
	Constructs a Launcher with deferred device detection. More...
	Launcher (uint32_t deviceId)
	Constructs a Launcher for an explicit device ID. More...
	~Launcher ()
	Launcher (const Launcher &)=delete
Launcher &	operator= (const Launcher &)=delete
	Launcher (Launcher &&) noexcept
Launcher &	operator= (Launcher &&) noexcept
template<auto Func, typename... Args, detail::EnableCompatibleKernelArguments< Func, Args... > = 0>
LaunchBuilder	execute (uint32_t taskCount, Args &&... args)
	Launches a kernel for deferred execution. More...
template<auto Func, typename... Args, detail::EnableCompatibleKernelArguments< Func, Args... > = 0>
detail::TaskCountRequired< LaunchBuilder >	execute (Args &&... args)
	Launches a kernel with only the kernel's own arguments. More...
template<auto Func, typename... Args, detail::EnableCompatibleKernelArguments< Func, Args... > = 0>
StageBuilder	stage (uint32_t taskCount, Args &&... args)
	Begins a stage chain with a sequential kernel stage. More...
template<auto Func, typename... Args, detail::EnableCompatibleKernelArguments< Func, Args... > = 0>
detail::TaskCountRequired< StageBuilder >	stage (Args &&... args)
	Begins a stage chain with only the kernel's own arguments. More...
StageGroupBuilder	stage ()
	Begins a parallel stage group. More...
uint32_t	deviceId () const
	Returns the device ID. More...
bool	isValid () const
	Returns whether the launcher was initialized successfully. More...

Detailed Description

Execution context for kernel launches on XCENA devices.

Provides kernel launch capabilities. Device is either specified explicitly or auto-detected from the first pointer argument in execute()/pipeline().

Example usage:

auto* A = pxl::allocateMemory<int>(0, 1024);
auto* B = pxl::allocateMemory<int>(0, 1024);
 
auto result = pxl::Launcher().execute<vectorAdd>(A, B, elementCount).tasks(taskCount).run();
if (result.status != pxl::Result::Success) { ... }
 
pxl::releaseMemory(A);
pxl::releaseMemory(B);

Definition at line 266 of file launcher.hpp.

Constructor & Destructor Documentation

Launcher() [1/4]

pxl::Launcher::Launcher

(

)

Constructs a Launcher with deferred device detection.

Device selection priority on the first execute()/stage() call:

1. If any pointer argument was returned by pxl::allocateMemory(), use that pointer's device. Mixed-device pointer args are rejected with a launch-time failure.
2. Otherwise, fall back to the process-default device cache (see pxl::getDefaultDeviceId() in context.hpp). If the cache is unpopulated, the first computable device is picked and cached ONLY when resolved from a pointer arg — pickDefaultForCompute itself does not clobber a user-set default.
3. If neither path resolves a device, run()/runAsync() returns pxl::kNoDeviceResolvedMessage.

Once bound on the first call, the device is reused for every subsequent execute()/stage() on the same Launcher; cross-device pointer args are rejected at run()/runAsync() time.

Launcher() [2/4]

pxl::Launcher::Launcher ( uint32_t  deviceId )

explicit

Constructs a Launcher for an explicit device ID.

Use this when all kernel arguments are scalars (no device pointers), or when you want to override the auto-detection logic. The explicit deviceId always wins — even if a pointer argument resolves to a different device, the kernel runs on deviceId (and the cross-device check in run() will surface the mismatch as a launch failure).

Side effect: a successful explicit construction updates the process-wide default device cache (see pxl::getDefaultDeviceId()). Subsequent auto-allocations (allocateMemory(N) without deviceId) and default-Launcher() calls will favor this device until the cache is cleared via pxl::clearDefaultDeviceId().

Parameters

deviceId

Target device identifier.

~Launcher()

pxl::Launcher::~Launcher

(

)

Launcher() [3/4]

pxl::Launcher::Launcher ( const Launcher &  )

delete

Launcher() [4/4]

pxl::Launcher::Launcher ( Launcher &&  )

noexcept

Member Function Documentation

deviceId()

uint32_t pxl::Launcher::deviceId

(

)

const

Returns the device ID.

execute() [1/2]

template<auto Func, typename... Args, detail::EnableCompatibleKernelArguments< Func, Args... > = 0>

detail::TaskCountRequired<LaunchBuilder> pxl::Launcher::execute ( Args &&...  args )

inline

Launches a kernel with only the kernel's own arguments.

Set the task count on the returned builder with .tasks(taskCount). Kernel arity distinguishes this form from the positional compatibility form, including when the kernel's first argument is an integer. The pending return type exposes no run()/runAsync(), so attempting execution before .tasks(taskCount) is a C++ compile error. Discarding the pending request instead produces its [[nodiscard]] diagnostic and executes nothing.

Definition at line 384 of file launcher.hpp.

    {
        return detail::TaskCountRequired<LaunchBuilder>(
            execute<Func>(uint32_t{0}, std::forward<Args>(args)...));
    }

execute() [2/2]

template<auto Func, typename... Args, detail::EnableCompatibleKernelArguments< Func, Args... > = 0>

LaunchBuilder pxl::Launcher::execute ( uint32_t  taskCount, Args &&...  args  )

inline

Launches a kernel for deferred execution.

Template Parameters

Func	Kernel function pointer (must have KernelTraits specialization from pxcc).
Args	Kernel argument types.

Parameters

taskCount	Number of tasks to execute.
args	Kernel arguments (device memory pointers and scalars).

Returns

LaunchBuilder for chaining .reserve()/.run().

Directional kernel parameters require the exact kernel argument count and a compatible typed pointer or typed NDArray. Raw void* allocations must be cast to the kernel element type (or allocated with allocateMemory<T>()) so element mismatches remain diagnosable.

Warning

A raw pointer passed to an output_ptr parameter makes the entire managed allocation range from that pointer discardable and synchronized back; use an NDArray argument to bound a smaller output view.

Definition at line 336 of file launcher.hpp.

    {
        const char* kernelName = nullptr;
 
#if defined(__PXCC_ANALYSIS__)
        kernelName = "__pxcc_placeholder__";
#else
        static_assert(sizeof(pxl::KernelTraits<Func>) > 0,
                      "Kernel function not found in KernelTraits — was it compiled with pxcc?");
        kernelName = pxl::KernelTraits<Func>::name;
#endif
 
        std::vector<ArgInfo_t> argList;
        std::vector<std::shared_ptr<void>> storage;
        std::vector<std::pair<void*, size_t>> syncTargets;
        auto directions = detail::MakeKernelDirections<Func>();
        argList.reserve(sizeof...(Args));
        if constexpr (sizeof...(Args) > 0)
        {
            buildArgList(argList, storage, syncTargets, std::forward<Args>(args)...);
        }
 
        if (impl_ == nullptr)
        {
            initFromArgs(argList, syncTargets);
        }
        if (!isValid())
        {
            return makeEmptyBuilder();
        }
 
        return execute(kernelName, taskCount,
                       std::move(argList), std::move(storage), std::move(syncTargets),
                       std::move(directions));
    }

isValid()

bool pxl::Launcher::isValid

(

)

const

Returns whether the launcher was initialized successfully.

operator=() [1/2]

Launcher& pxl::Launcher::operator= ( const Launcher &  )

delete

operator=() [2/2]

Launcher& pxl::Launcher::operator= ( Launcher &&  )

noexcept

stage() [1/3]

StageGroupBuilder pxl::Launcher::stage ( )

inline

Begins a parallel stage group.

Device is auto-detected from pointer arguments when run() is called.

Example:

auto result = pxl::Launcher()
    .stage()
        .add<K1>(A, B).tasks(firstTaskCount)
        .add<K2>(C, D).tasks(secondTaskCount)
    .stage<K3>(E, F).tasks(finalTaskCount)
    .run();

Definition at line 459 of file launcher.hpp.

    {
        // Allocate the parent StageBuilder on the heap and transfer ownership
        // to the returned StageGroupBuilder. Without owning the parent here,
        // the StageGroupBuilder would hold a reference into this stack frame
        // and dangle as soon as the function returns.
        return StageGroupBuilder(std::make_unique<StageBuilder>(impl_));
    }

stage() [2/3]

template<auto Func, typename... Args, detail::EnableCompatibleKernelArguments< Func, Args... > = 0>

detail::TaskCountRequired<StageBuilder> pxl::Launcher::stage ( Args &&...  args )

inline

Begins a stage chain with only the kernel's own arguments.

Set the task count for the new stage with .tasks(taskCount). Kernel arity distinguishes this form from the positional compatibility form. The pending return type exposes no run()/runAsync() or next stage operation.

Definition at line 438 of file launcher.hpp.

    {
        return detail::TaskCountRequired<StageBuilder>(
            stage<Func>(uint32_t{0}, std::forward<Args>(args)...));
    }

stage() [3/3]

template<auto Func, typename... Args, detail::EnableCompatibleKernelArguments< Func, Args... > = 0>

StageBuilder pxl::Launcher::stage ( uint32_t  taskCount, Args &&...  args  )

inline

Begins a stage chain with a sequential kernel stage.

Template Parameters

Func	Kernel function pointer.

Parameters

taskCount	Number of tasks to execute.
args	Kernel arguments.

Returns

StageBuilder for chaining additional stages.

Example:

auto result = pxl::Launcher()
    .stage<K1>(data, mid).tasks(taskCount)
    .stage<K2>(mid, out).tasks(taskCount)
    .run();

Definition at line 408 of file launcher.hpp.

    {
        if (impl_ == nullptr)
        {
            std::vector<ArgInfo_t> tempArgList;
            std::vector<std::shared_ptr<void>> tempStorage;
            std::vector<std::pair<void*, size_t>> tempSyncTargets;
            tempArgList.reserve(sizeof...(Args));
            if constexpr (sizeof...(Args) > 0)
            {
                buildArgList(tempArgList, tempStorage, tempSyncTargets, std::forward<Args>(args)...);
            }
            initFromArgs(tempArgList, tempSyncTargets);
        }
        StageBuilder builder(impl_);
        // Call returns StageBuilder& to the local; discard ref and return the
        // local by value to enable NRVO (StageBuilder is move-only).
        builder.stage<Func>(taskCount, std::forward<Args>(args)...);
        return builder;
    }

---

The documentation for this class was generated from the following file:

• launcher.hpp