класс ara::nm::NetworkHandle

Использование и жизненный цикл

Класс NetworkHandle функционирует как объект доступа к дескриптору сети, адресуемому через ara::core::InstanceSpecifier, и предназначен для State Management [SWS_ANM_01000]. Инстанцирование осуществляется путем передачи InstanceSpecifier прототипа порта NetworkManagementPortInterface [SWS_ANM_01001]. Поскольку класс объявлен как final, его нельзя использовать в качестве базового класса для наследования [SWS_ANM_01000].

Семантика перемещения и параллелизм

Объекты этого класса обладают чистой семантикой перемещения: конструктор копирования [SWS_ANM_01005], а также оператор присваивания с копированием [SWS_ANM_01006] удалены (= delete). Экземпляры вместо этого могут передаваться через конструктор перемещения [SWS_ANM_01003] и оператор присваивания с перемещением [SWS_ANM_01004].

В отношении потокобезопасности действуют следующие требования:

• Конструктор с InstanceSpecifier является потокобезопасным (thread-safe) [SWS_ANM_01001].
• Для конструктора перемещения потокобезопасность определена как зависящая от реализации (implementation-defined) [SWS_ANM_01003].
• Деструктор [SWS_ANM_01002] и присваивание с перемещением [SWS_ANM_01004] явно указаны как не потокобезопасные (not thread-safe). Интерпретация: поскольку потокобезопасность не гарантируется, вызывающий контекст, вероятно, отвечает за внешнюю синхронизацию, если несколько потоков используют один и тот же дескриптор. Вопрос Q-7172baaffab79218 (открытый)

Обработка ошибок

Все конструкторы, операторы присваивания, а также деструктор объявлены как noexcept [SWS_ANM_01001], [SWS_ANM_01002], [SWS_ANM_01003], [SWS_ANM_01004]. Исключения или возвращаемые значения ошибок в этом интерфейсе класса не предусмотрены.

Псевдоним типа NetworkStateChangeNotifier из заголовка ara/nm/network_handle.h определяет функциональную обертку для функций обратного вызова при изменениях состояния сети [SWS_ANM_01020]. Сигнатура std::function<void(const NetworkStateType&)> принимает в качестве параметра новое состояние как константную ссылку на NetworkStateType и не имеет возвращаемого значения [SWS_ANM_01020].

Уведомитель находит применение при мониторинге сетевого управления через две точки регистрации:

• Для сигнализации фактического состояния сети уведомитель регистрируется с помощью RegisterNetworkStateChangeNotifier [SWS_ANM_01010]. В качестве альтернативы шаблонная перегрузка позволяет передавать пользовательский executor, в контексте которого выполняется уведомитель [SWS_ANM_01015]. На один экземпляр может быть активен максимум один уведомитель [SWS_ANM_01010].
• Для уведомлений о запрашиваемом состоянии сети регистрация выполняется через RegisterNetworkRequestedStateChangeNotifier, на выбор напрямую [SWS_ANM_01012] или с указанием целевого исполнителя [SWS_ANM_01014]. Здесь также допускается максимум один обработчик [SWS_ANM_01012].

Что касается обработки ошибок, все функции регистрации возвращают ara::core::Result<void>; в случае сбоя регистрации сообщается об ошибке NmErrc::kInvalidHandler [SWS_ANM_01010], [SWS_ANM_01012]. Это, по всей видимости, происходит главным образом тогда, когда передается не полностью инициализированный или пустой функциональный объект. Вопрос Q-04452871df619a94 (открытый)

В качестве ограничения NetworkStateChangeNotifier специфицирован как непотокобезопасный (not thread-safe) [SWS_ANM_01020]. Соответствующие функции регистрации также спроектированы как непотокобезопасные [SWS_ANM_01010], [SWS_ANM_01012]. Поэтому вызывающие стороны должны гарантировать, что присваивание, а также регистрация осуществляются синхронизированно или последовательно.

Перечисление NetworkStateType представляет состояние сети в модуле anm (Adaptive Network Management) [SWS_ANM_01358]. Оно различает неактивное состояние kNoCom = 0 (если не все сопоставленные сети находятся в состоянии FULL_COM) и активное состояние kFullCom = 1 (когда все сопоставленные сети находятся в FULL_COM) [SWS_ANM_01358].

Тип находит разностороннее применение в интерфейсах ara/nm/network_handle.h:

• Zustandsabfrage: метод GetNetworkState() синхронно и потокобезопасно возвращает текущее эффективное состояние сети в виде ara::core::Result<NetworkStateType> [SWS_ANM_01007]. Точно так же GetNetworkRequestedState() потокобезопасно считывает текущее запрошенное состояние для PNC, VLAN или физической сети [SWS_ANM_01008].
• Zustandsanforderung: через SetNetworkRequestedState(NetworkStateType networkState) активно запрашивается (kFullCom) или освобождается (kNoCom) состояние для PNC, VLAN или физической сети [SWS_ANM_01009]. Эта операция специфицирована как непотокобезопасная [SWS_ANM_01009].
• Ereignisbenachrichtigung: через функциональную обертку NetworkStateChangeNotifier (std::function<void(const NetworkStateType&)>) данный тип передается в качестве параметра для информирования логики приложения об изменениях состояния [SWS_ANM_01020].

