clase <SI-Namespace>::proxy::<SI>Proxy

Uso y semántica

El método de fábrica estático Create sirve, conforme a [SWS_CM_10438], para la creación libre de excepciones de una instancia de proxy (<SI>Proxy) según el modismo de constructor nombrado. Requiere como parámetro handle un handle de servicio determinado previamente según [SWS_CM_00131]. La llamada se realiza de forma síncrona y está declarada como noexcept. El resultado se devuelve en un ara::core::Result que, en caso de éxito, contiene la instancia de proxy lista para operar.

Manejo de errores

Si se produce un error durante la instanciación, Create devuelve a través de ara::core::Result un código de error de tipo ara::com::ComErrc [SWS_CM_10438]:

• ComErrc::kServiceNotAvailable: El servicio ya no está disponible tras haber sido ofrecido previamente a través de OfferService().
• ComErrc::kCommunicationFailure: El binding de red notifica un error de comunicación recuperable o el fallo de una conexión protegida.

Ambos errores presentan una semántica de reversión (rollback) [SWS_CM_10438]. En caso de errores estructurales o de seguridad, se aplican las vulneraciones especificadas (violations): Si el handle transferido es nulo o está corrupto, se produce una ErroneousServiceHandleViolation. Si el proceso invocador carece de los permisos necesarios para la instancia en el marco del Grant Enforcement, la solicitud se rechaza y se trata como InsufficientPermissionsViolation (SWS CommunicationManagement §8 «Security», [SWS_CM_10438]).

Concurrencia y condiciones de contorno

Interpretación: Dado que Create opera de forma síncrona y vincula recursos de comunicación, es de suponer que la llamada sea reentrante para handles diferentes, pero no debería ejecutarse en bucles de tiempo real estricto (hard real-time) críticos en el tiempo debido a posibles inicializaciones de red. Pregunta Q-f7ba23670f562788 (abierta)

El método estático FindService de la clase de proxy sirve para la localización síncrona de instancias de servicio disponibles mediante un ara::com::InstanceIdentifier ([SWS_CM_00122]). La llamada devuelve el resultado directamente como ara::core::Result, que en caso de ejecución correcta contiene un ara::com::ServiceHandleContainer ([SWS_CM_00122]). Este contenedor —implementado típicamente como ara::core::Vector ([SWS_CM_00304])— puede estar vacío, comprender un único manipulador de instancia o varios manipuladores en función del estado de provisión actual (ARAComAPI §6.5 «Service Discovery»).

En caso de error, el ara::core::Result devuelve un código de error de ara::com::ComErrc, concretamente ComErrc::kCommunicationFailure, si el enlace de red notifica un error de transmisión recuperable o un problema en la comunicación segura ([SWS_CM_00122]). Además, el acceso está sujeto a una verificación de permisos; unos permisos insuficientes dan lugar a una InsufficientPermissionsViolation ([SWS_CM_00122]).

En lo que respecta a la secuencia y a la concurrencia, se aplican las siguientes condiciones:

• Contexto de llamada y sincronía: dado que la búsqueda se ejecuta inmediatamente, solo se encuentran aquellas instancias para las que se haya llamado previamente a OfferService() en el lado del servidor (ARAComAPI §6.5 «Service Discovery»).
• Seguridad ante excepciones y reentrancia: la función está especificada como noexcept y segura ante excepciones ([SWS_CM_00122]). Puesto que el método es estático y no requiere un estado de objeto mutable, es de suponer que se puede invocar de forma reentrante y segura para subprocesos. Pregunta Q-3228cc998c4a737e (abierta)
• Procesamiento posterior: los manipuladores encontrados sirven para la instanciación de objetos de proxy a través del constructor Proxy(const HandleType &handle) ([SWS_CM_00131]). Para una búsqueda basada en modelos, se encuentra disponible alternativamente la sobrecarga con ara::core::InstanceSpecifier ([SWS_CM_00622]).

La función estática FindService de la clase proxy sirve según [SWS_CM_00622] para la localización sincrónica de instancias de servicio disponibles en función de un ara::core::InstanceSpecifier con retorno inmediato («immediately returned request»). El requisito para la localización es que la respectiva instancia de skeleton de servicio se haya ofrecido previamente mediante OfferService() (ARAComAPI p. 103 «Figure 6.5: Service Discovery»).

