clase <SI-Namespace>::skeleton:: events::<Event>

El método Allocate se invoca a nivel de Skeleton para un evento ([SWS_CM_90438]; AUTOSAR_AP_EXP_ARAComAPI §5.4.1 «Skeleton Class API’s») con el fin de asignar memoria para la transferencia de datos de eventos cuando el Communication Management (ara::com) es responsable de la gestión de los datos ([SWS_CM_90438]). Devuelve una instancia de tipo ara::com::SampleAllocateePtr<SampleType> ([SWS_CM_90438]). Conceptualmente, este tipo de puntero se comporta como un std::unique_ptr<T>, de modo que solo una parte es propietaria del puntero en cada momento (ARAComAPI §6 «Event Allocate/Send sample Binding implementer hint»).

En cuanto al tratamiento de errores y la seguridad frente a excepciones, Allocate está especificado como not exception safe ([SWS_CM_90438]). La especificación define dos posibles infracciones (violations):

• SampleAllocationViolation: No hay suficientes recursos de memoria disponibles para asignar los datos ([SWS_CM_90438]).
• AllocateUsageViolation: La asignación se realizó de forma inadmisible a través de un asignador personalizado ([SWS_CM_90438]).

El concepto tras Allocate tiene como objetivo primordial admitir mecanismos de copia cero (zero-copy), en particular con transporte IPC basado en memoria compartida, presuponiendo una sincronización estricta entre lectores y escritores (ARAComAPI §6 «Event Allocate/Send sample Binding implementer hint»). Los implementadores deben tener en cuenta que los requisitos de serialización pueden anular la copia cero si los tipos de datos no están configurados como compatibles binariamente en el despliegue o si una lógica de detección lo descarta (ARAComAPI §6 «Event Allocate/Send sample Binding implementer hint»).

En interacción con el envío de eventos, el puntero de memoria obtenido a través de Allocate se pasa a Send(ara::com::SampleAllocateePtr<SampleType> data) ([SWS_CM_90437]). Tras la invocación de Send, la aplicación de servicio ya no debe acceder a los datos una vez que el Communication Management envía los datos a todas las aplicaciones suscritas ([SWS_CM_90437]).

La función [SWS_CM_00162] sirve, en el lado del proveedor del servicio y dentro de <SI-Namespace>::skeleton::events::<Event>, para enviar datos de eventos a todas las aplicaciones suscritas. En esta variante, la responsabilidad de la asignación de datos recae por completo en la aplicación usuaria. El objeto de datos se transfiere a través del parámetro data, tras lo cual la implementación del binding realiza una copia interna durante la llamada (ARAComAPI, Figure 6.17 «BrakeEvent Class»). Tras el retorno de la llamada síncrona al método, la aplicación puede modificar o liberar inmediatamente el área de memoria original.

El método está declarado con noexcept y especificado como seguro frente a excepciones. Devuelve un ara::core::Result<void> que, en caso de éxito, contiene void y, en caso de error, reporta códigos de error de [SWS_CM_10432] ([SWS_CM_00162]):

• ComErrc::kServiceNotOffered: Se produce si la instancia de servicio aún no se ha puesto a disposición mediante OfferService().
• ComErrc::kMinimumSendIntervalViolationError: Se produce si la solicitud de envío se ha emitido con mayor rapidez que el intervalo mínimo de envío configurado (ServiceInterfaceDeploymentElement.minimumSendInterval).

A diferencia de la alternativa de copia cero [SWS_CM_90437], la cual requiere punteros de tipo ara::com::SampleAllocateePtr obtenidos a través de Allocate(), esta llamada no requiere vincular memoria al framework. El mismo comportamiento de transmisión y las mismas condiciones de error se aplican también, según [SWS_CM_00119], al método de actualización Update de campos.

Uso y contexto de llamada

El método Send se invoca en una instancia de evento en el skeleton del servicio (<SI-Namespace>::skeleton::events::<Event>) ([SWS_CM_90437]). Transmite datos de eventos de cuya gestión de memoria se encarga Communication Management. El parámetro data de tipo ara::com::SampleAllocateePtr<SampleType> debe haberse obtenido previamente mediante Allocate() ([SWS_CM_90437]). Este tipo de puntero se comporta semánticamente como un std::unique_ptr, con lo cual la propiedad de los datos se transfiere a la capa de comunicación durante la invocación (ARAComAPI §6.17 «BrakeEvent Class»). Tras la transferencia, se prohíbe cualquier acceso posterior a los datos a la aplicación emisora ([SWS_CM_90437]).

Tratamiento de errores y condiciones límite

La función está declarada como noexcept y devuelve un ara::core::Result<void> ([SWS_CM_90437]). Si el envío falla, el resultado contiene un código de error de ara::com::ComErrc ([SWS_CM_10432]):

• ComErrc::kServiceNotOffered: El servicio correspondiente aún no se ha ofrecido previamente con OfferService() ([SWS_CM_90437]).
• ComErrc::kMinimumSendIntervalViolationError: El intervalo mínimo de envío configurado para el elemento de servicio (minimumSendInterval) aún no ha transcurrido desde la última transmisión ([SWS_CM_90437]).

Ambos casos de error poseen semántica de reversión ([SWS_CM_90437]). Por lo tanto, el servicio debe haberse ofrecido obligatoriamente antes de la invocación, y las llamadas de envío sucesivas deben respetar la distancia mínima configurada.

Interacción y optimización

