class ara::per::UniqueHandle

The class template ara::per::UniqueHandle manages exclusive ownership of file accessor objects of AUTOSAR Persistency within the scope of strict move-only semantics. After receipt via file access functions, the instance must mandatorily be checked for validity by means of operator bool() prior to any usage [SWS_PER_00371]. Calling other operators on an empty or transferred handle leads to undefined behavior [SWS_PER_00399]. All operations are declared as noexcept, where read accesses are thread-safe, whereas modifying operations are not.

more ›

Context

The class template ara::per::UniqueHandle serves as a type-safe access handle to resource objects of AUTOSAR Adaptive Persistency, namely ReadAccessor or ReadWriteAccessor. It is provided as the return value of the functions OpenFileReadOnly(), OpenFileWriteOnly(), and OpenFileReadWrite(), encapsulating exclusive ownership of the opened file access interface.

Lifecycle

The class implements strict move-only semantics (unique ownership). To prevent accidental duplication of access or shared ownership, both the copy constructor [SWS_PER_00373] and the copy assignment operator [SWS_PER_00374] are defined as deleted (delete). Ownership rights can exclusively be transferred by moving: when calling the move constructor [SWS_PER_00371] or the move assignment [SWS_PER_00372], the passed source object is invalidated and may not be used thereafter.

A UniqueHandle is at any time either in a valid state (representing a valid object of the parameterized class) or in an empty or invalidated state, as present after a move transfer [SWS_PER_00399]. Upon termination of the scope, the destructor [SWS_PER_00569] is executed. Presumably, destruction of a valid handle automatically closes or cleans up the encapsulated access resource. Question Q-e7f12aa0d7c5548d (open)

State diagram: Lifecycle and state transitions of a UniqueHandle between valid and empty states. Sources: [SWS_PER_00371], [SWS_PER_00372], [SWS_PER_00399], [SWS_PER_00569]

Usage Path

Typical usage of UniqueHandle follows a defined sequence of steps:

1. Acquiring the handle: The application receives the handle as the result of a file access call such as OpenFileReadOnly(), OpenFileWriteOnly(), or OpenFileReadWrite().
2. State check: Prior to any further operation, the status of the instance must mandatorily be verified by means of operator bool() [SWS_PER_00371], [SWS_PER_00372]. The operator returns true if a valid object is present, and false if the handle is empty [SWS_PER_00399].
3. Accessing the encapsulated object: If the status is valid, methods and data of the target are accessed via the arrow operators operator-> (non-constant [SWS_PER_00360] or constant [SWS_PER_00361]) or via dereferencing by means of operator* (non-constant [SWS_PER_00400] or constant [SWS_PER_00401]).
4. Ownership transfer or destruction: If needed, the handle can be transferred to another component via std::move [SWS_PER_00371] or is automatically destroyed at the end of its lifetime [SWS_PER_00569].

Error Scenarios

A central error scenario is access to an empty or transferred handle: using operators other than operator bool() on an empty handle leads to undefined behavior according to the specification [SWS_PER_00399]. Prior to any dereferencing, a check is therefore mandatory [SWS_PER_00371], [SWS_PER_00372].

Regarding exception safety and concurrency, the following specification details apply:

• Exception safety: All methods and operators are provided with noexcept and specified as exception safe ([SWS_PER_00371], [SWS_PER_00372], [SWS_PER_00399], [SWS_PER_00400], [SWS_PER_00401], [SWS_PER_00360], [SWS_PER_00361], [SWS_PER_00569]).
• Thread safety: The read operators operator* [SWS_PER_00400], [SWS_PER_00401], operator-> [SWS_PER_00360], [SWS_PER_00361], as well as operator bool() [SWS_PER_00399] are thread-safe. In contrast, modifying actions such as the move assignment [SWS_PER_00372] and destruction via the destructor [SWS_PER_00569] are explicitly not thread-safe and require external synchronization in the case of concurrent access.