pxl::Context Class Reference

An execution abstraction of a Device object. More...

#include <context.hpp>

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

Public Member Functions
	Context (const Context &)=delete
	Deleted copy constructor. More...
Context &	operator= (const Context &)=delete
	Deleted copy assignment operator. More...
virtual Job *	createJob ()=0
	Creates a new job with the default number of sub. More...
virtual Job *	createJob (const uint32_t numSub)=0
	Creates a new job with the specified number of sub. More...
virtual Result	createJobForceAsync (const uint32_t numSub, const AsyncCallback &callback, void *arg, uint32_t timeout=0)=0
	Creates a new job with the specified number of sub asynchronously. More...
virtual Result	destroyJob (Job *job)=0
	Destroys the specified job. More...
virtual void *	memAlloc (const size_t size)=0
	Allocates memory on the device. More...
virtual void *	memCalloc (const size_t num, const size_t size)=0
	Allocates zero-initialized memory on the device. More...
virtual void	memFree (const void *ptr)=0
	Frees previously allocated memory on the device. More...
virtual uint32_t	deviceId () const =0
	Returns the ID of the device. More...
virtual uint32_t	availableSubCount () const =0
	Returns the available number of Sub. More...
virtual uint64_t	availableMemSize () const =0
	Returns the available memory size of the device. More...
virtual Result	getAttribute (DeviceAttr attr, uint64_t &value) const =0
	Returns information about the device attribute. More...
virtual void *	memRealloc (void *ptr, const size_t size)=0
	Resizes previously allocated device memory. More...

Protected Member Functions
	Context ()=default
virtual	~Context ()=default

Detailed Description

An execution abstraction of a Device object.

The Context class provides an execution abstraction for a specific device, identified by its ID. It offers functionality for:

• Managing computational resources (Sub) by creating and destroying Jobs.
• Managing device memory (alloc, free)
• Transferring data between host and device
• Querying device resources and configuration.

Definition at line 26 of file context.hpp.

Member Typedef Documentation

AsyncCallback

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

Callback function type for job creation.

Parameters

job	Pointer to the created job.
arg	Argument to be passed to the callback function.

This callback is called when a job is created.

Definition at line 37 of file context.hpp.

Constructor & Destructor Documentation

Context() [1/2]

pxl::Context::Context ( const Context &  )

delete

Deleted copy constructor.

Context() [2/2]

pxl::Context::Context ( )

protecteddefault

~Context()

virtual pxl::Context::~Context ( )

protectedvirtualdefault

Member Function Documentation

availableMemSize()

virtual uint64_t pxl::Context::availableMemSize ( ) const

pure virtual

Returns the available memory size of the device.

Returns

Available memory size in bytes.

availableSubCount()

virtual uint32_t pxl::Context::availableSubCount ( ) const

pure virtual

Returns the available number of Sub.

Returns

Available number of Sub.

createJob() [1/2]

virtual Job* pxl::Context::createJob ( )

pure virtual

Creates a new job with the default number of sub.

Returns

Pointer to the created job, or nullptr if creation fails.

Each Job owns a private default stream allocated from the per-process stream pool. Returns nullptr when that pool is exhausted, so the effective concurrent-Job ceiling is shared with user-created Streams.

Example usage:

auto job = context->createJob();
if (!job)
{
   // Handle job creation failure
}

createJob() [2/2]

virtual Job* pxl::Context::createJob ( const uint32_t  numSub )

pure virtual

Creates a new job with the specified number of sub.

Parameters

numSub

Number of Sub to assign to the job.

Returns

Pointer to the created job, or nullptr if creation fails (including stream-pool exhaustion — see createJob()).

Example usage:

uint32_t numSub = 2;
auto job = context->createJob(numSub);
if (!job)
{
   // Handle job creation failure
}

createJobForceAsync()

virtual Result pxl::Context::createJobForceAsync ( const uint32_t  numSub, const AsyncCallback &  callback, void *  arg, uint32_t  timeout = 0  )

pure virtual

Creates a new job with the specified number of sub asynchronously.

Parameters

numSub	Number of sub to assign to the job.
callback	Callback function to be called when the job creation is complete.
arg	Argument to be passed to the callback function.
timeout	Timeout value for creation operation.

Returns

Result indicating the success or failure of the operation. Returns Result::Failure when the per-process stream pool is exhausted (see createJob()).

If the callback throws, the exception is caught and logged on the invoking thread rather than propagated beyond the callback.