Valores de retorno e interacción

Como resultado, la llamada devuelve un ara::core::Result con un ara::com::ServiceHandleContainer según [SWS_CM_00622], que por defecto se basa en ara::core::Vector [SWS_CM_00304]. Este contenedor puede estar vacío, contener un único handle o múltiples instancias encontradas (ARAComAPI p. 103 «Figure 6.5: Service Discovery»). A continuación, los handles de servicio determinados se pasan al constructor para la instanciación del objeto proxy [SWS_CM_00131]. De forma alternativa, para una búsqueda asincrónica dirigida por eventos con notificación se encuentra disponible StartFindService [SWS_CM_00623], mientras que para los identificadores de instancia se utiliza la sobrecarga de [SWS_CM_00122].

Tratamiento de errores y condiciones límite

La función está declarada como noexcept y se considera segura frente a excepciones («exception safe») según [SWS_CM_00622]. En caso de error, el objeto Result contiene el código de error ComErrc::kCommunicationFailure, por ejemplo ante fallos de comunicación del enlace de red [SWS_CM_00622]. Además, [SWS_CM_00622] define infracciones de modelo y de autorización como InstanceSpecifierMappingIntegrityViolation, PortInterfaceMappingViolation, ProcessMappingViolation, InstanceSpecifierAlreadyInUseViolation y InsufficientPermissionsViolation.

Interpretación: Debido al retorno sincrónico e inmediato, el método probablemente resulte adecuado sobre todo para fases de inicialización iniciales o sondeos específicos, siempre que no se requiera una observación continua vía callback. Pregunta Q-ea5b242a6fe41d20 (abierta)

usar

El constructor explícito <SI>Proxy instancia la clase de proxy de servicio específica de tipo en el espacio de nombres <SI-Namespace>::proxy [SWS_CM_00131]. En el marco del patrón Proxy-Skeleton, este objeto generado sirve en el lado del consumidor de servicios como fachada local que reenvía las llamadas a métodos a la implementación de servicio efectiva ARAComAPI Figure 5.1 «Proxy Skeleton Pattern».

Para la construcción se transfiere como parámetro una referencia a un HandleType válido [SWS_CM_00131]. Este identificador debe haberse obtenido previamente mediante mecanismos de Service Discovery, ya sea de forma síncrona a través de FindService() [SWS_CM_00122] o de forma asíncrona a través del callback registrado de StartFindService() [SWS_CM_00123].

Manejo de errores

La construcción no es segura frente a excepciones (not exception safe) [SWS_CM_00131]. Si no se puede alcanzar el servicio referenciado, se desencadena una ara::com::ComException conforme a ara::com::ComErrc::kServiceNotAvailable [SWS_CM_00131]. Además, se definen las siguientes infracciones:

• ErroneousServiceHandleViolation: Se produce cuando el objeto HandleType transferido es nulo o está dañado [SWS_CM_00131].
• InsufficientPermissionsViolation: Se produce cuando la creación es denegada por la verificación de derechos (Grant Enforcement) [SWS_CM_00131].

Restricciones y ciclo de vida

Para la clase Proxy, el constructor de copia está explícitamente eliminado (=delete) [SWS_CM_00136]. La transferencia de la instancia solo está permitida a través del constructor de movimiento (Move Constructor), el cual tampoco está especificado como seguro frente a excepciones [SWS_CM_00137]. En tiempo de ejecución, tras una creación exitosa, ante una caída temporal y posterior disponibilidad del servicio de destino, la gestión de comunicaciones actualiza automáticamente en segundo plano el direccionamiento de la capa de transporte de la instancia de proxy existente ARAComAPI Figure 6.1 «Auto Updating of Proxy Instance».

