класс ara::shwa::Buffer

Шаблон класса служит для управления многомерными буферами памяти для безопасного аппаратного ускорения в Adaptive Platform SWS_SafeHardwareAcceleration §7.1 «High Level Design of Safe Hardware Acceleration in an Adaptive Platform». Поскольку все стандартные операции, операции копирования и перемещения удалены, создание осуществляется исключительно через статические фабричные методы, такие как [AP_SWS_SHWA_00209], в виде монопольно удерживаемого указателя. С помощью конфигурируемых свойств и аллокаторов память можно адаптировать, тогда как операции чтения свойств не рассчитаны на потокобезопасность. Неудачные попытки выделения памяти возвращаются вызывающей стороне через определенные коды ошибок.

больше ›

Контекст

Шаблонный класс ara::shwa::Buffer в модуле Safe Hardware Acceleration (SHWA) платформы Adaptive Platform образует центральную абстракцию для инкапсуляции и управления многомерными областями памяти. Как изложено в системной архитектуре, Adaptive Applications, а также функциональные кластеры обычно взаимодействуют с комбинацией из нескольких очередей (Queues), устройств-ускорителей (Devices) и буферов (SWS_SafeHardwareAcceleration §7.1 «High Level Design of Safe Hardware Acceleration in an Adaptive Platform»). При этом буферы предоставляют память, необходимую для операций ускорения на уровне хоста или устройства, и могут опционально конфигурироваться с помощью специфичных для приложения аллокаторов ([AP_SWS_SHWA_00210]) или указателей на данные хоста.

Контекстная диаграмма: встраивание буфера в функциональное взаимодействие приложений, устройств, очередей и аллокаторов. Источники: SWS_SafeHardwareAcceleration §7.1 «High Level Design of Safe Hardware Acceleration in an Adaptive Platform», [AP_SWS_SHWA_00210].

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

Жизненный цикл экземпляра буфера подчиняется строгим семантическим ограничениям. Для гарантии однозначных отношений владения удалены как конструктор по умолчанию ([AP_SWS_SHWA_00202]), так и конструктор копирования ([AP_SWS_SHWA_00203]) и оператор присваивания копированием ([AP_SWS_SHWA_00204]). Точно так же явно удалены конструктор перемещения ([AP_SWS_SHWA_00205]) и оператор присваивания перемещением ([AP_SWS_SHWA_00206]). Интерпретация: предположительно, это предотвращает неконтролируемое дублирование или перемещение ресурсов буфера либо аппаратных связей в памяти. Вопрос Q-dcabd66fa9f3ec2a (открытый)

Поэтому создание выполняется исключительно через статические фабричные методы семейства перегрузок Create, которые в случае успеха возвращают std::unique_ptr<Buffer>, инкапсулированный в ara::core::Result. При этом доступны различные пути конструирования:

• Создание с областью буфера и опциональным списком свойств: потокобезопасно ([AP_SWS_SHWA_00209]).
• Создание с областью буфера, выделенным аллокатором и списком свойств: потокобезопасно ([AP_SWS_SHWA_00210]).
• Создание на основе существующих указателей на данные хоста с областью буфера: потокобезопасно как для модифицируемых указателей ([AP_SWS_SHWA_00211]), так и для указателей на константные данные ([AP_SWS_SHWA_00213]).
• Создание с указателем на константные данные хоста, областью буфера и аллокатором: потокобезопасно ([AP_SWS_SHWA_00214]).
• Прямое создание только через аллокатор: не потокобезопасно ([AP_SWS_SHWA_00212]).

После успешного создания владение остаётся у вызывающего контекста через std::unique_ptr. Уничтожение объекта по истечении умного указателя, предположительно, автоматически освобождает лежащую в основе область памяти через соответствующий аллокатор. Вопрос Q-aa2b5642b8527803 (открытый)

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

Типичный сценарий использования начинается с выделения памяти и инициализации буфера через один из потокобезопасных фабричных методов, таких как [AP_SWS_SHWA_00209]. После успешного инстанцирования приложение может проверить, сохранены ли специфические свойства для этого буфера, вызвав HasProperty<PropertyT>() ([AP_SWS_SHWA_00215]). Если требуемое свойство присутствует, его конкретное значение можно синхронно прочитать с помощью GetProperty<PropertyT>() ([AP_SWS_SHWA_00216]). Следует учитывать, что как HasProperty, так и GetProperty объявлены как не потокобезопасные; поэтому параллельные запросы к одному и тому же объекту буфера должны синхронизироваться на стороне приложения.

Диаграмма последовательности: типичная последовательность действий при инстанцировании через фабрику и последующем запросе свойств. Источники: [AP_SWS_SHWA_00209], [AP_SWS_SHWA_00215], [AP_SWS_SHWA_00216].

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

Все фабричные методы и методы инспекции объявлены с noexcept и обеспечивают полную безопасность исключений (exception safe). Ошибки сигнализируются через ara::core::Result:

• Если при вызове Create выделение памяти на стороне хоста или ускорителя завершается неудачей, возвращается ошибка ShwaErrorCode::kMemoryNotAllocated ([AP_SWS_SHWA_00209], [AP_SWS_SHWA_00210], [AP_SWS_SHWA_00211], [AP_SWS_SHWA_00212], [AP_SWS_SHWA_00213], [AP_SWS_SHWA_00214]). В качестве семантики отката при этом определено ShwaErrorCode::kRuntime.
• Если через GetProperty<PropertyT>() запрашивается свойство, которое не поддерживается буфером или платформой, результат возвращает код ошибки ShwaErrorCode::kFeatureNotSupported ([AP_SWS_SHWA_00216]). Во избежание этой ошибки рекомендуется предварительная проверка с помощью HasProperty<PropertyT>() ([AP_SWS_SHWA_00215]).