класс ara::shwa::Id

Шаблонный класс ara::shwa::Id инкапсулирует многомерные идентификаторы в модуле shwa и обеспечивает контролируемое инстанцирование через статические фабричные методы, такие как Create [AP_SWS_SHWA_00707]. Являясь копируемым и перемещаемым объектом-значением, он позволяет получать доступ к отдельным индексам измерений с помощью Get и Set [AP_SWS_SHWA_00710]. Поскольку операции чтения и записи, а также многомерные фабрики не являются потокобезопасными, необходимая синхронизация возлагается на вызывающее приложение.

больше ›

Контекст

Шаблонный класс ara::shwa::Id представляет внутри модуля shwa многомерную идентификацию или индексацию для структур разделяемой памяти либо аппаратных ускорителей. Он инкапсулирует координаты или индексы измерений, которые могут инстанцироваться через статические фабричные методы, а затем опрашиваться или модифицироваться. Класс объявлен как final и параметризует количество измерений через параметр шаблона Dimensions со значением по умолчанию 1. В качестве участников взаимодействия обычно выступают компоненты приложения, которым необходимо адресовать структурированный доступ к буферам ускорителя или ресурсам памяти. При этом экземплярный объект ara::shwa::Id служит компактным объектом-значением для координатной адресации по измерениям.

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

Инстанцирование ara::shwa::Id подчиняется строгим требованиям: конструктор по умолчанию явно удален [AP_SWS_SHWA_00702]. Прямое создание неинициализированного объекта тем самым исключено. Вместо этого создание выполняется контролируемым образом через статические фабричные функции Create, которые возвращают объект, инкапсулированный в ara::core::Result [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. В зависимости от требуемой размерности доступны перегрузки для одного измерения [AP_SWS_SHWA_00707], двух измерений [AP_SWS_SHWA_00708] или трех измерений [AP_SWS_SHWA_00709].

С точки зрения отношений владения ara::shwa::Id ведет себя как обычный объект-значение. Он реализует как конструктор копирования [AP_SWS_SHWA_00703], так и оператор присваивания копированием [AP_SWS_SHWA_00704] как стандартизированные (default) и безопасные относительно исключений (noexcept). Также доступны конструктор перемещения [AP_SWS_SHWA_00705] и оператор присваивания перемещением [AP_SWS_SHWA_00706] с noexcept. Таким образом, экземпляры можно эффективно размещать в контейнерах, передавать по значению или перемещать между частями программы. Особого внимания требует потокобезопасность: в то время как одномерный фабричный метод специфицирован как потокобезопасный [AP_SWS_SHWA_00707], двух- и трехмерные фабричные методы явно обозначены как непотокобезопасные [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. При параллельной инициализации многомерных индексов вызывающие стороны должны предусмотреть соответствующие меры синхронизации.

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

Типичный сценарий использования включает контролируемое инстанцирование через подходящий фабричный вызов, проверку объекта Result, а также последующие операции чтения и записи для отдельных измерений. Сначала приложение вызывает Create с желаемыми границами измерений или значениями индексов. После успешного возврата ara::core::Result<Id> содержащееся в нем значение извлекается. С помощью константного метода Get можно запросить значение индекса для определенного измерения [AP_SWS_SHWA_00710]. При необходимости значение определенного измерения можно впоследствии изменить с помощью Set [AP_SWS_SHWA_00711]. Оба метода (Get и Set) классифицированы как непотокобезопасные; одновременный доступ к одному и тому же экземпляру из нескольких потоков должен синхронизироваться извне.

Диаграмма последовательности: типичный процесс фабричного создания, запроса значений и последующей модификации объекта Id. Источники: [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00710], [AP_SWS_SHWA_00711]

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

При создании через статические методы Create могут возникать ошибки времени выполнения. Если инстанцирование завершается сбоем, фабричный метод возвращает ara::core::Result, содержащий код ошибки ShwaErrorCode::kRuntime [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. Поэтому вызывающие стороны должны в обязательном порядке проверить возвращаемое значение с помощью HasValue(), прежде чем обращаться к экземпляру. Все функции Create гарантируют семантику отката и объявлены как безопасные относительно исключений (noexcept).

При штатной работе с методами Get и Set следует учитывать, что согласно спецификации они не являются безопасными относительно исключений (not exception safe) и работают непотокобезопасно [AP_SWS_SHWA_00710], [AP_SWS_SHWA_00711]. Интерпретация: передача недопустимых значений измерений за пределами допустимого диапазона значений, вероятно, приведет к неопределенному поведению или исключениям, так как для некорректных параметров в этих методах не определены отдельные коды ошибок. Вопрос Q-6983f5f27702e6e8 (открытый) Вызывающие стороны должны перед вызовом убедиться, что аргумент dimension находится в допустимых пределах экземпляра.