El destructor ~<SI>Proxy () concluye el ciclo de vida de una instancia de proxy de servicio y libera los recursos locales correspondientes [SWS_CM_99444]. En el lado del consumidor, un proxy de servicio sirve como fachada local para interactuar con una implementación de servicio potencialmente remota y reenvía las llamadas ARAComAPI §5.1 «Proxy Skeleton Pattern». El objeto proxy se instancia previamente mediante un handle de servicio determinado [SWS_CM_00131], el cual se puso a disposición a través de funciones de Service Discovery como FindService [SWS_CM_00122].

Para la destrucción y el comportamiento en tiempo de ejecución rigen las siguientes prescripciones y condiciones de contorno:

• Ciclo de vida y semántica: La destrucción se lleva a cabo de forma síncrona al salir del ámbito de validez o al eliminar explícitamente la instancia. Aunque el constructor de copia de la clase proxy esté eliminado [SWS_CM_00136], el objeto puede moverse antes de su destrucción mediante semántica de movimiento [SWS_CM_00137].
• Seguridad frente a excepciones: El destructor está especificado como not exception safe [SWS_CM_99444].
• Precondiciones y comportamiento ante fallos: Si se vulnera la condición previa [SWS_CM_00087], esto da lugar a una DanglingSamplesViolation [SWS_CM_99444]. (Interpretación: Antes de invocar el destructor, probablemente deban liberarse todas las referencias a muestras o punteros de datos retenidos por el consumidor para evitar referencias no válidas). Pregunta Q-5488797b732d9be6 (abierta)
• Interacción: Si se utilizan búsquedas de servicio asíncronas, estas deberían cancelarse en caso necesario mediante StopFindService antes de liberar el contexto de uso [SWS_CM_00125]. Además, los manejadores de tratamiento de errores registrados para eventos, triggers y campos pueden restablecerse con anterioridad [SWS_CM_00105] [SWS_CM_00108] [SWS_CM_00126].

El método estático StartFindService [SWS_CM_00123] de la clase proxy inicia la búsqueda asincrónica de instancias de servicio a partir de un ara::com::InstanceIdentifier registrando un manejador de devolución de llamada (ARAComAPI §6.5 «Service Discovery»). A la llamada se le pasan un ara::com::FindServiceHandler y el ara::com::InstanceIdentifier buscado [SWS_CM_00123].

En caso de éxito, la función devuelve un ara::core::Result con un ara::com::FindServiceHandle [SWS_CM_00123]. Este identificador representa la solicitud de búsqueda activa y es estrictamente necesario para finalizar de nuevo más adelante la monitorización de la disponibilidad del servicio y las llamadas posteriores al manejador mediante StopFindService [SWS_CM_00125].

Si surge un problema de comunicación al establecer la conexión, el método devuelve el código de error ComErrc::kCommunicationFailure en el ara::core::Result [SWS_CM_00123]. Si la instancia invocable transferida no es válida o es nula, esto se evalúa como InvalidHandlerViolation; la falta de permisos de acceso da lugar a una InsufficientPermissionsViolation [SWS_CM_00123].

Tan pronto como una instancia de servicio adecuada pasa a estar disponible en el sistema, la gestión de la comunicación invoca el manejador registrado con los identificadores de servicio correspondientes [SWS_CM_00123]. Mediante un HandleType notificado, la aplicación puede crear una instancia concreta de proxy a través del método Named Constructor Create [SWS_CM_10438]. Interpretación: el manejador presumiblemente se ejecutará de forma asincrónica en un hilo de la gestión de la comunicación, por lo que el acceso a recursos compartidos en el manejador debería ser seguro para subprocesos. Pregunta Q-9dc570d7e65fc808 (abierta) Para la búsqueda a través de un identificador basado en modelo, se dispone alternativamente de StartFindService con InstanceSpecifier [SWS_CM_00623].

El método estático StartFindService de la clase proxy inicia la búsqueda continua de instancias de servicio en función de un ara::core::InstanceSpecifier modelado [SWS_CM_00623]. En la llamada se pasan el InstanceSpecifier y una función de callback de tipo ara::com::FindServiceHandler [SWS_CM_00623]. Como valor de retorno, la función proporciona un ara::core::Result<ara::com::FindServiceHandle> [SWS_CM_00623], el cual pone a disposición un identificador de búsqueda para gestionar la búsqueda en caso de registro exitoso.

