class ara::rds::ReadDataResult

Structure ara::rds::ReadDataResult encapsulates the result of a read operation from a raw data stream of the AUTOSAR Adaptive Platform (AUTOSAR_AP_SWS_RawDataStream, p. 1). It is created by methods ReadData and provides the read binary data in buffer data together with the actual byte count numberOfBytes [SWS_RDS_11301]. Because the buffer is managed as std::unique_ptr, the structure presumably transfers exclusive ownership to the caller and precludes copying. Question (open) Errors are reported via the enclosing ara::core::Result, which is why the result must be validated before accessing the data.

more ›

Context

Class ara::rds::ReadDataResult acts in module rds (RawDataStream) of the AUTOSAR Adaptive Platform as a structured result container for data retrievals from data streams (AUTOSAR_AP_SWS_RawDataStream, p. 1). Its primary responsibility is to pass the raw data bytes read from a raw data stream together with the actually transferred byte count to the calling application. Stream instances that offer read methods ReadData, as well as the respective application component that evaluates the data stream and further processes the data [SWS_RDS_10486], [SWS_RDS_11322], act as interaction partners in the system network.

Lifecycle

Instances of ara::rds::ReadDataResult arise in the context of synchronous or time-limited read operations. Creation is initiated when a caller invokes method ReadData(std::size_t maxLength) [SWS_RDS_10486], [SWS_RDS_11322] or the overload with timeout monitoring ReadData(std::size_t maxLength, std::chrono::milliseconds timeout) [SWS_RDS_11309], [SWS_RDS_11323].

Ownership and memory lifecycle are decisively determined by the contained data member data, which is declared as std::unique_ptr<ara::core::Byte[]> [SWS_RDS_11301]. According to common C++ interpretation, this means that ReadDataResult is presumably designed as a move-only type and thus cannot be copied, but only moved. Question Q-fe4b113c5852b5aa (open) Upon receiving the object, the calling program assumes sole ownership of the allocated data buffer. Destruction of the instance automatically leads to freeing the reserved heap memory of the byte array, unless the pointer was previously explicitly extracted from the object. Regarding concurrency, no internal synchronization exists; concurrent access to an instance from multiple threads without external locks is not thread-safe.

Usage Path

The regular flow for using ara::rds::ReadDataResult is divided into the following substeps:

• Requesting the read operation: The application calls ReadData on the stream with the maximum requested amount of data maxLength [SWS_RDS_10486], [SWS_RDS_11322], optionally supplemented by a timeout value [SWS_RDS_11309], [SWS_RDS_11323].
• Return of the result container: The stream reads the binary data from the channel and, upon success, returns a populated object of type ara::core::Result<ReadDataResult> (AUTOSAR_AP_SWS_RawDataStream, p. 1).
• Size determination: The application reads field numberOfBytes from [SWS_RDS_11302]. Interpretation: This value is likely to indicate the amount of bytes actually provided in the buffer, which can be less than or equal to the requested maxLength. Question Q-12bde8c67452a632 (open)
• Data processing: Buffer data is dereferenced [SWS_RDS_11301] in order to process the received bytes or transfer them into application-owned structures via move semantics.

Sequence diagram: Typical sequence of a read operation with receipt and evaluation of ReadDataResult. Sources: [SWS_RDS_10486], [SWS_RDS_11301], [SWS_RDS_11302], AUTOSAR_AP_SWS_RawDataStream, p. 1

Error Scenarios

The methods for creating a ReadDataResult are declared with noexcept [SWS_RDS_10486], [SWS_RDS_11309], [SWS_RDS_11322], [SWS_RDS_11323], which is why no C++ exceptions are thrown in the event of an error. Instead, error handling is handled entirely via the return object ara::core::Result (AUTOSAR_AP_SWS_RawDataStream, p. 1).

Typical error scenarios include stream interruptions, invalid read requests, or the expiration of the waiting time for timed read calls [SWS_RDS_11309], [SWS_RDS_11323]. Interpretation: In such failures, ara::core::Result presumably does not contain a valid ReadDataResult object, but rather a corresponding error code. Question Q-f3f971c4789fe8e7 (open) For the application, as a precondition for accessing data [SWS_RDS_11301] and numberOfBytes [SWS_RDS_11302], this means always first checking the success state of the parent Result object to prevent access to uninitialized pointers or invalid memory areas.