class ara::com::SamplePtr

The template class encapsulates exclusive ownership of received event samples modeled after std::unique_ptr and grants the application direct, immutable read access to buffers of the middleware (EXP ARAComAPI §5.3.5.4). Instances are passed when querying new samples, can be transferred exclusively via move semantics, and keep the memory space allocated ([SWS_CM_11537]). Only the destruction of the pointer or an explicit nulling releases the buffer slot again. Validity requires that the event remains subscribed and the associated proxy exists.

more ›

Context

The template class ara::com::SamplePtr represents the central access and ownership model for received event data (event samples) in the Adaptive Platform (EXP ARAComAPI §5.3.5.4). Semantically, the class models an exclusive smart pointer after the pattern of std::unique_ptr (EXP ARAComAPI §5.3.5.4). The primary interaction partners are the application layer, the receiving event or proxy object, and the underlying communication middleware ara::com, which manages the buffer resources (EXP ARAComAPI, p. 44, EXP ARAComAPI, p. 50).

The concept explicitly follows a reference-based zero-copy approach: instead of passing event data to the application by value copy, ara::com forwards pointers or references to central communication buffers (EXP ARAComAPI, p. 50). In typical 1:N distribution scenarios, local event caches can thus be served purely via reference updates, minimizing memory overhead and latency (EXP ARAComAPI, p. 50). Access to the payload is conceptually strictly read-only: upon provision, SamplePtr is always instantiated with a constant payload type (ara::com::SamplePtr<SampleType const>), whereby all access operators are implicitly const (EXP ARAComAPI, p. 39, EXP ARAComAPI, p. 44, [SWS_CM_00701]).

Lifecycle

Instances of SamplePtr can be created as empty pointers via the default constructor or with nullptr ([SWS_CM_11534], [SWS_CM_11535]). Valid instances populated with payload, by contrast, originate within the middleware during deserialization of events into buffer slots and are passed to an application-side callable in the context of GetNewSamples() (EXP ARAComAPI, p. 44).

With the handoff, a complete ownership transfer to the application takes place (EXP ARAComAPI §5.3.5.4). To guarantee exclusivity of ownership, the copy constructor and copy assignment operator are deleted ([SWS_CM_11536], [SWS_CM_11538]). Transfer of the managed memory slot is possible exclusively via move construction or move assignment ([SWS_CM_11537], [SWS_CM_11540]), whereas Swap() allows swapping the contents of two pointers ([SWS_CM_11544]).

As long as a SamplePtr instance exists and holds the sample, the middleware cannot reclaim or overwrite the occupied memory space (EXP ARAComAPI §5.3.5.4). The middleware slot is released only when the lifetime of the SamplePtr ends upon calling the destructor ([SWS_CM_11547]) or when the pointer is explicitly cleared by means of Reset(nullptr) or assignment of nullptr ([SWS_CM_11539], [SWS_CM_11545]).

State diagram: Lifecycle phases and ownership transitions of a SamplePtr. Sources: [SWS_CM_11534], [SWS_CM_11537], [SWS_CM_11545], [SWS_CM_11547], EXP ARAComAPI §5.3.5.4.

Usage Path

The typical data access workflow is divided into the following steps:

1. Trigger sample query: The application calls GetNewSamples() on the event proxy, passing a suitable callback function with signature void(ara::com::SamplePtr<SampleType const>) as well as an upper limit for the number of samples to retrieve (EXP ARAComAPI, p. 44).
2. Handoff to callback: If new data is available and the buffer quota is not exhausted, the middleware deserializes the sample and passes the new SamplePtr instance to the callback (EXP ARAComAPI, p. 44).
3. Check End-to-End status: Via GetProfileCheckStatus(), the application can query the result of the E2E protection check for the data packet at hand ([SWS_CM_90420]).
4. Read data: Application logic accesses the managed object in a read-only manner via operator* ([SWS_CM_11541]), operator-> ([SWS_CM_11542]), or the Get() method ([SWS_CM_11546]).
5. Further processing or release: If the sample is to be persisted beyond the callback, the application moves the pointer into its own storage structures via move construction ([SWS_CM_11537]). If the pointer remains in the scope of the callback, it is automatically destroyed upon leaving ([SWS_CM_11547]), which immediately frees the slot in the middleware (EXP ARAComAPI §5.3.5.4).

Sequence diagram: Interaction sequence for GetNewSamples() with ownership transfer and buffer release. Sources: [SWS_CM_11541], [SWS_CM_11547], [SWS_CM_90420], EXP ARAComAPI, p. 44, EXP ARAComAPI §5.3.5.4.

Error Scenarios

When using SamplePtr, specific boundary conditions and sources of errors must be observed:

• Exhaustion of the buffer quota: On each call to GetNewSamples(), the middleware checks whether the number of samples currently held by the application exceeds the quota previously guaranteed during the call to Subscribe(). If the quota is exceeded, GetNewSamples() refuses to deliver further samples and returns a ara::core::ErrorCode instead (EXP ARAComAPI, p. 44, EXP ARAComAPI, p. 45).
• Invalidity due to subscription loss or proxy destruction: SamplePtr behaves deterministically like a std::unique_ptr only as long as the underlying event remains subscribed and the parent proxy instance exists. Retaining pointers beyond the end of the subscription or the destruction of the proxy is considered a violation of preconditions.
• Pointer validity and null state: Via operator bool(), the occupancy state of the pointer can be evaluated ([SWS_CM_11543]). Dereferencing an empty pointer via operator* or operator-> leads to undefined behavior. All access and modification methods are declared as noexcept ([SWS_CM_11541], [SWS_CM_11542], [SWS_CM_11546]).
• E2E validation errors: A validly received pointer does not necessarily guarantee error-free transmission data; via the return value of GetProfileCheckStatus(), the application must verify whether End-to-End protection signals data corruption or transmission delays ([SWS_CM_90420]).