Обработка ошибок: при запросе или установке NetworkStateType через упомянутые методы в случае ошибки в ara::core::Result может возвращаться код NmErrc::kServiceNotAvailable [SWS_ANM_01007] [SWS_ANM_01008] [SWS_ANM_01009].

Использование

Функция RegisterNetworkRequestedStateChangeNotifier из заголовочного файла ara/nm/network_handle.h регистрирует функцию обратного вызова для уведомления об изменениях запрошенного состояния сети [SWS_ANM_01012]. Ей в качестве параметра передаётся NetworkStateChangeNotifier. Для изменений запрошенного состояния может быть зарегистрирован максимум один уведомитель [SWS_ANM_01012]. Функция объявлена как noexcept и возвращает ara::core::Result<void>.

Обработка ошибок

Если при регистрации возникает ошибка, она сообщается через ara::core::Result со специфическим кодом ошибки NmErrc::kInvalidHandler [SWS_ANM_01012]. Интерпретация: эта ошибка, вероятно, возникает, если переданный уведомитель недействителен или не может быть вызван. Вопрос Q-57a28e90a933e6de (открытый)

Параллелизм и ограничения

Функция специфицирована как непотокобезопасная (not thread-safe) [SWS_ANM_01012]. Поэтому вызывающие компоненты обязательно должны внешне синхронизировать параллельный доступ и попытки регистрации из нескольких потоков.

Взаимодействие

В качестве альтернативы прямому выполнению существует шаблонная перегрузка функции [SWS_ANM_01014], которая дополнительно принимает параметр executor. Это позволяет запускать уведомитель в явно предоставленном контексте выполнения; эта перегрузка также не является потокобезопасной и в случае ошибки возвращает NmErrc::kInvalidHandler [SWS_ANM_01014].

Объявленная в заголовочном файле ara/nm/network_handle.h шаблонная функция RegisterNetworkRequestedStateChangeNotifier регистрирует обратный вызов типа NetworkStateChangeNotifier для получения уведомлений об изменениях состояния запрошенной сети [SWS_ANM_01014]. С помощью дополнительного параметра executor типа ExecutorT&& определяется желаемый контекст выполнения, в котором этот уведомитель должен выполняться при изменениях статуса. Синхронный вызов для регистрации обработчика объявлен как noexcept и возвращает ara::core::Result<void> вызывающему компоненту.

Для обработки ошибок интерфейс сигнализирует о проблемах через возвращаемый тип ara::core::Result. В случае передачи недействительного обработчика операция завершается неудачей, и функция возвращает специфический код ошибки NmErrc::kInvalidHandler [SWS_ANM_01014].

Что касается параллелизма и ограничений на вызовы, функция явно специфицирована как not thread-safe [SWS_ANM_01014]. Это означает, что при параллельном доступе к одному и тому же экземпляру дескриптора вызывающие компоненты должны обеспечивать внешнюю синхронизацию во избежание конфликтов данных.

В общесистемном взаимодействии эта функция представляет собой расширение варианта с меньшим числом параметров [SWS_ANM_01012], который регистрирует не более одного уведомителя для изменений запрошенного состояния. Интерпретация: поскольку базовая спецификация в [SWS_ANM_01012] допускает максимум один уведомитель, этот вызов, вероятно, также занимает тот же слот уведомителя и при повторной регистрации перезаписывает ранее установленный обработчик. Вопрос Q-5d8c1832558ac15b (открытый)

Использование

Функция RegisterNetworkStateChangeNotifier служит для регистрации уведомителя для эффективного состояния сети [SWS_ANM_01010]. Она объявлена в заголовочном файле ara/nm/network_handle.h и определена как noexcept [SWS_ANM_01010]. В качестве параметра передаётся NetworkStateChangeNotifier notifier; возврат значения происходит синхронно через ara::core::Result<void> [SWS_ANM_01010]. Для данного состояния может быть зарегистрирован максимум один уведомитель [SWS_ANM_01010].

Обработка ошибок

В случае ошибки ara::core::Result возвращает код ошибки NmErrc::kInvalidHandler [SWS_ANM_01010]. Это сигнализирует вызывающему компоненту о том, что переданный обработчик недействителен [SWS_ANM_01010].

Параллелизм и ограничения

Интерфейс прямо специфицирован как not thread-safe [SWS_ANM_01010]. Вызывающие компоненты должны гарантировать, что вызовы RegisterNetworkStateChangeNotifier не выполняются конкурентно без внешней синхронизации. Поскольку спецификация предусматривает максимум один уведомитель, повторный вызов, вероятно, перезапишет существующую регистрацию или отклонит её [SWS_ANM_01010]. Вопрос Q-5e3ac4e4d2b33e9f (открытый)

