Manages device compute resources and offloads user applications. More...

#include <job.hpp>

Public Types
using	AsyncCallback = std::function< void(Job job, void arg)>
	Callback type for asynchronous job creation. More...

Public Member Functions
	Job (const Job &)=delete
	Deleted copy constructor. More...

Job &	operator= (const Job &)=delete
	Deleted copy assignment operator. More...

virtual Result	load (const char *muBinaryPath)=0
	Loads binary data into this job. More...

virtual Result	load (const pxl::Module *module)=0
	Loads a module into this job. More...

virtual bool	isLoaded () const =0
	Check whether MU binary is loaded on the job. More...

virtual const std::vector< uint32_t >	subIdList () const =0
	Returns the list of sub IDs associated with this job. More...

virtual Map *	buildMap (const char *muFuncName, const uint32_t taskCount)=0
	create a map object from the job. More...

virtual Map *	buildMap (const pxl::Function *muFunc, const uint32_t taskCount)=0
	create a map object from the job. More...

virtual Map *	buildMap (const uint32_t taskCount)=0
	create a map object from the job. More...

virtual void	destroyMap (Map *map)=0
	Destroys the specified map. More...

virtual uint64_t	id () const =0
	Returns this Job's identifier. More...

virtual uint32_t	deviceId () const =0
	Device this Job runs on. More...

virtual Result	reload (const char *muBinaryPath)=0
	Swaps the loaded binary on this job, keeping its Sub set. More...

virtual Result	reload (const pxl::Module *module)=0
	Swaps the loaded module on this job, keeping its Sub set. More...

virtual void *	allocateMemory (size_t size, AllocFlag flag=AllocFlag::None)=0
	Allocates device memory used only by this Job. More...

template<typename T >
T *	allocateMemory (size_t count, AllocFlag flag=AllocFlag::None)
	Allocates typed device memory used only by this Job. More...

virtual Result	remapMemory (void *ptr, uintptr_t virtualAddr)=0
	Makes this Job's private memory reachable by the kernel at a chosen address. More...

virtual Result	unmapMemory (uintptr_t virtualAddr)=0
	Removes a remapMemory mapping. The backing is not freed. More...

Protected Member Functions
	Job ()=default

virtual	~Job ()=default

Detailed Description

Manages device compute resources and offloads user applications.

A Job represents a collection of computing resources (one or more Sub units) allocated within a Context. It is responsible for managing these resources and offloading user applications to the device for execution. It offers functionality for:

Loading a binary file (Module) into the device.
Reloading a different binary onto the same Subs without recreating the job.
Creating Map objects for kernel execution.

Definition at line 31 of file job.hpp.

Member Typedef Documentation

◆ AsyncCallback

using pxl::Job::AsyncCallback = std::function<void(Job* job, void* arg)>

Callback type for asynchronous job creation.

Parameters

job	Pointer to the created Job, or nullptr on failure.
arg	Argument passed through to the callback.

Definition at line 40 of file job.hpp.

Constructor & Destructor Documentation

◆ Job() [1/2]

pxl::Job::Job ( const Job & )

delete

Deleted copy constructor.

◆ Job() [2/2]

pxl::Job::Job ( )

protecteddefault

◆ ~Job()

virtual pxl::Job::~Job ( )

protectedvirtualdefault

Member Function Documentation

◆ allocateMemory() [1/2]

template<typename T >

T* pxl::Job::allocateMemory	(	size_t	count,
		AllocFlag	flag = `AllocFlag::None`
	)

inline

Allocates typed device memory used only by this Job.

Template Parameters

T	Element type.

Parameters

count	Number of elements to allocate.
flag	Optional allocation flag.

Returns: Pointer to the allocated memory, or nullptr on failure.

Definition at line 234 of file job.hpp.

     {
         if (count > 0 && count > SIZE_MAX / sizeof(T))
         {
             return nullptr;
         }
         return static_cast<T*>(allocateMemory(count * sizeof(T), flag));
     }

◆ allocateMemory() [2/2]

virtual void* pxl::Job::allocateMemory	(	size_t	size,
		AllocFlag	flag = `AllocFlag::None`
	)

pure virtual

Allocates device memory used only by this Job.

Unlike pxl::allocateMemory (shared across the device), memory returned here is private to this Job. Release it with pxl::releaseMemory.

If another Job uses this memory, setInput/setOutput reject it; reaching it any other way may cause a device error.

Parameters

size	Size in bytes to allocate.
flag	Optional allocation flag to control initial memory state.

Returns: Pointer to the allocated memory, or nullptr on failure.

◆ buildMap() [1/3]

virtual Map* pxl::Job::buildMap	(	const char *	muFuncName,
		const uint32_t	taskCount
	)

pure virtual

create a map object from the job.

Parameters

muFuncName	Name of the function to be executed in the map operation.
taskCount	Number of tasks to be executed in the map operation.

Returns: Pointer to the created Map object.

Example usage:

auto map = job->buildMap("myFunction", 100);

◆ buildMap() [2/3]

virtual Map* pxl::Job::buildMap	(	const pxl::Function *	muFunc,
		const uint32_t	taskCount
	)

pure virtual

create a map object from the job.

Parameters

muFunc	Function to be executed in the map operation.
taskCount	Number of tasks to be executed in the map operation.

Returns: Pointer to the created Map object.

Example usage:

auto module = pxl::createModule("test.mubin");
auto muFunc = module->createFunction("myFunction");
auto map = job->buildMap(muFunc, 100);

◆ buildMap() [3/3]

virtual Map* pxl::Job::buildMap ( const uint32_t taskCount )

pure virtual

create a map object from the job.

Parameters

taskCount Number of tasks to be executed in the map operation.

Returns: Pointer to the created Map object.

