class ara::shwa::Id

The template class ara::shwa::Id encapsulates multidimensional identifiers in module shwa and enforces controlled instantiation via static factory methods such as Create [AP_SWS_SHWA_00707]. As a copyable and movable value object, it allows access to individual dimension indices by means of Get and Set [AP_SWS_SHWA_00710]. Since read and write accesses as well as multidimensional factories are not thread-safe, the necessary synchronization is the responsibility of the calling application.

more ›

Context

Within module shwa, the template class ara::shwa::Id represents a multidimensional identification or indexing for shared memory or hardware accelerator structures. It encapsulates coordinates or dimension indices that can be instantiated via static factory methods and subsequently queried or modified. The class is declared as final and parameterizes the number of dimensions via the template parameter Dimensions with the default value 1. Typical interaction partners are application components that need to address structured accesses to accelerator buffers or memory resources. In this context, an instance object of ara::shwa::Id serves as a compact value object for dimension-related addressing.

Lifecycle

Instantiation of ara::shwa::Id is subject to strict rules: the default constructor is explicitly deleted [AP_SWS_SHWA_00702]. Direct, uninitialized object creation is thus excluded. Instead, creation takes place in a controlled manner via static factory functions Create, which return the object encapsulated in a ara::core::Result [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. Depending on the required dimensionality, overloads are available for one dimension [AP_SWS_SHWA_00707], two dimensions [AP_SWS_SHWA_00708], or three dimensions [AP_SWS_SHWA_00709].

Regarding ownership semantics, ara::shwa::Id behaves like a regular value object. It implements both the copy constructor [AP_SWS_SHWA_00703] and the copy assignment operator [AP_SWS_SHWA_00704] as defaulted (default) and exception safe (noexcept). Likewise, the move constructor [AP_SWS_SHWA_00705] and the move assignment operator [AP_SWS_SHWA_00706] are available with noexcept. Instances can thus be efficiently stored in containers, passed by value, or moved between program parts. Special consideration is required for thread safety: while the one-dimensional factory method is specified as thread-safe [AP_SWS_SHWA_00707], the two- and three-dimensional factory methods are explicitly designated as not thread-safe [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. In the case of parallel initializations of multidimensional indices, callers must provide appropriate synchronization measures.

Usage Path

The typical usage flow comprises controlled instantiation via the appropriate factory call, verification of the Result object, as well as subsequent read and write operations on the individual dimensions. First, the application calls Create with the desired dimension boundaries or index values. After successful return of a ara::core::Result<Id>, the value contained therein is unpacked. Via the const method Get, the index value for a specific dimension can be queried [AP_SWS_SHWA_00710]. If needed, the value of a specific dimension can subsequently be modified via Set [AP_SWS_SHWA_00711]. Both methods (Get and Set) are classified as not thread-safe; concurrent accesses to the same instance from multiple threads must be synchronized externally.

Sequence diagram: Typical flow of factory creation, value query, and subsequent modification of an Id object. Sources: [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00710], [AP_SWS_SHWA_00711]

Error Scenarios

Runtime errors can occur during creation via the static Create methods. If instantiation fails, the factory method returns a ara::core::Result containing the error code ShwaErrorCode::kRuntime [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. Callers must therefore mandatorily check the return value by means of HasValue() before the instance is accessed. All Create functions guarantee rollback semantics and are declared as exception safe (noexcept).

During ongoing operation with the methods Get and Set, care must be taken that these are not exception safe according to the specification (not exception safe) and do not operate thread-safely [AP_SWS_SHWA_00710], [AP_SWS_SHWA_00711]. Interpretation: passing invalid dimension values outside the valid range of values is likely to lead to undefined behavior or exceptions, since no separate error codes are defined for faulty parameters to these methods. Question Q-6983f5f27702e6e8 (open) Prior to calling, callers must ensure that the argument dimension lies within the valid boundaries of the instance.