Leer el artículo original Node-API Parte 11 Pasar trabajo priorizado desde C++ nativo a ArkTS guía paso a paso
Introducción
Cuando tu aplicación HarmonyOS NEXT necesita enviar trabajo desde un hilo nativo C o C++ de vuelta al bucle de eventos de ArkTS, la extensión de Node API napi_call_threadsafe_function_with_priority es la herramienta más directa y segura. Se apoya en el mecanismo de thread safe function tradicional y añade dos controles extra prioridad de la tarea y posición en la cola cabeza o cola. Con esto afinas la importancia de cada trabajo y cómo se mezcla en la cola de mensajes de ArkTS sin bloquearte con mutex o condiciones de carrera.
Por qué usar un TSFN con prioridad
Experiencia fluida Un reproductor puede tratar callbacks de audio como inmediatos, pings de analítica como bajos y generación de miniaturas como inactivos para que la interfaz no se atasque.
Orden determinista A veces quieres que un pico de trabajo urgente se cuele al frente encolar en la cabeza mientras que las actualizaciones rutinarias esperan su turno encolar en la cola.
Entrega de contexto sin copias Las TSFN permiten pasar un puntero opaco void* hasta ArkTS sin serializar datos pesados.
Cómo fluye en la práctica
1 Hilo ArkTS preparación Creas una TSFN ligada a un callback ArkTS o JavaScript y levantas un async work que ejecutará en otro hilo.
2 Hilo trabajador ejecución Dentro de ExecuteWork llamas a la API con prioridad tantas veces como necesites combinando prioridad y posición de cola.
3 Hilo ArkTS entrega ArkTS va drenando su cola e invoca tu callback en el orden implícito por prioridad más cabeza o cola. Si necesitas leer el retorno desde nativo puedes extraerlo con napi_get_value_int32 u otros.
4 Limpieza Libera la TSFN con napi_release_threadsafe_function y elimina el async work cuando termine todo.
Paso a paso integración en proyecto
1 Declaración de API en index.d.ts
export const callThreadSafeWithPriority: (cb: (a: number, b: number) => number) => void
2 Núcleo nativo en C++ visión general
El módulo define una estructura CallbackData que guarda la TSFN y el async work. CallJs siempre corre en el hilo ArkTS y construye dos números 12 y 15, llama al callback JS y opcionalmente lee el entero de retorno. ExecuteWork publica cinco tareas con prioridades distintas usando napi_call_threadsafe_function_with_priority en este orden 1 idle a cola, 2 low a cola, 3 high a cola, 4 immediate a cola, 5 high a cabeza por lo que la quinta se ejecuta antes que la tercera. WorkComplete libera la TSFN y elimina el async work. La función nativa CallThreadSafeWithPriority crea la TSFN, crea el async work y lo encola sin devolver resultado síncrono. El módulo se registra con el nombre entry para importarlo desde ArkTS.
3 Uso en ArkTS Index.ets
Importas la librería nativa libentry.so, declaras un callback que suma dos números y registra logs, y llamas a testNapi.callThreadSafeWithPriority(callback) en el onClick de un componente. La lógica ArkTS recibe múltiples invocaciones del callback según la prioridad y la posición de cola configuradas en C++.
4 Configuración build profile
En build-profile.json5 activa el modo stage, configura externalNativeOptions para apuntar al CMakeLists, define abi arm64-v8a y x86_64 y habilita los ajustes de release según tu necesidad. Si usas opciones de Ark activa runtimeOnly en arkOptions para reducir el peso en tiempo de ejecución.
Consejos prácticos y trampas comunes
Consejo agrupa con cabeza Divide el trabajo por afinidad y agrupa las tareas de baja prioridad en un único worker para no inundar con mensajes idle.
Consejo callbacks ligeros La parte ArkTS debe ser muy rápida el bucle de eventos seguirá bloqueándose si el JS es pesado sin importar la prioridad.
Error liberación olvidada Si no liberas la TSFN mantienes vivo su entorno y puedes provocar fallos del runtime al recargar. Libérala en el callback de finalización.
Error cruces de entorno No pases una TSFN entre instancias distintas de napi_env. El comprobador multihilo del runtime abortará.
Cuándo no usarlo
Si todas las tareas son triviales o ya tienen un orden natural, usa napi_call_threadsafe_function estándar por simplicidad. Si mueves datos pesados quizá te convenga más un ring buffer compartido o un canal IPC fuera de Node API.
Conclusión
napi_call_threadsafe_function_with_priority es una ampliación pequeña pero potente que aporta a tu add on nativo la finura de un planificador casi en tiempo real sin dolores de concurrencia. Al asignar un nivel de prioridad y decidir si encolas al inicio o al final mantienes el trabajo crítico ágil y dejas que las tareas de fondo esperen de manera ordenada con seguridad de hilos total sobre el runtime ArkTS de HarmonyOS NEXT.
Recursos adicionales
Documento oficial sobre TSFN con prioridad
Resumen de desarrollo NDK para HarmonyOS NEXT
Acerca de Q2BSTUDIO
En Q2BSTUDIO desarrollamos aplicaciones a medida y software a medida para ecosistemas móviles y de escritorio incluyendo HarmonyOS NEXT. Integramos módulos nativos C++ con ArkTS, optimizamos el rendimiento con TSFN prioritarias y diseñamos arquitecturas seguras y escalables. Somos especialistas en inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA y power bi. Si buscas un partner para construir experiencias nativas potentes te invitamos a conocer nuestro servicio de desarrollo de software y aplicaciones a medida multiplataforma y cómo aplicamos inteligencia artificial en productos de nueva generación.
Créditos Autor Bunyamin Eymen Alagoz