SyncObj

Fully qualified name: cupva::SyncObj

Defined in src/host/cpp_api/include/cupva_host.hpp

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

The synchronization object.

SyncObj is used to store data which can be used to populate a cupva::Fence. Exact data stored depends on how the SyncObj is created and its type. Can optionally be made to store a timestamp buffer to record timestamps for fences.

Operations that asynchronously write to a single SyncObj may be susceptible to race conditions. In particular, cupva::CmdRequestFence commands associated with cupva::Fence instances that share the same SyncObj and are submitted to multiple cupva::Stream instances, or with cupva::OrderType::OUT_OF_ORDER, cannot guarantee the order in which they write to the SyncObj data. This also applies to operations through external APIs that would write to an NvSciSyncObj or NvSciFence tied to a cupva::SyncObj though cupva::nvsci::Import or cupva::nvsci::Export. Measures must be taken to ensure proper ordering of writes. For example, the use of cupva::CmdBarrier, cupva::CmdWaitOnFences, cupva::Fence::wait(), etc. The use of multiple independent SyncObj is also an effective design to avoid race conditions.

A single SyncObj can support up to 512 fences at any given time. User must ensure that the concurrent number of fences associated with a SyncObj is less than 512.

Public Functions

SyncObj() noexcept

Construct an empty SyncObj.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

SyncObj(SyncObj const&) = delete

SyncObj &operator=(SyncObj const&) & = delete

SyncObj(SyncObj &&obj) noexcept

Move construct a SyncObj.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: No

  • Runtime: Yes

  • De-Init: No

SyncObj &operator=(SyncObj &&obj) & noexcept

Move assign a SyncObj.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: No

  • Runtime: Yes

  • De-Init: No

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

  • Thread-safe: No

• API group

  • Init: No

  • Runtime: No

  • De-Init: Yes

Throws:

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

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

~SyncObj() noexcept

Destroy the SyncObj.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: No

  • Runtime: No

  • De-Init: Yes

Public Static Functions

static SyncObj Create(

bool const isTimeStamp = false,

SyncClientType const clientType = SyncClientType::SIGNALER_WAITER,

SyncWaitMode const waitMode = SyncWaitMode::YIELD,

)

Construct a new SyncObj.

Usage considerations

• Allowed context for the API call

  • Thread-safe: Yes

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• isTimeStamp – The flag to turn on/off the time-stamp in the SyncObj.

• clientType – The synchronization client type.

• waitMode – The sync object wait mode.

Throws:

• std::bad_alloc – Allocating the SyncObj object failed.

• cupva::Exception(InvalidArgument) – The SyncClientType is invalid.

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

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

Returns:

SyncObj The newly constructed SyncObj