El tratamiento de errores se realiza mediante el ara::core::Result devuelto. Si se produce un error de comunicación subsanable o un error de comunicación segura en el binding de red, el resultado contiene el código de error ComErrc::kCommunicationFailure [SWS_CM_00623]. Además, se especifican violaciones concretas: InvalidHandlerViolation si el manejador proporcionado no es válido o es nulo, InsufficientPermissionsViolation en caso de falta de permisos por grant enforcement, así como violaciones de modelado como InstanceSpecifierMappingIntegrityViolation o PortInterfaceMappingViolation [SWS_CM_00623].

En cuanto a concurrencia y restricciones, la función está declarada como noexcept y especificada como segura frente a excepciones [SWS_CM_00623]. Es de suponer que la ejecución del manejador registrado se lleve a cabo de forma asíncrona por parte de la gestión de comunicaciones tan pronto como se detecten instancias de servicio adecuadas en el sistema. Pregunta Q-79fb3ff78d517714 (abierta)

En la interacción con interfaces relacionadas, son de aplicación los siguientes puntos:

• El ara::com::FindServiceHandle devuelto debe conservarse para finalizar la búsqueda en curso mediante StopFindService [SWS_CM_00125] y detener la recepción de posteriores notificaciones.
• Los identificadores proporcionados a través del callback (HandleType) sirven típicamente para instanciar el objeto proxy mediante el método de factoría Create [SWS_CM_10438].
• Como alternativa a la búsqueda a través de un InstanceSpecifier, también se puede iniciar una búsqueda con un ara::com::InstanceIdentifier [SWS_CM_00123].

El método SetServiceStateChangeHandler sirve en una instancia de proxy para registrar una función de callback destinada a supervisar cambios de disponibilidad del respectivo servicio ([SWS_CM_01074], SWS CommunicationManagement §8.3.8.2.4.6 «SetServiceStateChangeHandler(ara::com::ServiceStateHandler)»). La gestión de comunicación llama a este manejador en cuanto cambia el estado de disponibilidad del servicio (ServiceState) ([SWS_CM_01074]).

Como parámetro se pasa un objeto de función del tipo ara::com::ServiceStateHandler, especificado como std::function<void(ServiceState)> ([SWS_CM_01072]). La función no posee valor de retorno. Un manejador ya registrado puede sobrescribirse durante el tiempo de ejecución mediante una nueva llamada ([SWS_CM_01074]).

En cuanto al tratamiento de errores, la función está declarada como segura frente a excepciones (noexcept) ([SWS_CM_01074]). Si el invocable pasado no existe o es nulo, se produce la infracción InvalidHandlerViolation ([SWS_CM_01074]).

En lo que respecta al entorno de ejecución, [SWS_CM_01074] representa la interfaz básica. Dado que aquí no se puede pasar ningún ejecutor, el callback probablemente se ejecute en el contexto de hilo interno de la gestión de comunicación. Pregunta Q-7833435e7aa1da9f (abierta) En caso de que se requiera una ejecución en un contexto de aplicación específico, se encuentra disponible de forma alternativa la variante de plantilla sobrecargada con un executor según [SWS_CM_01076] (SWS CommunicationManagement §8.3.8.2.4.5 «SetServiceStateChangeHandler(ara::com::ServiceStateHandler, ExecutorT&&)»).

Uso y contexto de llamada

El método de plantilla SetServiceStateChangeHandler sirve, en la clase de proxy generada <SI-Namespace>::proxy::<SI>Proxy, para registrar un callback destinado a supervisar la disponibilidad del servicio [SWS_CM_01076]. La función acepta dos parámetros AUTOSAR_AP_SWS_CommunicationManagement §8.3.8.2.4.5 «SetServiceStateChangeHandler(ara::com::ServiceStateHandler, ExecutorT&&)»:

• handler: Un functor de tipo ara::com::ServiceStateHandler (definido como std::function<void(ServiceState)>) que se invoca con cada cambio del estado de disponibilidad [SWS_CM_01072], [SWS_CM_01074].
• executor: Un contexto de ejecución del tipo de plantilla ExecutorT conforme a [SWS_CM_11360], en el cual se ejecuta el manejador registrado [SWS_CM_01076].

