clase ara::exec::ExecutionClient

La clase ara::exec::ExecutionClient sirve a los procesos de aplicación para notificar de forma vinculante su estado de ejecución interno a Execution Management ([SWS_EM_02003]). Durante la inicialización, asume además la interceptación de la señal SIGTERM y la reenvía a un manejador de finalización definido por el usuario en un subproceso en segundo plano ([SWS_EM_02562]). Como objeto de solo movimiento (move-only), la instancia vincula estrictamente el tratamiento de señales a su ciclo de vida y restaura el estado de señal anterior durante la destrucción. Quienes realizan llamadas deben asegurarse de que la devolución de llamada registrada permanezca invocable durante todo el tiempo de vida de la instancia.

más ›

Contexto

La clase ara::exec::ExecutionClient sirve para que los procesos en la Adaptive Platform notifiquen su estado de ejecución interno a Execution Management ([SWS_EM_02003]). Actúa como una interfaz estandarizada entre la aplicación en ejecución y la gestión central de procesos. Además de reenviar las transiciones de estado, la instancia asume la responsabilidad del tratamiento de la señal del sistema operativo SIGTERM ([SWS_EM_02562], [SWS_EM_02002]). Al recibir la señal, ejecuta una devolución de llamada definida por el usuario en un hilo en segundo plano independiente para permitir una finalización ordenada de la aplicación ([SWS_EM_02562]). Interpretación: Es probable que el sistema operativo o Execution Management transmitan la señal SIGTERM al proceso cuando se solicite la finalización de la unidad de ejecución. Pregunta Q-51eee947d01ae8b4 (abierta)

Diagrama de contexto: interacción entre el proceso de aplicación, ExecutionClient, Execution Management y el mecanismo de señales. Fuentes: [SWS_EM_02003], [SWS_EM_02562], [SWS_EM_02002].

Ciclo de vida

La instanciación de ara::exec::ExecutionClient se realiza opcionalmente a través del método de fábrica estático Create ([SWS_EM_02562]) o mediante el constructor regular ([SWS_EM_02560]). Mientras que Create es seguro frente a excepciones (noexcept) y devuelve el resultado encapsulado en un ara::core::Result ([SWS_EM_02562]), el constructor regular está declarado como noexcept(false) ([SWS_EM_02560]). Ambas vías de creación esperan como parámetro una devolución de llamada invocable std::function<void()> (terminationHandler). Esta devolución de llamada debe permanecer válida e invocable durante toda la vida útil de la instancia de ExecutionClient ([SWS_EM_02562], [SWS_EM_02560]).

En cuanto a la propiedad, la clase está diseñada como de solo movimiento (move-only): el constructor de copia ([SWS_EM_02563]) y el operador de asignación por copia ([SWS_EM_02564]) están explícitamente eliminados (delete). La transferencia de instancias solo es posible a través del constructor de movimiento ([SWS_EM_02580]) y del operador de asignación por movimiento ([SWS_EM_02581]), siendo ambos seguros frente a excepciones (noexcept), pero no seguros para subprocesos. El método de fábrica Create y el propio constructor se consideran seguros para subprocesos ([SWS_EM_02562], [SWS_EM_02560]).

El destructor ~ExecutionClient() está definido como noexcept ([SWS_EM_02002]) y no es seguro para subprocesos. Al destruir la instancia, se devuelve la responsabilidad de la señal SIGTERM: el destructor restablece el manejador de señales para SIGTERM al estado original que estaba activo antes de la instanciación ([SWS_EM_02002]).

Ruta de uso

El flujo regular se divide en inicialización, transmisión de estado y terminación ordenada:

• Creación: al inicio del tiempo de ejecución del proceso, la instancia se inicializa a través de Create, pasándose el manejador de terminación ([SWS_EM_02562]). Normalmente, este manejador establece un flag o señaliza primitivas de sincronización para desbloquear los hilos en ejecución.
• Notificación de estado: tan pronto como el proceso está listo, notifica su estado de ejecución a Execution Management a través de ReportExecutionState ([SWS_EM_02003]). La llamada es segura para subprocesos y puede realizarse desde diferentes hilos de trabajo.
• Recepción de señal y terminación: si se recibe una señal SIGTERM durante el tiempo de ejecución, ExecutionClient activa el terminationHandler registrado de forma asíncrona en un hilo en segundo plano ([SWS_EM_02562]). El proceso completa las tareas abiertas de manera ordenada.
• Destrucción: al salir del ámbito de validez, el destructor restaura la configuración de señal original ([SWS_EM_02002]).

Diagrama de secuencia: flujo desde la creación pasando por la notificación de estado hasta la terminación controlada por señales. Fuentes: [SWS_EM_02562], [SWS_EM_02003], [SWS_EM_02002].

Escenarios de error

Al utilizar ExecutionClient, se cubren diferentes situaciones de error mediante códigos de error de ara::exec::ExecErrc:

• ara::exec::ExecErrc::kInvalidArgument: se produce durante la instanciación mediante Create ([SWS_EM_02562]) o mediante el constructor regular ([SWS_EM_02560]) si el objeto terminationHandler transferido no contiene ninguna función invocable. El sistema aplica semántica de reversión (rollback); para solucionarlo, debe transferirse un invocable (callable) válido.
• ara::exec::ExecErrc::kNoCommunication: puede ocurrir tanto en la creación ([SWS_EM_02562], [SWS_EM_02560]) como en ReportExecutionState ([SWS_EM_02003]) cuando existe un error de comunicación entre el proceso de aplicación y Execution Management (p. ej., falta de confirmación de recepción del mensaje). En este caso no se aplica semántica de reversión; como medida de recuperación está previsto un nuevo intento de llamada.
• ara::exec::ExecErrc::kInvalidTransition: es devuelto por ReportExecutionState ([SWS_EM_02003]) si se solicita un cambio de estado no permitido, por ejemplo, una nueva notificación de un estado ya activo como kRunning. Dado que el estado ya ha sido notificado, no se requiere una nueva transmisión (semántica de reversión).