Взаимодействие

Функция напрямую связана с шаблонной перегрузкой [SWS_ANM_01015]. В то время как базовая функция привязывает уведомитель без явного контекста выполнения, [SWS_ANM_01015] позволяет передавать дополнительный параметр ExecutorT&& executor для управления выполнением обработчика в заданном контексте [SWS_ANM_01015]. Оба варианта реализуют требования из RS_Nm_00051, определены в одном и том же заголовочном файле и разделяют классификацию not thread-safe, а также ошибку NmErrc::kInvalidHandler [SWS_ANM_01010] [SWS_ANM_01015].

Шаблонная функция RegisterNetworkStateChangeNotifier ([SWS_ANM_01015]) из заголовочного файла ara/nm/network_handle.h регистрирует функцию обратного вызова для отслеживания изменений эффективного состояния сети. В отличие от варианта с меньшим количеством параметров, этот интерфейс, помимо notifier типа NetworkStateChangeNotifier, дополнительно принимает пользовательский контекст выполнения executor (ExecutorT&&), через который уведомления асинхронно диспетчеризируются и обрабатываются.

Обработка ошибок и возвращаемые значения

Функция объявлена как noexcept и сигнализирует о результате через ara::core::Result<void> [SWS_ANM_01015]. Если при регистрации возникает ошибка — в частности, при передаче недействительного или невызываемого обработчика, — операция завершается неудачей и возвращает код ошибки NmErrc::kInvalidHandler.

Параллелизм и взаимодействие

В отношении потокобезопасности интерфейс специфицирован как not thread-safe [SWS_ANM_01015]. Поэтому вызовы регистрации не должны выполняться без защиты конкурентно из нескольких потоков для одного и того же контекста состояния. В составе системы функция дополняет базовый интерфейс [SWS_ANM_01010], который регистрирует не более одного уведомителя без явного исполнителя. В качестве интерпретации, вероятно, и для [SWS_ANM_01015] верно, что активен всегда только один уведомитель, и новый вызов заменяет ранее сохранённый обработчик. Вопрос Q-e9a890e004a4f0ea (открытый)

Функция SetNetworkRequestedState служит для запроса или освобождения кластера подсетей (PNC), VLAN или физической сети через заголовочный файл ara/nm/network_handle.h согласно [SWS_ANM_01009]. В качестве входного параметра передается требуемое целевое состояние networkState типа NetworkStateType. Вызов, вероятно, выполняется синхронно, поскольку интерфейс напрямую возвращает ara::core::Result<void> вместо асинхронного объекта Future. Вопрос Q-38a98cab4ea55704 (открытый)

В случае успеха метод возвращает пустой ara::core::Result<void> [SWS_ANM_01009]. Если запрошенное состояние не может быть установлено или служба сетевого управления недоступна, функция сообщает о специфическом коде ошибки NmErrc::kServiceNotAvailable в объекте результата [SWS_ANM_01009]. Вызывающие программные компоненты должны явным образом анализировать этот объект ошибки, чтобы адекватно реагировать на недоступные службы.

Что касается параллелизма, данная операция согласно спецификации явно классифицирована как not thread-safe [SWS_ANM_01009]. Поэтому одновременные вызовы для одного и того же дескриптора не должны выполняться без синхронизации со стороны приложения во избежание состояний гонки. Благодаря объявлению с noexcept дополнительно гарантируется, что исключения C++ не выходят наружу [SWS_ANM_01009].

Использование

Функция UnregisterNetworkRequestedStateChangeNotifier относится к модулю адаптивного управления сетью (anm) и объявляется через заголовочный файл ara/nm/network_handle.h [SWS_ANM_01013]. Ее задача состоит в отмене нотификатора для изменений запрошенного состояния сети [SWS_ANM_01013], благодаря чему она способствует реализации вышестоящего требования RS_Nm_00051.

Интерфейс не ожидает входных параметров и не возвращает значения (void) [SWS_ANM_01013]. Интерпретация: поскольку сигнатура не предусматривает асинхронного типа результата, вызов, вероятно, выполняется синхронно, а разрегистрация вступает в силу сразу после возврата функции. Вопрос Q-df3005625905440a (открытый)

Обработка ошибок

Функция специфицирована с noexcept [SWS_ANM_01013] и тем самым не генерирует исключений. В спецификации для вызывающей стороны не предусмотрено ни кодов ошибок, ни отдельных реакций на ошибки.

Параллелизм и ограничения

В отношении потокобезопасности функция явно классифицирована как not thread-safe [SWS_ANM_01013]. Вызывающие программные модули поэтому должны с помощью надлежащих мер синхронизации гарантировать, что дерегистрация не выполняется параллельно с другими обращениями к тому же экземпляру.