La función no tiene valor de retorno (void) [SWS_CM_01076].

Tratamiento de errores y seguridad frente a excepciones

La función está declarada como noexcept y especificada como segura frente a excepciones (exception safe) [SWS_CM_01076]. Si el manejador invocable proporcionado no existe o es null, se genera una InvalidHandlerViolation [SWS_CM_01076].

Concurrencia y restricciones

Un manejador registrado puede sobrescribirse en tiempo de ejecución [SWS_CM_01074]. Dado que la ejecución se realiza a través del objeto executor proporcionado [SWS_CM_01076], la notificación presumiblemente se procesa de forma asíncrona en el contexto de subproceso o de despacho (dispatch) suministrado por el usuario. Pregunta Q-349c5224c3b9cc20 (abierta)

Interacción

El método amplía la variante elemental [SWS_CM_01074] con la especificación explícita del contexto de ejecución [SWS_CM_01076]. Para la integración se requiere la cabecera <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h, mientras que el tipo de manejador procede de ara/com/types.h [SWS_CM_01072].

El método estático de plantilla StartFindService inicia la monitorización asíncrona en segundo plano para localizar instancias de un servicio a partir de un ara::com::InstanceIdentifier ([SWS_CM_11352], EXP_ARAComAPI §5.3.3 «Proxy Class API’s»). Además de la instancia de destino (instance conforme a [SWS_CM_00122]), se registran una función de devolución de llamada (handler conforme a [SWS_CM_00123]) y un contexto de ejecución (executor del tipo de plantilla ExecutorT conforme a [SWS_CM_11360]) ([SWS_CM_11352]). En este proceso, las notificaciones de devolución de llamada probablemente se procesen en el contexto de hilo o tarea del executor transferido ([SWS_CM_11352]). Pregunta Q-1db520123c1e49a4 (abierta)

Como valor de retorno, la llamada proporciona un ara::com::FindServiceHandle ([SWS_CM_11352]). Este manejador identifica la actividad de búsqueda en curso y se necesita para finalizar explícitamente más adelante la actividad en segundo plano mediante [SWS_CM_00125] (StopFindService) (EXP_ARAComAPI §5.3.3 «Proxy Class API’s»). Los identificadores de servicio (HandleType) recibidos a través de la devolución de llamada registrada sirven posteriormente para la construcción de las instancias proxy correspondientes ([SWS_CM_00131]).

La función está declarada como noexcept y especificada como segura frente a excepciones (exception safe) ([SWS_CM_11352]). Se definen las siguientes violaciones en tiempo de ejecución (Violations):

• InvalidHandlerViolation: Se produce si la función de manejador transferida es inválida o corresponde a null ([SWS_CM_11352]).
• InsufficientPermissionsViolation: Se produce si el sistema de autorizaciones deniega el acceso (Grant Enforcement) ([SWS_CM_11352]).

Si en su lugar se debe buscar un servicio a través de un ara::core::InstanceSpecifier basado en modelos, se encuentra disponible alternativamente la variante de función [SWS_CM_11365].

La función estática de plantilla StartFindService inicia la búsqueda continua y asíncrona de instancias de servicio a partir de un ara::core::InstanceSpecifier mediante el registro de un manejador de notificaciones en un contexto de ejecución transferido [SWS_CM_11365]. A diferencia de las búsquedas únicas síncronas, inicia una actividad en segundo plano para supervisar la disponibilidad del servicio y devuelve un ara::com::FindServiceHandle EXP_ARAComAPI §5.3 «Proxy Class APIs».

Parámetros y ejecución

La función acepta tres parámetros [SWS_CM_11365]:

• handler: Función de devolución de llamada de tipo ara::com::FindServiceHandler conforme a [SWS_CM_00123], a la que se llama ante cambios en la disponibilidad de la instancia.
• instance: El ara::core::InstanceSpecifier a buscar conforme a [SWS_CM_00123].
• executor: Un contexto de ejecución del tipo de plantilla ExecutorT conforme a [SWS_CM_11360]. Interpretación: Es probable que el argumento de plantilla ExecutorT determine en qué contexto de hilo o tarea se ejecutará la devolución de llamada registrada. Pregunta Q-6d46f67d536a391e (abierta)