Example usage:

auto taskCount = 100;

auto map = job->buildMap(taskCount);

◆ destroyMap()

virtual void pxl::Job::destroyMap ( Map * map )

pure virtual

Destroys the specified map.

Parameters

map	Pointer to the map to be destroyed.

When called from one of this Map's callbacks, this function cannot wait for the Map's in-flight work because the callback itself is part of that work. It returns immediately. If no work remains, the Map is deleted in place; otherwise, deletion is deferred until the remaining work completes. The pointer is invalid as soon as this function is called and must not be reused.

Example usage:

job->destroyMap(map);

◆ deviceId()

virtual uint32_t pxl::Job::deviceId ( ) const

pure virtual

Device this Job runs on.

◆ id()

virtual uint64_t pxl::Job::id ( ) const

pure virtual

Returns this Job's identifier.

◆ isLoaded()

virtual bool pxl::Job::isLoaded ( ) const

pure virtual

Check whether MU binary is loaded on the job.

Returns: True if the MU binary or module is loaded, false otherwise.

◆ load() [1/2]

virtual Result pxl::Job::load ( const char * muBinaryPath )

pure virtual

Loads binary data into this job.

Parameters

muBinaryPath Path to the binary file.

Returns: Result indicating the success or failure of the operation.

Example usage:

auto job = context->createJob();
auto result = job->load("path/to/test.mubin");
if (result != pxl::Result::Success)
{
    // Handle module loading failure
}

◆ load() [2/2]

virtual Result pxl::Job::load ( const pxl::Module * module )

pure virtual

Loads a module into this job.

Parameters

module Pointer to the Module object to load.

Returns: Result indicating the success or failure of the operation.

Example usage:

auto module = pxl::createModule("test.mubin");
auto job = context->createJob();
auto result = job->load(module);
if (result != pxl::Result::Success)
{
    // Handle module loading failure
}

◆ operator=()

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

delete

Deleted copy assignment operator.

◆ reload() [1/2]

virtual Result pxl::Job::reload ( const char * muBinaryPath )

pure virtual

Swaps the loaded binary on this job, keeping its Sub set.

Parameters

muBinaryPath Path to the new binary file.

Returns: Result indicating the success or failure of the operation.

Reuse a job's reserved Subs for a different kernel without recreating it. Every Map built from this job is invalidated: the Map objects stay valid (the caller still destroys them) but every operation on them returns Failure, so rebuild the Maps after reload. Not safe to interleave with buildMap()/destroyMap()/execute()/destroyJob() on the same job; serialize externally.

If reload fails, the job is left unloaded but keeps its Subs; recover by retrying load() or reload().

◆ reload() [2/2]

virtual Result pxl::Job::reload ( const pxl::Module * module )

pure virtual

Swaps the loaded module on this job, keeping its Sub set.

Parameters

module Pointer to the new Module object to load.

Returns: Result indicating the success or failure of the operation.

Same semantics as reload(const char*): all Maps built from this job are invalidated and must be rebuilt.

◆ remapMemory()

virtual Result pxl::Job::remapMemory	(	void *	ptr,
		uintptr_t	virtualAddr
	)

pure virtual

Makes this Job's private memory reachable by the kernel at a chosen address.

Maps ptr (from Job::allocateMemory) so the kernel reaches it at virtualAddr — e.g. kernel stack/heap at a linker-fixed address. virtualAddr must be aligned to DeviceAttr::MappingGranularity (query via Context::getAttribute) and is device-only: do not dereference it on the host (use ptr). Undo with unmapMemory. A remapped address is rejected by setInput/setOutput: this is device-side scratch (kernel stack/heap), not an I/O buffer. The host may seed it — after writing ptr, call pxl::flushHostCache(ptr, bytesWritten) before the kernel reads it via virtualAddr; flush the range actually written, not the granularity-aligned span the mapping covers. Reading kernel-written data back through ptr is not part of the contract: no automatic output sync runs on a remapped mapping, so return host-visible results through setOutput memory. virtualAddr must stay clear of the addresses PXL hands out itself. It is checked against live mappings here, but if a later allocation takes it this mapping is retired (logged, and unmapMemory then reports NotFound); the Job's other mappings and its memory access are unaffected.

Parameters

ptr	Job-private memory from this Job's allocateMemory.
virtualAddr	Device address to map it at (granularity aligned).

Returns: Result::Success, or Result::InvalidArgument on a bad ptr/address or a device without device-managed V2P (InfiniteMemory / non-CXL).

◆ subIdList()

virtual const std::vector<uint32_t> pxl::Job::subIdList ( ) const

pure virtual

Returns the list of sub IDs associated with this job.

Returns: Vector containing the IDs of the sub associated with this job.

◆ unmapMemory()

virtual Result pxl::Job::unmapMemory ( uintptr_t virtualAddr )

pure virtual

Removes a remapMemory mapping. The backing is not freed.

Releasing the backing or destroying the Job drops the mapping too, so NotFound can also mean it was already cleaned up that way.

Returns: Result::Success, or Result::NotFound if this Job did not map it.

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

job.hpp

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ AsyncCallback

Constructor & Destructor Documentation

◆ Job() [1/2]

◆ Job() [2/2]

◆ ~Job()

Member Function Documentation

◆ allocateMemory() [1/2]

◆ allocateMemory() [2/2]

◆ buildMap() [1/3]

◆ buildMap() [2/3]

◆ buildMap() [3/3]

◆ destroyMap()

◆ deviceId()

◆ id()

◆ isLoaded()

◆ load() [1/2]

◆ load() [2/2]

◆ operator=()

◆ reload() [1/2]

◆ reload() [2/2]

◆ remapMemory()

◆ subIdList()

◆ unmapMemory()