Context

Fully qualified name: cupva::Context

Defined in cupva_host.hpp

class Context : public cupva::DynamicStorage<impl::Context>

Context holds all resources required by other CUPVA APIs.

The context abstracts the PVA hardware. The current context is stored in thread-local storage. All CUPVA API calls are implicitly using the current context of the calling thread, and all CUPVA objects created are implicitly owned by the current context.

Many CUPVA objects implicitly capture a reference to the Context which is active at the time of object creation. Users must not call object APIs when the cupva::Context current to the calling thread is different to the cupva::Context which was current at the time the object was created.

• Maturity: GA

Public Functions

Context() noexcept

Creates a new Context object.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: No

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Pre:

None

Context(Context &&obj) noexcept

Move constructor.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Pre:

None

Context &operator=(Context &&obj) & noexcept

Move assignment.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Pre:

None

Context(Context const&) = delete

Context &operator=(Context const&) & = delete

void finalize()

Destroy the resources created by the object.

This method is exposed to allow fine-grained control over error handling.

During destruction of the object, this method will be called but the destructor must not propagate exceptions. To handle exceptions, manually invoke this method prior to object destruction.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: No

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Throws:

• cupva::Exception(DriverAPIError) – The PVA driver returned an unexpected error

• cupva::Exception(NotAllowedInOperationalState) – if called when NVIDIA DRIVE OS VM state is “Operational”

• cupva::Exception(InvalidState) – if called without freeing all allocations

Pre:

None

~Context() noexcept

Destroy the Context object.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: No

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Pre:

None

Public Static Functions

static Context Create(uint32_t const engineMask = ENGINE_MASK_ALL)

Construct a new Context object.

The context automatically becomes current for the calling thread.

The context abstracts the PVA hardware. The current context is stored in thread-local storage. All CUPVA API calls are implicitly using the current context of the calling thread, and all CUPVA objects created are implicitly owned by the current context.

If a calling thread does not have a current context when an API call requiring a Context is made, a default context is used. The default Context is process-wide. The system has a limit on the number of Contexts created across all processes, which includes default Contexts. On currently supported platforms, this limit is 4. If the limit is exceeded, this API will fail with a DriverAPIError.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: Yes

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: No

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Parameters:

engineMask – Bitmask indicating which engines to enable in the context. See GetHardwareInfo() to query the number of available engines in the system.

Throws:

• cupva::Exception(DriverAPIError) – The PVA driver returned an error

• cupva::Exception(InternalError) – Failed to initialize internal state

• cupva::Exception(NotAllowedInOperationalState) – if called when NVIDIA DRIVE OS VM state is “Operational”

• std::bad_alloc – if memory could not be allocated

Pre:

None

static void SetCurrent(impl::Context *const ctx) noexcept

Sets the context for the calling thread.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: Yes

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Parameters:

ctx – A pointer to the context instance which current for the calling thread. Passing null causes the thread to use the default application context.

Pre:

None

static impl::Context *GetCurrent() noexcept

Gets the pointer to the context instance used.

If there is no current context, returns nullptr.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: Yes

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Returns:

A pointer to the context instance used by calling thread.

Pre:

None

Public Static Attributes

static constexpr uint32_t ENGINE_MASK_ALL = {cupva::config::ENGINE_MASK_ALL}

Engine mask for Context::Create() to enable all available PVA engines.