Tratamiento de errores y condiciones límite

La firma está declarada como noexcept y especificada como exception safe [SWS_CM_11365]. En la especificación se definen violaciones funcionales (Violations): InstanceSpecifierMappingIntegrityViolation (resolución fallida en el contexto de Executable o no es un PortPrototype), PortInterfaceMappingViolation y ProcessMappingViolation (asignaciones de PortInterface no coincidentes), InstanceSpecifierAlreadyInUseViolation, InvalidHandlerViolation (manejador inválido o inexistente), así como InsufficientPermissionsViolation en caso de falta de autorización de acceso [SWS_CM_11365].

Interacción

El FindServiceHandle obtenido sirve para finalizar de forma controlada la monitorización continua en segundo plano transfiriéndolo a StopFindService [SWS_CM_00125]. Los identificadores notificados al manejador se utilizan para instanciar proxies de servicio concretos mediante Proxy(handle) [SWS_CM_00131]. Para búsquedas mediante ara::com::InstanceIdentifier existe una sobrecarga alternativa [SWS_CM_11352].

La función estática StopFindService de la clase proxy finaliza una búsqueda de servicio asincrónica iniciada previamente con StartFindService y detiene la recepción de nuevas notificaciones para el manejador suministrado [SWS_CM_00125]. Con ello se suspende la actividad en segundo plano en curso para la monitorización de la disponibilidad del servicio por parte del enlace técnico AP EXP ARAComAPI §5.3 «Proxy Class API’s».

Uso y semántica

• Parámetros: como parámetro de entrada, la función espera un ara::com::FindServiceHandle obtenido previamente mediante uno de los métodos StartFindService ([SWS_CM_00123], [SWS_CM_00623], [SWS_CM_11352], [SWS_CM_11365], [SWS_CM_00125]).
• Valor devuelto y seguridad frente a fallos: la función no tiene valor devuelto (void), está declarada con noexcept y especificada como segura frente a excepciones [SWS_CM_00125].
• Concurrencia y contexto de llamada: una llamada a StopFindService está expresamente permitida también directamente dentro de la función de callback definida por el usuario FindServiceHandler [SWS_CM_00383] AP EXP ARAComAPI §5.3 «Proxy Class API’s». Para este propósito, se pasa al manejador el respectivo FindServiceHandle como parámetro [SWS_CM_00383]. Dado que el callback en sí no necesita ser reentrante, el implementador del binding debe garantizar la serialización de las llamadas sucesivas AP EXP ARAComAPI §5.3 «Proxy Class API’s».

La función miembro UnsetServiceStateChangeHandler forma parte de la clase proxy generada en el espacio de nombres <SI-Namespace>::proxy::<SI>Proxy conforme a [SWS_CM_01075] (AUTOSAR_AP_SWS_CommunicationManagement §8.3.8.2.4.12 «UnsetServiceStateChangeHandler»). Se incluye mediante el encabezado #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h".

En cuanto a uso, comportamiento y concurrencia, rigen las siguientes especificaciones:

• Uso: El método posee la signatura void UnsetServiceStateChangeHandler() noexcept;. No recibe parámetros y no devuelve ningún valor de retorno. Interpretación: Según el identificador y la referencia a [SWS_CM_01074], la llamada sirve para restablecer o cancelar el registro de un manejador de callback registrado previamente para cambios en el estado del servicio en la instancia de proxy. Pregunta Q-6eb71298a6f37ad9 (abierta)
• Tratamiento de errores y seguridad frente a excepciones: La operación está declarada como noexcept y especificada como exception safe ([SWS_CM_01075]). No lanza excepciones ni devuelve códigos de error al invocador.
• Interacción y condiciones de contorno: La semántica funcional remite a la definición en [SWS_CM_01074]. Interpretación: La cancelación del registro probablemente surta efecto de forma síncrona, de modo que, tras el retorno de la llamada a la función, no se entreguen más transiciones de estado a través del callback anterior. Pregunta Q-31348a50d9be537d (abierta)