En comparación con la signatura [SWS_CM_00162], en la que se transfieren datos gestionados por la aplicación y el Communication Management los copia, esta variante tiene como objetivo la comunicación de copia cero (zero-copy) mediante memoria compartida (ARAComAPI §6.18 «Event Allocate/Send sample»). Para ello se presupone una estricta sincronización entre escritores y lectores, debiendo tenerse en cuenta los posibles requisitos de serialización entre los interlocutores de comunicación (ARAComAPI §6.18 «Event Allocate/Send sample»).

usar

La función SetSubscriptionStateChangeHandler registra en el ámbito del skeleton (skeleton::events) un manejador de callback para supervisar el estado de suscripción de un evento [SWS_CM_12008]. El parámetro handler debe ser un objeto invocable según el tipo SubscriptionStateChangeHandler conforme a [SWS_CM_00311]. El método no devuelve ningún valor de retorno y está especificado como noexcept [SWS_CM_12008].

Communication Management invoca el manejador registrado en cuanto cambia el estado de suscripción del evento [SWS_CM_12012]. En el lado del skeleton, esto ocurre con el estado kSubscribed tan pronto como el número de suscripciones activas pasa a ser mayor que cero [SWS_CM_12013], o bien con kNotSubscribed cuando ya no existen suscripciones activas [SWS_CM_12014] SWS CommunicationManagement §7.5.4 «Query Service Event Subscription State on Skeleton side».

Tratamiento de errores y concurrencia

La operación está clasificada como exception safe [SWS_CM_12008]. Si el callable transferido no es válido o es nulo, se produce una InvalidHandlerViolation [SWS_CM_12008]. Interpretación: Dado que la función no lanza excepciones ni devuelve un código de error, es de suponer que esta vulneración de la especificación se capture a través de mecanismos del entorno de ejecución específicos de la plataforma. Pregunta Q-a7b7b54f0d538b40 (abierta)

El manejador puede sobrescribirse en tiempo de ejecución [SWS_CM_12012]. Para la ejecución en un contexto dedicado de hilo o de tareas, existe la sobrecarga con el parámetro de plantilla executor [SWS_CM_12009]. [SWS_CM_01110] define un registro análogo para elementos trigger del skeleton.

La función de plantilla SetSubscriptionStateChangeHandler sirve a nivel de skeleton ([SWS_CM_12009]), en el espacio de nombres de un evento, para registrar una retrollamada ante cambios de estado de suscripciones entrantes. Frente a la función básica sin ejecutor ([SWS_CM_12008]), recibe adicionalmente un contexto de ejecución (executor) en el que se ejecuta el manejador registrado ([SWS_CM_12009]). La función no tiene valor de retorno, está declarada como noexcept y se considera segura frente a excepciones ([SWS_CM_12009]).

En cuanto al comportamiento ante errores, la transferencia de un callable no válido o nulo conduce a una InvalidHandlerViolation ([SWS_CM_12009]). El manejador registrado puede sobrescribirse en cualquier momento durante el tiempo de ejecución de la aplicación mediante una nueva llamada ([SWS_CM_12012]).

Communication Management invoca al manejador en cuanto cambia el estado de las suscripciones para el evento respectivo (SWS CommunicationManagement §7.5.4 «Query Service Event Subscription State on Skeleton side», [SWS_CM_12012]):

• La llamada se realiza con el estado kSubscribed cuando el número de suscripciones activas pasa de cero a más de cero ([SWS_CM_12013]).
• Si el número de suscriptores activos vuelve a descender a cero, se notifica al manejador con kNotSubscribed ([SWS_CM_12014]).

Interpretación: Al transferir executor, la ejecución del manejador probablemente se vincule de forma dirigida a contextos de hilos o de despacho propios de la aplicación ([SWS_CM_12009]), con el fin de desacoplar limpiamente la notificación concurrente del código del skeleton respecto de los hilos de comunicación internos. Pregunta Q-b11f3bc97069f2ec (abierta)

La función UnsetSubscriptionStateChangeHandler sirve en el nivel de skeleton, dentro del espacio de nombres ::skeleton::events::{<event-name>}, para dar de baja un manejador de cambios de estado registrado previamente para el ara::com::SubscriptionState de un evento [SWS_CM_12010]. La función no acepta parámetros y no devuelve ningún valor (void) [SWS_CM_12010]. La inclusión se realiza mediante la cabecera #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h" [SWS_CM_12010].

En cuanto al comportamiento frente a excepciones, el método está declarado con noexcept y especificado como seguro frente a excepciones (exception safe) [SWS_CM_12010]. No se devuelven códigos de error específicos ni se lanzan excepciones de C++ [SWS_CM_12010]. Interpretación: es probable que cualquier condición de error interna durante la baja de registro sea interceptada internamente por la gestión de comunicaciones, ya que la firma no contempla notificación de errores. Pregunta Q-7e986a15e552ca19 (abierta)

En la interacción con interfaces relacionadas, existen funciones análogas para la baja de registro de manejadores:

• En el nivel de skeleton, ::skeleton::triggers::{<trigger-name>}::UnsetSubscriptionStateChangeHandler proporciona la baja de registro correspondiente para disparadores [SWS_CM_01112].
• En el nivel de proxy, existen métodos equivalentes para dar de baja manejadores de cambios de estado para eventos [SWS_CM_00334], campos [SWS_CM_11609] y disparadores [SWS_CM_01108] dentro del espacio de nombres proxy AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s».