class ara::per::SharedHandle

The template class ara::per::SharedHandle serves as a smart-pointer abstraction for file and key-value storages to enable thread-safe access across thread boundaries. After obtaining it via factory functions, the validity state of the handle must be checked via operator bool() [SWS_PER_00398], as calling other operators on an empty handle or one invalidated by move operations results in undefined behavior. While dereferencing to the encapsulated object is thread-safe, assignments and destruction of the handle [SWS_PER_00568] on the same instance require external synchronization.

more ›

Context

The template class ara::per::SharedHandle represents a smart-pointer abstraction for persistent storage resources in the per (Persistency) module of the AUTOSAR Adaptive Platform. It serves as the standardized return type of the factory functions OpenFileStorage() and OpenKeyValueStorage(). The main responsibility of the class is to coordinate access to file and key-value storages across thread boundaries and to provide the necessary encapsulation to enable a thread-safe implementation of storage opening and access routines. Interaction partners are application-side threads of execution, persistency management, and the respective encapsulated storage resource T.

Lifecycle

A SharedHandle is typically created when opening a storage instance via the factory interfaces of per. Through the copy constructor [SWS_PER_00369] as well as the copy assignment operator [SWS_PER_00370], the handle can be duplicated, whereby multiple handle instances obtain shared access to the same target object. If a handle is transferred by means of the move constructor [SWS_PER_00367] or move assignment [SWS_PER_00368], the source handle transitions to an invalidated state and may no longer be used for storage accesses.

The current status of the handle is determined by the explicit conversion operator operator bool() [SWS_PER_00398]: it returns true if a valid storage instance is referenced, and false if the handle is empty. Release of the handle resources occurs via the destructor ~SharedHandle() [SWS_PER_00568]. Interpretation: the underlying storage resource is likely to be released as soon as the last referencing SharedHandle is destroyed. Question Q-00a1798cf43e0ee6 (open)

With respect to concurrency, accesses to the encapsulated resource via operator* ([SWS_PER_00402], [SWS_PER_00403]) and operator-> ([SWS_PER_00363], [SWS_PER_00364]) as well as the status query via operator bool() [SWS_PER_00398] are thread-safe. In contrast, assignment operations on the same handle ([SWS_PER_00368], [SWS_PER_00370]) and its destruction [SWS_PER_00568] are not thread-safe and require external synchronization in the case of shared handle usage.

State diagram: Lifecycle and state transitions of ara::per::SharedHandle between valid and empty states. Sources: [SWS_PER_00367], [SWS_PER_00368], [SWS_PER_00369], [SWS_PER_00370], [SWS_PER_00398], [SWS_PER_00568]

Usage Path

Typical usage of ara::per::SharedHandle comprises controlled retrieval, validation, and access to storage structures:

1. Obtaining the handle: The application calls OpenFileStorage() or OpenKeyValueStorage() and receives a SharedHandle<T>.
2. Validity check: Prior to each access, the application checks the state of the handle via operator bool() [SWS_PER_00398].
3. Resource access: Calling storage functions takes place by dereferencing using operator-> ([SWS_PER_00363], [SWS_PER_00364]) or operator* ([SWS_PER_00402], [SWS_PER_00403]).
4. Handover: If needed, the handle can be passed to other threads by copy ([SWS_PER_00369], [SWS_PER_00370]) or by move ([SWS_PER_00367], [SWS_PER_00368]).
5. End of lifecycle: Upon leaving scope, the destructor [SWS_PER_00568] tears down the handle.

Sequence diagram: Sequence of obtaining, validity checking, method invocation, and teardown of a SharedHandle. Sources: [SWS_PER_00363], [SWS_PER_00398], [SWS_PER_00568]

Error Scenarios

Critical error states occur primarily during invalid operations on empty or invalidated handles. According to [SWS_PER_00398], calling any operators other than operator bool() on an empty handle leads directly to undefined behavior. This particularly affects source handles after a move construction [SWS_PER_00367] or a move assignment [SWS_PER_00368], since these are invalidated and may not be used further.

To prevent undefined behavior, the specification mandatorily requires verifying the handle state via operator bool() prior to calling further operators ([SWS_PER_00367], [SWS_PER_00368]). All constructors, assignment operators, access operators, and the destructor are declared as noexcept and specified as exception safe ([SWS_PER_00367], [SWS_PER_00368], [SWS_PER_00369], [SWS_PER_00370], [SWS_PER_00363], [SWS_PER_00364], [SWS_PER_00402], [SWS_PER_00403], [SWS_PER_00398], [SWS_PER_00568]). An invalid state therefore does not trigger an exception, but must mandatorily be intercepted by the caller via the return value of operator bool().