Warning

The completion runs asynchronously. Do not destroy the owning Context while a creation is still in flight: a Job handed to the callback during Context teardown may already be scheduled for destruction.

Example usage:

Job* job = nullptr;
bool done = false;
auto callback = [&](Job* job_, void* arg) {
   job = job_;
   done = true;
};
 
uint32_t numSub = 2;
auto result = context->createJobForceAsync(numSub, callback, arg, timeout);
if (result != pxl::Result::Success)
{
    // Handle job creation failure
}
 
while (!done)
{
   // Wait for job creation to complete
}
 
// Check if job is created successfully

destroyJob()

virtual Result pxl::Context::destroyJob ( Job *  job )

pure virtual

Destroys the specified job.

Parameters

job	Pointer to the job to be destroyed.

Returns

Result indicating the success or failure of the operation.

This function synchronously drains every Map built from the job (waiting for any in-flight map executions) before freeing it.

When called from a completion, error, or message callback for one of this Job's Maps, this function cannot drain the Job because the callback itself is part of the outstanding work. In that case, it returns Result::Cancelled and leaves the Job valid. Retry from a thread that can wait after the callback returns. Unrelated callbacks are not subject to this restriction; for example, a createJobForceAsync() callback can destroy the Job it just received.

Warning

Destroying the same Job concurrently from multiple threads is not supported; serialize destroyJob() for a given Job externally. A racing destroyJob() on the same Job returns Failure and leaves the Job valid; retry after the in-progress teardown completes.

Example usage:

auto job = context->createJob();
// ... use job, enqueue async work ...
auto result = context->destroyJob(job);
if (result != pxl::Result::Success)
{
   // Handle job destruction failure
}

deviceId()

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

pure virtual

Returns the ID of the device.

Returns

The device ID.

Example usage:

auto deviceId = context->deviceId();

getAttribute()

virtual Result pxl::Context::getAttribute ( DeviceAttr  attr, uint64_t &  value  ) const

pure virtual

Returns information about the device attribute.

Parameters

attr	Device attribute to query.
value	Reference to store the attribute value.

Returns

Result indicating the success or failure of the operation.

Example usage:

uint64_t value;
auto result = context->getAttribute(pxl::DeviceAttr::CxlMemoryCapacity, value);
if (result == pxl::Result::Success)
{
    // Use the value
}

memAlloc()

virtual void* pxl::Context::memAlloc ( const size_t  size )

pure virtual

Allocates memory on the device.

Parameters

size	Size of the memory to allocate.

Returns

Pointer to the allocated memory.

Example usage:

auto ptr = context->memAlloc(size);
if (!ptr)
{
    // Handle allocation failure
}

memCalloc()

virtual void* pxl::Context::memCalloc ( const size_t  num, const size_t  size  )

pure virtual

Allocates zero-initialized memory on the device.

This function allocates an array of num elements, each of size size, and initializes all bytes in the allocated storage to zero.

Parameters

num	Number of elements to allocate.
size	Size of each element.

Returns

Pointer to the allocated and zero-initialized memory.

Example usage:

auto ptr = context->memCalloc(count, sizeof(int));
if (!ptr)
{
    // Handle allocation failure
}

memFree()

virtual void pxl::Context::memFree ( const void *  ptr )

pure virtual

Frees previously allocated memory on the device.

Parameters

ptr	Pointer to the memory to free.

Example usage:

auto ptr = context->memAlloc(size);
if (!ptr)
{
    // Handle allocation failure
}
context->memFree(ptr);

memRealloc()

virtual void* pxl::Context::memRealloc ( void *  ptr, const size_t  size  )

pure virtual

Resizes previously allocated device memory.

Mirrors C realloc: tries an in-place resize, otherwise relocates with a copy. memRealloc(nullptr, size) allocates; memRealloc(ptr, 0) frees and returns nullptr. On failure the original pointer is left intact.

Declared last among the virtuals on purpose: appending it keeps the vtable slots of all pre-existing methods stable, so a binary compiled against an older Context layout is not silently misdirected.

Parameters

ptr	Pointer to the memory to resize (may be nullptr).
size	New size in bytes.

Returns

The (possibly new) pointer, or nullptr on failure / zero-size free.

Example usage:

auto ptr = context->memAlloc(size);
ptr = context->memRealloc(ptr, size * 2);

operator=()

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

delete

Deleted copy assignment operator.

---

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

• context.hpp