класс ara::com::SamplePtr

Шаблонный класс инкапсулирует монопольное владение принятыми выборками (samples) событий по образцу std::unique_ptr и предоставляет приложению прямой неизменяемый доступ для чтения к буферам промежуточного ПО (EXP ARAComAPI §5.3.5.4). Экземпляры передаются при запросе новых выборок, допускают передачу исключительно по семантике перемещения (move-semantics) и удерживают занятое пространство памяти ([SWS_CM_11537]). Только уничтожение указателя или его явное обнуление освобождает слот буфера. Действительность предполагает, что событие остается подписанным, а соответствующий прокси существует.

больше ›

Контекст

Шаблонный класс ara::com::SamplePtr представляет собой центральную модель доступа и владения для принятых данных событий (Event Samples) в Adaptive Platform (EXP ARAComAPI §5.3.5.4). Семантически данный класс воспроизводит эксклюзивный «умный» указатель по образцу std::unique_ptr (EXP ARAComAPI §5.3.5.4). Основными партнерами по взаимодействию являются уровень приложения, принимающий объект события или прокси, а также нижележащее коммуникационное промежуточное ПО ara::com, управляющее буферными ресурсами (EXP ARAComAPI, с. 44, EXP ARAComAPI, с. 50).

Концепция целенаправленно использует подход с нулевым копированием (zero-copy) на основе ссылок: вместо передачи данных событий приложению путем копирования по значению ara::com передает указатели или ссылки на центральные коммуникационные буферы (EXP ARAComAPI, с. 50). В типичных сценариях распределения 1:N локальные кэши событий благодаря этому могут обслуживаться исключительно путем обновления ссылок, что минимизирует затраты памяти и задержку (EXP ARAComAPI, с. 50). Доступ к полезным данным концептуально рассчитан строго на чтение: при предоставлении SamplePtr всегда инстанцируется с константным типом полезных данных (ara::com::SamplePtr<SampleType const>), вследствие чего все операторы доступа являются неявно константными (EXP ARAComAPI, с. 39, EXP ARAComAPI, с. 44, [SWS_CM_00701]).

Жизненный цикл

Экземпляры SamplePtr могут создаваться как пустые указатели через конструктор по умолчанию или с nullptr ([SWS_CM_11534], [SWS_CM_11535]). Напротив, валидные экземпляры, содержащие полезные данные, формируются внутри промежуточного ПО при десериализации событий в слоты буфера и передаются в рамках GetNewSamples() вызываемому объекту на стороне приложения (EXP ARAComAPI, с. 44).

С передачей происходит полный переход права владения (ownership transfer) к приложению (EXP ARAComAPI §5.3.5.4). Чтобы гарантировать эксклюзивность владения, конструктор копирования и копирующий оператор присваивания удалены ([SWS_CM_11536], [SWS_CM_11538]). Передача управляемого слота памяти возможна исключительно через конструктор перемещения или перемещающее присваивание ([SWS_CM_11537], [SWS_CM_11540]), тогда как Swap() позволяет произвести обмен содержимым двух указателей ([SWS_CM_11544]).

Пока экземпляр SamplePtr существует и удерживает выборку, промежуточное ПО не может востребовать обратно или перезаписать занятую область памяти (EXP ARAComAPI §5.3.5.4). Освобождение слота промежуточного ПО происходит только тогда, когда время жизни SamplePtr заканчивается вызовом деструктора ([SWS_CM_11547]), или указатель явно очищается с помощью Reset(nullptr) либо присваиванием nullptr ([SWS_CM_11539], [SWS_CM_11545]).

Диаграмма состояний: фазы жизненного цикла и переходы владения SamplePtr. Источники: [SWS_CM_11534], [SWS_CM_11537], [SWS_CM_11545], [SWS_CM_11547], EXP ARAComAPI §5.3.5.4.

Путь использования

Типичный процесс доступа к данным подразделяется на следующие шаги:

1. Инициация запроса выборки: Приложение вызывает GetNewSamples() на прокси события и передает подходящую функцию обратного вызова с сигнатурой void(ara::com::SamplePtr<SampleType const>), а также верхнюю границу для количества запрашиваемых выборок (EXP ARAComAPI, с. 44).
2. Передача в функцию обратного вызова: Если имеются новые данные и квота буфера не исчерпана, промежуточное ПО десериализует выборку и передает новый экземпляр SamplePtr в функцию обратного вызова (EXP ARAComAPI, с. 44).
3. Проверка статуса End-to-End: Через GetProfileCheckStatus() приложение может запросить результат проверки защиты E2E для текущего пакета данных ([SWS_CM_90420]).
4. Чтение данных: Логика приложения обращается к управляемому объекту для чтения через operator* ([SWS_CM_11541]), operator-> ([SWS_CM_11542]) или метод Get() ([SWS_CM_11546]).
5. Дальнейшая обработка или освобождение: Если выборка должна сохраняться дольше времени выполнения функции обратного вызова, приложение перемещает указатель с помощью перемещающего конструктора в собственные структуры памяти ([SWS_CM_11537]). Если указатель остается в области видимости функции обратного вызова, он автоматически уничтожается при выходе из нее ([SWS_CM_11547]), что немедленно освобождает слот в промежуточном ПО (EXP ARAComAPI §5.3.5.4).

Диаграмма последовательности: последовательность взаимодействия при GetNewSamples() с передачей владения и освобождением буфера. Источники: [SWS_CM_11541], [SWS_CM_11547], [SWS_CM_90420], EXP ARAComAPI, с. 44, EXP ARAComAPI §5.3.5.4.

Сценарии ошибок

При использовании SamplePtr необходимо учитывать специфические граничные условия и источники ошибок:

• Исчерпание квоты буфера: при каждом вызове GetNewSamples() промежуточное ПО проверяет, не превышает ли количество сэмплов, удерживаемых приложением в данный момент, квоту, гарантированную ранее при вызове Subscribe(). Если квота превышена, GetNewSamples() отказывает в выдаче дальнейших сэмплов и вместо этого возвращает ara::core::ErrorCode (EXP ARAComAPI, с. 44, EXP ARAComAPI, с. 45).
• Недействительность из-за потери подписки или уничтожения прокси: SamplePtr ведет себя детерминированно как std::unique_ptr только до тех пор, пока сохраняется подписка на базовое событие и существует вышестоящий экземпляр прокси. Удержание указателей после прекращения подписки или уничтожения прокси считается нарушением предусловий.
• Действительность указателя и нулевое состояние: с помощью operator bool() можно оценить состояние занятости указателя ([SWS_CM_11543]). Разыменование пустого указателя через operator* или operator-> приводит к неопределенному поведению. Все методы доступа и модификации объявлены как noexcept ([SWS_CM_11541], [SWS_CM_11542], [SWS_CM_11546]).
• Ошибки E2E-валидации: успешно полученный валидный указатель не гарантирует безошибочность переданных данных; по возвращаемому значению GetProfileCheckStatus() приложение должно проверить, сигнализирует ли сквозная E2E-защита об искажении данных или задержках передачи ([SWS_CM_90420]).