class ara::core::Bitset::reference

The helper class ara::core::Bitset::reference acts as a proxy type for lvalue-like access to individual bits of a ara::core::Bitset. It enables the targeted modification of the referenced bit value, in particular its inversion via member function flip() according to [SWS_CORE_01712]. By declaring flip() as noexcept, the operation is guaranteed to be exception-safe [SWS_CORE_01712]. As an essential constraint, the proxy object, according to interpretation, remains valid only during the lifetime of the enclosing container.

more ›

Context

Within module core of the AUTOSAR Adaptive Platform, the nested helper class ara::core::Bitset::reference acts as a proxy object for accessing individual bits in a ara::core::Bitset. Since individual bits do not have an independent memory address in the C++ type system and thus cannot be represented directly as a native reference (bool&), reference implements the concept of std::bitset::reference from the C++ standard [bitset]. The class serves as an intermediary between the calling code and the internal bit storage of the container ara::core::Bitset. It allows developers to treat an individual bit syntactically and semantically like a modifiable reference by directly mapping operations on the proxy to the underlying bit in the bitset. An essential component of this interface is the member function flip() according to [SWS_CORE_01712], which provides a direct state inversion of the addressed bit.

Lifecycle

Instances of ara::core::Bitset::reference typically have a short-lived character. According to interpretation, creation does not occur as a free-standing object by the application developer, but is initiated internally by the non-const access mechanisms of the container ara::core::Bitset when an lvalue access to a specific bit position is requested. The created proxy object logically binds to the specific bit position and the underlying memory region of the container. The lifetime of the reference instance is thus strictly coupled to the existence of the enclosing Bitset object: If the referenced Bitset is destroyed or its memory becomes invalid, subsequent access via the proxy object presumably leads to undefined behavior (dangling reference). Question Q-44ce3478c9a2d987 (open) After completing operations such as bit inversion via flip() according to [SWS_CORE_01712], the temporary object is usually discarded immediately. Regarding concurrency, it should be noted that concurrent write accesses to different or identical bits of the same container via separate reference instances without external synchronization are presumably not thread-safe.

Usage Path

The primary use case of ara::core::Bitset::reference consists in the targeted querying and modification of individual bit values. In the typical sequence, a caller accesses a bit position in ara::core::Bitset via the subscript operator, returning a temporary reference object. Modifying operations can now be performed on this reference. Specifically for inverting the bit value, the class provides the member function flip(), which is specified according to [SWS_CORE_01712]. This method inverts the current state of the referenced bit (0 becomes 1, 1 becomes 0) and returns an lvalue reference to the proxy object itself (reference&). This allows chaining of further calls or direct further use of the modified result.

Sequence diagram: Typical sequence of bit inversion via the proxy object reference. Sources: [SWS_CORE_01712]

Error Scenarios

The class ara::core::Bitset::reference is characterized by a design geared toward robustness and performance. For the central member function flip(), the exception safety "exception safe" as well as the identifier [SWS_CORE_01712] are explicitly specified according to noexcept. This means that calling flip() is guaranteed not to throw any C++ exceptions. Error states or exception handling thus do not occur during this call; the precondition for error-free execution is the validity of the underlying reference to the container object.