1# libuv 2 3## 简介 4 5[libuv](http://libuv.org/)是一个跨平台库，基于事件驱动来实现异步I/O，适用于网络编程和文件系统操作。它是Node.js的核心库之一，也被其他语言的开发者广泛使用。 6 7## 支持的能力 8 9[libuv](http://libuv.org/)实现了跨平台的基于事件驱动的异步I/O。 10 11支持标准库接口。 12 13## 引入libuv能力 14 15如果开发者需要使用libuv相关功能，首先请添加头文件： 16 17```c 18#include <uv.h> 19``` 20 21其次在CMakeLists.txt中添加以下动态链接库： 22 23``` 24libuv.so 25``` 26 27## 接口列表 28 29详见[libuv支持的API文档](http://docs.libuv.org/en/v1.x/api.html)。 30 31## OpenHarmony引入libuv的背景 32 33在OpenHarmony的早期版本中，为了兼容node的生态，将node的Node-API引入到系统中，方便node开发者快速接入OpenHarmony，扩展自己的js接口。同时引入了node的事件循环实现库——libuv。 34 35### 演进方向 36 37随着 OpenHarmony 的逐步完善，我们计划在未来的版本中，逐步将应用模型中的事件循环归一，并增强 OpenHarmony 自身的事件循环，以解决许多双 loop 机制下的调度问题，并为开发者提供更加完善的任务优先级、插队等与任务主循环交互的方法。 38 39开发者应尽可能避免在 `napi_get_uv_event_loop` 接口(已在API12中标记废弃)获取的应用主 loop 上使用 libuv 的 ndk 进行操作，因为这可能会带来各种问题，并给未来的兼容性变更带来大量的工作量。 40 41如果开发者希望跟主线程事件循环交互，比如插入任务等，应当使用[Node-API提供的接口](../../napi/napi-data-types-interfaces.md)。 42 43OpenHarmony 还将长期通过Node-API来为开发者提供和主线程交互及扩展js接口的能力，但会屏蔽实现层使用的事件循环。尽管我们在API12中给`napi_get_uv_event_loop`接口标记了废弃，但Node-API的主要功能接口将会长期维护，并保证与node的原生行为一致，来保证熟悉node.js的扩展机制的开发者方便地将自己的已有代码接入到OpenHarmony中来。 44 45如果您对 libuv 非常熟悉，并自信能够处理好所有的内存管理和多线程问题，您仍可以像使用原生 libuv 一样，自己启动线程，并在上面使用 libuv 完成自己的业务。在没有特殊版本要求的情况下，您不需要额外引入 libuv库到您的应用工程中。 46 47### 当前问题和解决方案 48 49根据现有机制，一个线程上只能存在一个事件循环，为了适配系统应用的主事件循环，在主线程上的js环境中，uvloop中的事件处理是由主事件循环监听其fd，触发一次`uv_run`来驱动的。因此部分依赖uvloop始终循环的功能无法生效。 50 51基于上述，比较常用的场景和解决方案有： 52 53#### 场景一、在JS主线程抛异步任务到工作线程执行，在主线程中执行JS代码处理返回结果 54 55**错误示例：** 56 57在native层直接通过调用`napi_get_uv_event_loop`接口获取系统loop，调用libuv NDK接口实现相关功能。 58 59```cpp 60#include "napi/native_api.h" 61#include "uv.h" 62#define LOG_DOMAIN 0X0202 63#define LOG_TAG "MyTag" 64#include <hilog/log.h> 65#include <thread> 66#include <sys/eventfd.h> 67#include <unistd.h> 68 69static void execute(uv_work_t *work) { 70 OH_LOG_INFO(LOG_APP, "ohos in execute"); 71} 72 73static void complete(uv_work_t *work, int status) { 74 OH_LOG_INFO(LOG_APP, "ohos in complete"); 75 delete work; 76} 77static napi_value Add(napi_env env, napi_callback_info info) 78{ 79 napi_value work_name; 80 uv_loop_s *loop = nullptr; 81 /* 获取应用js主线程的uv_loop */ 82 napi_get_uv_event_loop(env, &loop); 83 uv_work_t *work = new uv_work_t; 84 int ret = uv_queue_work(loop, work, execute, complete); 85 if (ret != 0) { 86 OH_LOG_INFO(LOG_APP, "delete work"); 87 delete work; 88 } 89 return 0; 90} 91 92EXTERN_C_START 93static napi_value Init(napi_env env, napi_value exports){ 94 napi_property_descriptor desc[] = {{"add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr}}; 95 napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 96 return exports; 97} 98EXTERN_C_END 99 100static napi_module demoModule = { 101 .nm_version = 1, 102 .nm_flags = 0, 103 .nm_filename = nullptr, 104 .nm_register_func = Init, 105 .nm_modname = "entry", 106 .nm_priv = ((void *)0), 107 .reserved = {0}, 108}; 109 110extern "C" __attribute__((constructor)) void RegisterEntryModule(void){ 111 napi_module_register(&demoModule); 112} 113``` 114 115**正确示例：** 116 117可通过`napi_create_async_work`、`napi_queue_async_work`搭配使用。 118 119```cpp 120#include "napi/native_api.h" 121#include "uv.h" 122#define LOG_DOMAIN 0X0202 123#define LOG_TAG "MyTag" 124#include <hilog/log.h> 125#include <thread> 126#include <sys/eventfd.h> 127#include <unistd.h> 128uv_loop_t *loop; 129napi_value jsCb; 130int fd = -1; 131 132static napi_value Add(napi_env env, napi_callback_info info) 133{ 134 napi_value work_name; 135 napi_async_work work; 136 napi_create_string_utf8(env, "ohos", NAPI_AUTO_LENGTH, &work_name); 137 /* 第四个参数是异步线程的work任务，第五个参数为主线程的回调 */ 138 napi_create_async_work(env, nullptr, work_name, [](napi_env env, void* data){ 139 OH_LOG_INFO(LOG_APP, "ohos in execute"); 140 }, [](napi_env env, napi_status status, void *data){ 141 /* 不关心具体实现 */ 142 OH_LOG_INFO(LOG_APP, "ohos in complete"); 143 napi_delete_async_work(env, (napi_async_work)data); 144 }, nullptr, &work); 145 /* 通过napi_queue_async_work触发异步任务执行 */ 146 napi_queue_async_work(env, work); 147 return 0; 148} 149 150EXTERN_C_START 151static napi_value Init(napi_env env, napi_value exports){ 152 napi_property_descriptor desc[] = {{"add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr}}; 153 napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 154 return exports; 155} 156EXTERN_C_END 157 158static napi_module demoModule = { 159 .nm_version = 1, 160 .nm_flags = 0, 161 .nm_filename = nullptr, 162 .nm_register_func = Init, 163 .nm_modname = "entry", 164 .nm_priv = ((void *)0), 165 .reserved = {0}, 166}; 167 168extern "C" __attribute__((constructor)) void RegisterEntryModule(void){ 169 napi_module_register(&demoModule); 170} 171``` 172 173#### 场景二、在native侧向应用主循环抛fd事件，接口无法生效 174 175由于应用主循环仅仅接收fd事件，在监听了uvloop中的backend_fd后，只有该fd事件被触发才会执行一次`uv_run`。这就意味着，在应用主循环中调用uv接口，如果不触发一次fd事件，`uv_run`将永远不会被执行，最后导致libuv的接口正常调用时不生效（仅当应用中没有触发uvloop中的fd事件时）。 176 177**错误示例：** 178 179我们以`uv_poll_start`接口举例，来说明在OpenHarmony中，我们像使用原生libuv一样调用`uv_poll_start`接口时无法生效的问题。 180 181```cpp 182#include "napi/native_api.h" 183#include "uv.h" 184#define LOG_DOMAIN 0X0202 185#define LOG_TAG "MyTag" 186#include <hilog/log.h> 187#include <thread> 188#include <sys/eventfd.h> 189#include <unistd.h> 190uv_loop_t *loop; 191napi_value jsCb; 192int fd = -1; 193void poll_handler(uv_poll_t* handle,int status, int events){ 194 OH_LOG_INFO(LOG_APP, "ohos poll print"); 195} 196static napi_value TestClose(napi_env env, napi_callback_info info){ 197 std::thread::id this_id = std::this_thread::get_id(); 198 OH_LOG_INFO(LOG_APP, "ohos thread id : %{public}ld\n", this_id); 199 size_t argc = 1; 200 napi_value workBname; 201 202 napi_create_string_utf8(env, "test", NAPI_AUTO_LENGTH, &workBname); 203 204 napi_get_cb_info(env, info, &argc, &jsCb, nullptr, nullptr); 205 // 获取事件循环 206 napi_get_uv_event_loop(env, &loop); 207 // 创建一个eventfd 208 fd = eventfd(0, 0); 209 OH_LOG_INFO(LOG_APP, "fd is %{public}d\n",fd); 210 uv_poll_t* poll_handle = new uv_poll_t; 211 // 初始化一个poll句柄，并将其与eventfd关联 212 uv_poll_init(loop, poll_handle, fd); 213 // 开始监听poll事件 214 uv_poll_start(poll_handle, UV_READABLE, poll_handler); 215 // 创建一个新线程，向eventfd写入数据 216 std::thread mythread([](){ 217 for (int i = 0; i < 8; i++){ 218 int value = 10; 219 int ret = eventfd_write(fd, value); 220 if (ret == -1){ 221 OH_LOG_INFO(LOG_APP, "write failed!\n"); 222 continue; 223 } 224 } 225 }); 226 mythread.detach(); 227 return 0; 228} 229EXTERN_C_START 230static napi_value Init(napi_env env, napi_value exports){ 231 napi_property_descriptor desc[] = {{"testClose", nullptr, TestClose, nullptr, nullptr, nullptr, napi_default, nullptr}}; 232 napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 233 return exports; 234} 235EXTERN_C_END 236 237static napi_module demoModule = { 238 .nm_version = 1, 239 .nm_flags = 0, 240 .nm_filename = nullptr, 241 .nm_register_func = Init, 242 .nm_modname = "entry", 243 .nm_priv = ((void *)0), 244 .reserved = {0}, 245}; 246 247extern "C" __attribute__((constructor)) void RegisterEntryModule(void){ 248 napi_module_register(&demoModule); 249} 250``` 251 252在上述代码中，流程如下： 253 2541. 首先通过`napi_get_uv_event_loop`接口获取到应用主线程的uvloop。 2552. 然后创建一个eventfd。 2563. 初始化uv_poll_t，并启动该句柄使其生效，在eventfd可读时触发回调函数`poll_handler`。 2574. 新开一个线程，向eventfd里写入字符。 258 259执行上述代码，poll_handler并不能正常打印。这是由于应用主线程是靠fd驱动来执行`uv_run`的，而非以UV_RUN_DEFAULT模式来进行循环。尽管uvloop中的backend_fd已经被event_handler监听，但是当执行`uv_poll_start`的时候，fd并未通过`epoll_ctl`加入到backend_fd中被其监听，**而是在下一次`uv_run`中的`uv__io_poll`这个函数才会执行`epoll_ctl`函数。因此，如果应用进程中没有其他触发backend_fd事件的时候，libuv接口的正常使用可能不会达到开发者的预期。** 260 261**临时方案：** 262 263在当下的系统版本中，我们并不推荐开发者直接通过`napi_get_uv_event_loop`获取应用主线程的uvloop进行业务逻辑的开发。如果当前Node-API的接口无法满足开发者的开发需求，确有必要使用libuv来实现业务功能，为了使libuv接口在主线程上生效，我们可以在调用类似*uv_xxx_start*后，执行一次`uv_async_send`的方式来主动触发应用主线程执行一次`uv_run`。这样可以保证该接口生效并正常执行。 264 265针对上述无法生效的代码示例，可以修改如下使其生效： 266 267```cpp 268#include "napi/native_api.h" 269#include "uv.h" 270#define LOG_DOMAIN 0x0202 271#define LOG_TAG "MyTag" 272#include <hilog/log.h> 273#include <thread> 274#include <sys/eventfd.h> 275#include <unistd.h> 276uv_loop_t *loop; 277napi_value jsCb; 278int fd = -1; 279void poll_handler(uv_poll_t* handle,int status, int events){ 280 OH_LOG_INFO(LOG_APP, "ohos poll print"); 281} 282static napi_value TestClose(napi_env env, napi_callback_info info){ 283 std::thread::id this_id = std::this_thread::get_id(); 284 OH_LOG_INFO(LOG_APP, "ohos thread id : %{public}ld\n", this_id); 285 size_t argc = 1; 286 napi_value workBName; 287 288 napi_create_string_utf8(env, "test", NAPI_AUTO_LENGTH, &workBName); 289 290 napi_get_cb_info(env, info, &argc, &jsCb, nullptr, nullptr); 291 292 napi_get_uv_event_loop(env, &loop); 293 294 fd = eventfd(0, 0); 295 OH_LOG_INFO(LOG_APP, "fd is %{public}d\n",fd); 296 uv_poll_t* poll_handle = new uv_poll_t; 297 uv_poll_init(loop, poll_handle, fd); 298 uv_poll_start(poll_handle, UV_READABLE, poll_handler); 299 300 // 主动触发一次fd事件，让主线程执行一次uv_run 301 uv_async_send(&loop->wq_async); 302 303 std::thread mythread([](){ 304 for (int i = 0; i < 8; i++){ 305 int value = 10; 306 int ret = eventfd_write(fd, value); 307 if (ret == -1){ 308 OH_LOG_INFO(LOG_APP, "write failed!\n"); 309 continue; 310 } 311 } 312 }); 313 mythread.detach(); 314 return 0; 315} 316 317EXTERN_C_START 318static napi_value Init(napi_env env, napi_value exports){ 319 napi_property_descriptor desc[] = {{"testClose", nullptr, TestClose, nullptr, nullptr, nullptr, napi_default, nullptr}}; 320 napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 321 return exports; 322} 323EXTERN_C_END 324 325static napi_module demoModule = { 326 .nm_version = 1, 327 .nm_flags = 0, 328 .nm_filename = nullptr, 329 .nm_register_func = Init, 330 .nm_modname = "entry", 331 .nm_priv = ((void *)0), 332 .reserved = {0}, 333}; 334 335extern "C" __attribute__((constructor)) void RegisterEntryModule(void){ 336 napi_module_register(&demoModule); 337} 338``` 339 340## libuv使用指导 341 342**重要：libuv NDK中所有依赖`uv_run`的接口在当前系统的应用主循环中无法及时生效，并且可能会导致卡顿掉帧的现象。因此不建议直接在JS主线程上使用libuv NDK接口，对于异步任务执行及与使用线程安全函数与主线程通信，开发者可以直接调用Node-API接口来实现相关功能。** 343 344### libuv接口与Node-API接口对应关系 345 346当前OpenHarmony提供了一些Node-API接口，可以替换libuv接口的使用。主要包括异步任务相关接口，线程安全的函数调用接口。 347 348#### 异步任务接口 349 350当开发者需要执行一个比较耗时的操作但又不希望阻塞主线程执行时，libuv提供了底层接口`uv_queue_work`帮助开发者在异步线程中执行耗时操作，然后将结果回调到主线程上进行处理。 351 352在Node-API中，通常可以通过[napi_async_work](../../napi/use-napi-asynchronous-task.md)相关函数来实现异步开发的功能。 353 354相关函数为： 355 356```cpp 357// 创建一个新的异步工作 358// env：指向当前环境的指针 359// async_resource：可选的资源对象，用于跟踪异步操作 360// async_resource_name：可选的字符串，用于描述异步资源 361// execute：一个回调函数，它将在一个新的线程中执行异步操作 362// complete：一个回调函数，它将在异步操作完成后被调用 363// data：用户定义的数据，它将被传递给execute和complete回调函数 364// result：指向新创建的异步工作的指针 365napi_status napi_create_async_work(napi_env env, 366 napi_value async_resource, 367 napi_value async_resource_name, 368 napi_async_execute_callback execute, 369 napi_async_complete_callback complete, 370 void* data, 371 napi_async_work* result); 372 373// 将异步工作添加到队列中 374// env：指向当前环境的指针 375// work：指向异步工作的指针 376napi_status napi_queue_async_work(napi_env env, napi_async_work work); 377 378// 删除异步工作 379// env：指向当前环境的指针 380// work：指向异步工作的指针 381napi_status napi_delete_async_work(napi_env env, napi_async_work work); 382``` 383 384#### 跨线程共享和调用的线程安全函数 385 386当开发者想传入某个回调函数到应用主线程上时，libuv的实现方式一般使用`uv_async_t`句柄用于线程间通信。 387 388相关函数包含： 389 390- uv_async_init() 391- uv_async_send() 392 393Node-API与之对应的接口为[napi_threadsafe_function](../../napi/use-napi-thread-safety.md)相关函数。 394 395相关函数： 396 397```cpp 398// 用于创建一个线程安全的函数，该函数可以在多个线程中调用，而不需要担心数据竞争或其他线程安全问题 399// env：指向NAPI环境的指针，用于创建和操作Javascript值 400// func：指向JavaScript函数的指针 401// resource_name：指向资源名称的指针，这个名称将用于日志和调试 402// max_queue_size：一个整数，表示队列的最大大小，当队列满时，新的调用将被丢弃 403// initial_thread_count：一个整数，表示初始线程数，这些线程将在创建函数时启动 404// context：指向上下文的指针，这个上下文将被传递给call_js_func函数 405// call_js_func：指向回调函数的指针，这个函数将在Javascript函数被调用时被调用 406// finalize：指向finalize函数的指针，这个函数将在线程安全函数被销毁时被调用 407// result：指向napi_threadsafe_function结构的指针，这个结构将被填充为新创建的线程安全函数 408napi_status napi_create_threadsafe_function(napi_env env, 409 napi_value func, 410 const char* resource_name, 411 size_t max_queue_size, 412 size_t initial_thread_count, 413 void* context, 414 napi_threadsafe_function_call_js call_js_func, 415 napi_threadsafe_function_finalize finalize, 416 napi_threadsafe_function* result); 417 418// 获取一个线程安全的函数 419// function：指向线程安全函数的指针 420napi_status napi_acquire_threadsafe_function(napi_threadsafe_function function); 421 422// 调用一个线程安全的函数 423// function：指向线程安全函数的指针 424// data：用户数据 425napi_status napi_call_threadsafe_function(napi_threadsafe_function function, void* data); 426 427// 释放一个线程安全的函数 428// function：指向线程安全函数的指针 429napi_status napi_release_threadsafe_function(napi_threadsafe_function function); 430 431``` 432 433除此之外，如果开发者需要libuv其他原生接口来实现业务功能，为了让开发者正确使用libuv提供的接口能力，避免因为错误使用而陷入到问题当中。在后续章节，我们将逐步介绍libuv的一些基本概念和OpenHarmony系统中常用函数的正确使用方法，它仅仅可以保证开发者使用libuv接口的时候不会出现应用进程崩溃等现象。另外，我们还统计了在当前应用主线程上可以正常使用的接口，以及无法在应用主线程上使用的接口。 434 435### 接口汇总说明 436 437| 接口类型 | 接口汇总 | 438| ---- | ---- | 439| [loop概念及相关接口](#libuv中的事件循环) | uv_loop_init | 440| [loop概念及相关接口](#libuv中的事件循环) | uv_loop_close | 441| [loop概念及相关接口](#libuv中的事件循环) | uv_default_loop | 442| [loop概念及相关接口](#libuv中的事件循环) | uv_run | 443| [loop概念及相关接口](#libuv中的事件循环) | uv_loop_alive | 444| [loop概念及相关接口](#libuv中的事件循环) | uv_stop | 445| [Handle概念及相关接口](#libuv中的handles和requests) | uv_poll\_\* | 446| [Handle概念及相关接口](#libuv中的handles和requests) | uv_timer\_\* | 447| [Handle概念及相关接口](#libuv中的handles和requests) | uv_async\_\* | 448| [Handle概念及相关接口](#libuv中的handles和requests) | uv_signal\_\* | 449| [Handle概念及相关接口](#libuv中的handles和requests) | uv_fs\_\* | 450| [Request概念及相关接口](#libuv中的handles和requests) | uv_random | 451| [Request概念及相关接口](#libuv中的handles和requests) | uv_getaddrinfo | 452| [Request概念及相关接口](#libuv中的handles和requests) | uv_getnameinfo | 453| [Request概念及相关接口](#libuv中的handles和requests) | uv_queue_work | 454| [线程间通信原理及相关接口](#线程间通信) | uv_async_init | 455| [线程间通信原理及相关接口](#线程间通信) | uv_async_send | 456| [线程池概念及相关接口](#线程池) | uv_queue_work | 457 458### libuv单线程约束 459 460在OpenHarmony中使用libuv时，**务必注意：使用`uv_loop_init`接口初始化loop的线程和调用`uv_run`的线程应保持一致，称为loop线程，并且对uvloop的所有非线程安全操作，均需保证与loop同线程，否则将会有发生crash的风险**。OpenHarmony对libuv的使用有更严格的约束，对于非线程安全的函数，libuv将实现多线程检测机制，检测到多线程问题后输出警告日志。为了确保检测机制的准确性，协助开发者规避uv接口的不规范使用，我们建议在创建事件循环与执行uv_run始终保持在同一线程。 461 462#### 单线程约束 463 464根据loop来源的不同，可分为两种情况，即开发者创建loop和从env获取loop。 465 466##### 开发者创建loop 467 468开发者可以通过调用`uv_loop_new`创建loop或者`uv_loop_init`接口初始化loop，loop的生命周期由开发者自行维护。在这种情况下，如前文所述，需要保证`uv_run`执行在与创建/初始化loop操作相同的线程上，即loop线程上。此外，其余非线程安全操作，如timer、handle相关操作等，均需要在loop线程上进行。 469 470如果因为业务需要，必须在其他线程往loop线程抛任务，请使用`uv_async_send`函数实现，即在async句柄初始化时，注册一个回调函数，当调用`uv_async_send`时，在主线程上执行该回调函数。见如下代码示例： 471 472```cpp 473#include <napi/native_api.h> 474#include <uv.h> 475#define LOG_DOMAIN 0x0202 476#define LOG_TAG "MyTag" 477#include "hilog/log.h" 478#include <thread> 479#include <unistd.h> 480uv_async_t* async = new uv_async_t; 481 482// 执行创建定时器操作 483void timer_cb(uv_async_t* handle) { 484 auto loop = handle->loop; 485 uv_timer_t* timer = new uv_timer_t; 486 uv_timer_init(loop, timer); 487 488 uv_timer_start(timer, [](uv_timer_t* timer){ 489 uv_timer_stop(timer); 490 }, 1000, 0); 491 // 在适当的时机关闭async句柄 492 if (cond) { 493 uv_close((uv_handle_t*)handle, [](uv_handle_t* handle){ 494 delete (uv_async_t*)handle; 495 }) 496 } 497} 498 499// 初始化async句柄，绑定对应的回调函数 500static napi_value TestTimerAsync(napi_env env, napi_callback_info info) { 501 std::thread t([](){ // A线程，loop线程 502 uv_loop_t* loop = new uv_lppo_t; 503 // 开发者自己创建loop，请注意维护loop的生命周期 504 uv_loop_init(loop); 505 // 初始化一个async句柄，注册回调函数 506 uv_async_init(loop, async, timer_cb); 507 // 让loop开始运行 508 uv_run(loop, UV_RUN_DEFAULT); 509 // 清理所有的handle 510 uv_walk( 511 loop, 512 [](uv_handle_t* handle, void* args) { 513 if (!uv_is_closing(handle)) { 514 uv_close(hendle, [](uv_handle_t* handle){delete handle;}); 515 } 516 }, 517 nullptr; 518 ); 519 while (uv_run(loop, UV_RUN_DEFAULT) != 0); 520 // 释放loop 521 uv_loop_delete(loop); 522 }) 523 t.detach(); 524 return 0; 525} 526 527// 在另一个线程上调用uv_async_send函数 528static napi_value TestTimerAsyncSend(napi_env env, napi_callback_info info) { 529 std::thread t([](){ // B线程 530 uv_async_send(async); // 调用uv_async_send，通知loop线程调用与async句柄绑定的timer_cb 531 }); 532 t.detach(); 533 return 0; 534} 535 536EXTERN_C_START 537static napi_value Init(napi_env env, napi_value exports) { 538 napi_property_descriptor desc[] = { 539 {"testTimerAsync", nullptr, TestTimerAsync, nullptr, nullptr, nullptr, napi_default, nullptr}, 540 {"testTimerAsyncSend", nullptr, TestTimerAsyncSend, nullptr, nullptr, nullptr, napi_default, nullptr}, 541 }; 542 napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 543 return exports; 544} 545EXTERN_C_END 546 547static napi_module demoModule = { 548 .nm_version = 1, 549 .nm_flags = 0, 550 .nm_filename = nullptr, 551 .nm_register_func = Init, 552 .nm_modname = "entry", 553 .nm_priv = ((void *)0), 554 .reserved = {0}, 555}; 556 557extern "C" __attribute__((constructor)) void RegisterEntryModule(void) { 558 napi_module_register(&demoModule); 559} 560``` 561 562上述代码只是一个简单的示例，进阶实现是：使用一个全局的任务队列，在非loop线程提交任务到任务队列，然后在合适的时机调用uv_async_send函数，回到loop线程执行async_cb，在async_cb中，遍历执行该任务队列上的所有任务。需要注意的是，务必保证对任务队列的操作是线程安全的，C++实现可使用无锁队列，C实现需要加锁保护。 563 564##### 从env获取loop 565 566开发者使用`napi_get_uv_event_loop`接口从env获取到的loop一般是系统创建的js线程的事件循环，因此应当避免在子线程中调用非线程安全函数。 567 568如因业务需要，必须在非loop线程上调用非线程安全函数，请使用线程安全函数`uv_async_send`函数进行操作。即定义一个uv_async_t*类型的句柄，初始化该句柄的时候，将需要在子线程调用的非线程安全函数在对应的async_cb中调用，然后在非loop线程上调用uv_async_send函数，并回到loop线程上执行async_cb。请参考[正确使用timer示例](#正确使用timer示例)的场景二。 569 570### 线程安全函数 571 572在libuv中，由于涉及到大量的异步任务，稍有不慎就会陷入到多线程问题中。在这里，我们对libuv中常用的线程安全函数和非线程安全函数做了汇总。若开发者在多线程编程中调用了非线程安全的函数，势必要对其进行加锁保护或者保证代码的正确运行时序，否则将陷入到crash问题中。 573 574线程安全函数： 575 576- uv_async_send()：向异步句柄发送信号，可以在任何线程中调用。 577- uv_thread_create()：创建一个新线程并执行指定的函数，可以在任何线程中调用。 578- 锁相关的操作，如uv\_mutex\_lock()、uv\_mutex\_unlock()等等。 579 580**提示：所有形如uv_xxx_init的函数，即使它是以线程安全的方式实现的，但使用时要注意，避免多个线程同时调用uv_xxx_init，否则它依旧会引起多线程资源竞争的问题。最好的方式是在事件循环线程中调用该函数。** 581 582**注：`uv_async_send`函数被调用后，回调函数是被异步触发的。如果调用了多次`uv_async_send`，libuv只保证至少有一次回调会被执行。这就可能导致一旦对同一句柄触发了多次`uv_async_send`，libuv对回调的处理可能会违背开发者的预期。** 而在native侧，可以保证回调的执行次数和开发者调用`napi_call_threadsafe_function`的次数保持一致。 583 584非线程安全函数： 585 586- uv\_os\_unsetenv()：删除环境变量 587- uv\_os\_setenv()：设置环境变量 588- uv\_os\_getenv()：获取环境变量 589- uv\_os\_environ()：检索所有的环境变量 590- uv\_os\_tmpdir()：获取临时目录 591- uv\_os\_homedir()：获取家目录 592 593### libuv中的事件循环 594 595事件循环是libuv中最核心的一个概念，loop负责管理整个事件循环的所有资源，它贯穿于整个事件循环的生命周期。通常将`uv_run`所在的线程称为该事件循环的主线程。 596 597#### 事件循环运行的三种方式 598 599`UV_RUN_DEFAULT`：默认轮询方式，该模式将会一直运行下去，直到loop中没有活跃的句柄和请求。 600 601`UV_RUN_ONCE`：一次轮询模式，如果pending_queue中有回调函数，则执行，然后跳过`uv__io_poll`函数。此模式默认认为loop中一定有事件发生。 602 603`UV_RUN_NOWAIT`：非阻塞模式，该模式下不会执行pending_queue，而是直接执行一次I/O轮询（`uv__io_poll`）。 604 605#### 常用接口 606 607```cpp 608int uv_loop_init(uv_loop_t* loop); 609``` 610 611 对loop进行初始化。 612 613```cpp 614int uv_loop_close(uv_loop_t* loop); 615``` 616 617 关闭loop，该函数只有在loop中所有的句柄和请求都关闭后才能成功返回，否则将返回UV_EBUSY。 618 619```cpp 620int uv_loop_delete(uv_loop_t* loop); 621``` 622 623释放loop，该接口会先调用`uv_loop_close`，然后再将loop释放掉。在OpenHarmony平台上，由于assert函数不生效，因此不论`uv_loop_close`函数是否成功清理loop上的资源，都会将loop释放掉。开发者使用该接口时，请务必确保在loop线程退出时，loop上的资源可以被正确释放，即挂在loop上的handle和request均被关闭，否则会导致资源泄漏。**开发者使用该接口时务必格外谨慎，建议非必要不使用。** 624 625```cpp 626uv_loop_t* uv_default_loop(void); 627``` 628 629 该函数创建一个进程级的loop。在OpenHarmony中，由于目前的应用主循环及其他js工作线程还存在着libuv的loop。因此我们不建议开发者使用该函数来创建loop并实现业务功能。在系统的双loop改造完成后，开发者可以根据业务要求来使用该接口。 630 631```cpp 632int uv_run(uv_loop_t* loop, uv_run_mode mode); 633``` 634 635 启动事件循环。运行模式可查看[事件循环运行的三种方式](#事件循环运行的三种方式)。 636 637```cpp 638int uv_loop_alive(uv_loop_t loop); 639``` 640 641 判断loop是否处于活跃状态。 642 643```cpp 644void uv_stop(uv_loop_t* loop); 645``` 646 647 该函数用来停止一个事件循环，在loop的下一次迭代中才会停止。如果该函数发生在I/O操作之前，将不会阻塞而是直接跳过`uv__io_poll`。 648 649**使用技巧**：在使用loop时，需要特别注意`uv_stop`函数的使用。开发者需要确保`uv_stop`前，通知与loop相关的所有线程的handle都关闭。参考代码如下： 650 651```cpp 652int stop_loop(uv_loop_t* loop) 653{ 654 uv_stop(loop); 655 auto const ensure_close = [](uv_handle_t* handle, void*) { 656 if (uv_is_closing(handle)) { 657 return; 658 } else { 659 uv_close(handle, nullptr); 660 } 661 }; 662 // 遍历所有句柄，如果handle处于活跃状态，调用ensure_close。 663 uv_walk(loop, ensure_close, nullptr); 664 665 // 继续运行uv_run，直到loop中不存在活跃的句柄和请求为止。 666 while(true) { 667 if (uv_run(loop, UV_RUN_DEFAULT) == 0) { 668 break; 669 } 670 } 671 672 // 最后检查loop状态。 673 if (uv_loop_alive(loop) != 0) { 674 return -1; 675 } 676 return 0; 677} 678``` 679 680### libuv中的handles和requests 681 682handle表示一个持久性的对象，通常挂载到loop中对应的handle_queue队列上。如果handle处于活跃状态，每次`uv_run`都会处理handle中的回调函数。 683 684request表示一个短暂性的请求，一个request只触发一次回调操作。 685 686下面是OpenHarmony系统中最常用的几个Handles和Requests： 687 688```cpp 689/* Handle Type */ 690typedef struct uv_handle_s uv_handle_t; 691typedef struct uv_timer_s uv_timer_t; 692typedef struct uv_async_s uv_async_t; 693typedef struct uv_signal_s uv_signal_t; 694 695/* Request Type */ 696typedef struct uv_req_s uv_req_t; 697typedef struct uv_work_s uv_work_t; 698typedef struct uv_fs_s uv_fs_t; 699``` 700 701**注：在handles中，uv_xxx_t继承了uv_handle_t；在requests中，uv_work_t继承了uv_req_t。** 702 703对于libuv中的handles，对其有个正确的认识并管理好它的生命周期至关重要。handle作为一个长期存在于loop中的句柄，在使用中，开发者应遵循下面的原则： 704 7051. 句柄的初始化工作应在事件循环的线程中进行。 7062. 若由于业务问题，句柄需要在其他工作线程初始化，在使用之前用原子变量判断是否初始化完成。 7073. 句柄在确定后续不再使用后，调用`uv_close`将句柄从loop中摘除。 708 709在这里，需要特别说明一下`uv_close`的使用方法。`uv_close`被用来关闭一个handle，但是它是异步地关闭handle。函数原型为： 710 711```cpp 712void uv_close(uv_handle_t* handle, uv_close_cb close_cb) 713``` 714 715 handle：要关闭的句柄。 716 close_cb：处理该句柄的函数，用来进行内存管理等操作。 717 718`uv_close`调用后，它首先将要关闭的handle挂载到loop中的closing_handles队列上，然后等待loop所在线程运行`uv__run_closing_handles`函数。最后回调函数close_cb将会在loop的下一次迭代中执行。因此，释放内存等操作应该在close_cb中进行。并且这种异步的关闭操作会带来多线程上的问题，开发者需要谨慎处理`uv_close`的时序问题，并且保证在close_cb执行之前Handles的生命周期。 719 720**Tips**：在[libuv官方文档](http://libuv.org/)中，有个经验法则需要在此提示一下。原文翻译：如果 uv_foo_t 类型的句柄具有 `uv_foo_start()` 函数，则从调用该函数的那一刻起，它就处于活动状态。 同样，`uv_foo_stop()`再次停用句柄。 721 722> **注意** 723> 724> 1. 所有的handle关闭前必须要调用`uv_close`，所有的内存操作都要在`uv_close`的close_cb中执行。 725> 726> 2. 所有的handle操作都不能通过获取其他线程loop的方式，在非loop线程上调用。 727 728#### 异步任务提交 729 730对于libuv中的requests，开发者需要确保在进行异步任务提交时，**通过动态申请的request，要在loop所在线程执行的complete回调函数中释放**。用uv_work_t举例，代码可参考如下： 731 732```cpp 733uv_work_t* work = new uv_work_t; 734uv_queue_work(loop, work, [](uv_work_t* req) { 735 // 异步操作 736}, [](uv_work_t* req, int status) { 737 // 回调操作 738 delete req; 739}); 740``` 741 742而对于一些特定场景，比如对内存开销敏感的场景中，同一个request可以重复使用，前提是保证同一类任务之间的顺序，并且要确保最后一次调用`uv_queue_work`时做好对该request的释放工作。 743 744```C 745uv_work_t* work = new uv_work_t; 746uv_queue_work(loop, work, [](uv_work_t* work) { 747 //do something 748 }, 749 [](uv_work_t* work, int status) { 750 // do something 751 uv_queue_work(loop, work, [](...) {/* do something*/}, [](...) { 752 //do something 753 if (last_task) { // 最后一个任务执行完以后，释放该request 754 delete work; 755 } 756 }); 757 }, 758 ) 759``` 760 761#### 异步任务提交注意事项 762##### uv_queue_work流程 763libuv中`uv_queue_work`在UI线程的工作流程为：将`work_cb`抛到FFRT对应优先级的线程池中，然后待FFRT调度执行该任务，并将`after_work_cb`抛到eventhandler的event queue中，等待eventhandler调度并回到loop线程执行。需要注意的是，`uv_queue_work`调用完后，并不代表其中的任何一个任务执行完，仅代表将work_cb插入到ffrt对应优先级的线程池中。而taskpool和jsworker线程的工作流程和libuv原逻辑保持一致。 764 765##### uv_queue_work使用约束 766 767特别强调，开发者需要明确，`uv_queue_work`函数仅用于抛异步任务，**异步任务的execute回调被提交到线程池后会经过调度执行，因此并不保证多次提交的任务之间的时序关系**。 768 769`uv_queue_work`仅限于在loop线程中调用，这样不会有多线程安全问题。**请不要把uv_queue_work作为线程间通信的手段，即A线程获取到B线程的loop，并通过`uv_queue_work`抛异步任务的方式，把execute回调置为空任务，而把complete回调放在B线程中执行。** 这种方式不仅低效，而且还增加了发生故障时定位问题的难度。为了避免低效的任务提交，请使用[napi_threadsafe_function相关函数](#跨线程共享和调用的线程安全函数)。 770 771#### libuv timer使用规范 772 773使用libuv timer需要遵守如下约定： 774 7751. 请不要在多个线程中使用libuv的接口（`uv_timer_start`、`uv_timer_stop`和`uv_timer_again`）同时操作同一个loop的timer heap，否则将导致崩溃，如果想要使用libuv的接口操作定时器，请**保持在与当前env绑定的loop所在线程上操作**； 7762. 如因业务需求往指定线程抛定时器，请使用`uv_async_send`线程安全函数实现。 777 778##### 错误使用timer示例 779 780以下错误示例中，由于在多个线程操作同一个loop的timer heap，崩溃率极高。 781 782ArkTS侧： 783 784```typescript 785import { hilog } from '@kit.PerformanceAnalysisKit'; 786import testNapi from 'libentry.so' 787 788function waitforRunner(): number { 789 "use concurrent" 790 hilog.info(0xff, "testTag", "executed"); 791 return 0; 792} 793 794@Entry 795@Component 796struct Index { 797 build() { 798 Row() { 799 Column() { 800 Button("TimerTest") 801 .width('40%') 802 .fontSize('14fp') 803 .onClick(() => { 804 let i: number = 20; 805 while (i--) { 806 setTimeout(waitforRunner, 200); 807 testNapi.testTimer(); 808 } 809 }).margin(20) 810 }.width('100%') 811 }.height('100%') 812 } 813} 814``` 815 816Native C++侧： 817 818```cpp 819#include <napi/native_api.h> 820#include <uv.h> 821#define LOG_DOMAIN 0x0202 822#define LOG_TAG "MyTag" 823#include "hilog/log.h" 824#include <thread> 825#include <unistd.h> 826 827static napi_value TestTimer(napi_env env, napi_callback_info info) { 828 uv_loop_t* loop = nullptr; 829 uv_timer_t* timer = new uv_timer_t; 830 831 napi_get_uv_event_loop(env, &loop); 832 uv_timer_init(loop, timer); 833 std::thread t1([&loop, &timer](){ 834 uv_timer_start(timer, [](uv_timer_t* timer){ 835 uv_timer_stop(timer); 836 }, 1000, 0); 837 }); 838 839 t1.detach(); 840 return 0; 841} 842 843EXTERN_C_START 844static napi_value Init(napi_env env, napi_value exports) { 845 napi_property_descriptor desc[] = { 846 {"testTimer", nullptr, TestTimer, nullptr, nullptr, nullptr, napi_default, nullptr}, 847 }; 848 napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 849 return exports; 850} 851EXTERN_C_END 852 853static napi_module demoModule = { 854 .nm_version = 1, 855 .nm_flags = 0, 856 .nm_filename = nullptr, 857 .nm_register_func = Init, 858 .nm_modname = "entry", 859 .nm_priv = ((void *)0), 860 .reserved = {0}, 861}; 862 863extern "C" __attribute__((constructor)) void RegisterEntryModule(void) { 864 napi_module_register(&demoModule); 865} 866``` 867 868在index.d.ts增加如下代码： 869 870```typescript 871export const testTimer:() => number; 872``` 873 874##### 正确使用timer示例 875 876**场景一：** 在上述场景中，需保证在native主线程上进行timer的相关操作。将上述TestTimer函数的代码做如下修改，便可以避免崩溃发生。 877 878```cpp 879static napi_value TestTimer(napi_env env, napi_callback_info info) { 880 uv_loop_t* loop = nullptr; 881 uv_timer_t* timer = new uv_timer_t; 882 883 napi_get_uv_event_loop(env, &loop); 884 uv_timer_init(loop, timer); 885 uv_timer_start(timer, [](uv_timer_t* timer){ 886 uv_timer_stop(timer); 887 }, 1000, 0); 888 889 return 0; 890} 891``` 892 893**场景二：** 如果需要在指定的子线程抛定时器，请使用线程安全函数`uv_async_send`实现。 894 895ArkTS侧： 896 897```typescript 898import { hilog } from '@kit.PerformanceAnalysisKit'; 899import testNapi from 'libentry.so' 900 901function waitforRunner(): number { 902 "use concurrent" 903 hilog.info(0xff, "testTag", "executed"); 904 return 0; 905} 906 907@Entry 908@Component 909struct Index { 910 build() { 911 Row() { 912 Column() { 913 Button("TestTimerAsync") 914 .width('40%') 915 .fontSize('14fp') 916 .onClick(() => { 917 testNapi.testTimerAsync(); // 初始化async句柄 918 }).margin(20) 919 920 Button("TestTimerAsyncSend") 921 .width('40%') 922 .fontSize('14fp') 923 .onClick(() => { 924 testNapi.testTimerAsyncSend(); // 子线程调用uv_async_send执行timer_cb 925 }).margin(20) 926 }.width('100%') 927 }.height('100%') 928 } 929} 930``` 931 932Native C++侧： 933 934```c++ 935#include <napi/native_api.h> 936#include <uv.h> 937#define LOG_DOMAIN 0x0202 938#define LOG_TAG "MyTag" 939#include "hilog/log.h" 940#include <thread> 941#include <unistd.h> 942uv_async_t* async = new uv_async_t; 943 944// 执行创建定时器操作 945void timer_cb(uv_async_t* handle) { 946 auto loop = handle->loop; 947 uv_timer_t* timer = new uv_timer_t; 948 uv_timer_init(loop, timer); 949 950 uv_timer_start(timer, [](uv_timer_t* timer){ 951 uv_timer_stop(timer); 952 }, 1000, 0); 953} 954 955// 初始化async句柄，绑定对应的回调函数 956static napi_value TestTimerAsync(napi_env env, napi_callback_info info) { 957 uv_loop_t* loop = nullptr; 958 napi_get_uv_event_loop(env, &loop); 959 uv_async_init(loop, async, timer_cb); 960 return 0; 961} 962 963static napi_value TestTimerAsyncSend(napi_env env, napi_callback_info info) { 964 std::thread t([](){ 965 uv_async_send(async); // 在任意子线程中调用uv_async_send，通知主线程调用与async绑定的timer_cb 966 }); 967 t.detach(); 968 return 0; 969} 970 971EXTERN_C_START 972static napi_value Init(napi_env env, napi_value exports) { 973 napi_property_descriptor desc[] = { 974 {"testTimerAsync", nullptr, TestTimerAsync, nullptr, nullptr, nullptr, napi_default, nullptr}, 975 {"testTimerAsyncSend", nullptr, TestTimerAsyncSend, nullptr, nullptr, nullptr, napi_default, nullptr}, 976 }; 977 napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 978 return exports; 979} 980EXTERN_C_END 981 982static napi_module demoModule = { 983 .nm_version = 1, 984 .nm_flags = 0, 985 .nm_filename = nullptr, 986 .nm_register_func = Init, 987 .nm_modname = "entry", 988 .nm_priv = ((void *)0), 989 .reserved = {0}, 990}; 991 992extern "C" __attribute__((constructor)) void RegisterEntryModule(void) { 993 napi_module_register(&demoModule); 994} 995``` 996 997### 线程间通信 998 999上面简单介绍了一些libuv中的基本概念，在这里我们将着重介绍libuv中的线程间通信。 1000 1001libuv的线程间通信是通过uv_async_t句柄来进行的，相关函数如下： 1002 1003```cpp 1004int uv_async_init(uv_loop_t* loop, uv_async_t* handle, uv_async_cb async_cb) 1005``` 1006 1007 loop：事件循环loop。 1008 1009 handle：线程间通信句柄。 1010 1011 async_cb：回调函数。 1012 1013 返回：成功，返回0。失败，返回错误码。 1014 1015```cpp 1016int uv_async_send(uv_async_t* handle) 1017``` 1018 1019 handle：线程间通信句柄。 1020 1021 返回：成功，返回0。失败，返回错误码。 1022> 说明 1023> 1024> 1. uv_async_t从调用`uv_async_init`开始后就一直处于活跃状态，除非用`uv_close`将其关闭。 1025> 1026> 2. uv_async_t的执行顺序严格按照`uv_async_init`的顺序，而非通过`uv_async_send`的顺序来执行的。因此按照初始化的顺序来管理好时序问题是必要的。 1027 1028 1029 1030示例代码： 1031 1032```cpp 1033#include <bits/stdc++.h> 1034#include "uv.h" 1035 1036uv_loop_t* loop = nullptr; 1037uv_async_t* async = nullptr; 1038int g_counter = 10; 1039void async_handler(uv_async_t* handle) 1040{ 1041 printf("ohos async print\n"); 1042 if (--g_counter == 0) { 1043 // 调用uv_close关闭async，在主循环中释放内存。 1044 uv_close((uv_handle_t*)async, [](uv_handle_t* handle) { 1045 printf("delete async\n"); 1046 delete (uv_async_t*)handle; 1047 }); 1048 } 1049} 1050 1051int main() 1052{ 1053 loop = uv_default_loop(); 1054 async = new uv_async_t; 1055 uv_async_init(loop, async, async_handler); 1056 std::thread subThread([]() { 1057 for (int i = 0; i < 10; i++) { 1058 usleep(100); // 避免多次调用uv_async_send只执行一次 1059 printf("%dth: subThread triggered\n", i); 1060 uv_async_send(async); 1061 } 1062 }); 1063 subThread.detach(); 1064 return uv_run(loop, UV_RUN_DEFAULT); 1065} 1066``` 1067 1068该示例代码仅仅描述了一个简单的场景，步骤如下： 1069 10701. 在主线程中初始化async句柄 10712. 新建一个子线程，在里面每隔100毫秒触发一次`uv_async_send`。10次以后调用`uv_close`关闭async句柄。 10723. 在主线程运行事件循环。 1073 1074可以看到，每触发一次，主线程都会执行一次回调函数。 1075 1076``` 10770th:subThread triggered 1078ohos async print 10791th:subThread triggered 1080ohos async print 10812th:subThread triggered 1082ohos async print 10833th:subThread triggered 1084ohos async print 10854th:subThread triggered 1086ohos async print 10875th:subThread triggered 1088ohos async print 10896th:subThread triggered 1090ohos async print 10917th:subThread triggered 1092ohos async print 10938th:subThread triggered 1094ohos async print 10959th:subThread triggered 1096ohos async print 1097delete async 1098``` 1099 1100### 线程池 1101 1102线程池是libuv的一个核心功能，libuv中的线程池是通过uv_loop_t中的成员变量wq_async来控制工作线程与主线程的通信。核心函数如下： 1103 1104```cpp 1105int uv_queue_work(uv_loop_t* loop, 1106 uv_work_t* req, 1107 uv_work_cb work_cb, 1108 uv_after_work_cb after_work_cb) 1109``` 1110 1111work_cb：提交给工作线程的任务。 1112 1113after_work_cb：loop所在线程的要执行的回调函数。 1114 1115**注意：** work_cb与after_work_cb的执行有一个时序问题，只有work_cb执行完，通过`uv_async_send(loop->wq_async)`触发fd事件，loop所在线程在下一次迭代中才会执行after_work_cb。只有执行到after_work_cb时，与之相关的uv_work_t生命周期才算结束。 1116 1117下图为libuv的线程池工作流程，图中流程已简化，默认句柄的pending标志为1，worker线程个数不代表线程池中线程的真实数量。 1118 1119 1120 1121### OpenHarmony中libuv的使用现状 1122 1123当前OpenHarmony系统中涉及到libuv的线程主要有主线程、JS Worker线程、Taskpool中的TaskWorker线程以及IPC线程。除了主线程内采用了eventhandler作为主循环，其他线程都是使用libuv中的UV_RUN_DEFAULT运行模式作为当前线程的事件主循环来执行任务。在主线程中，eventhandler通过fd驱动的方式来触发任务的执行，eventhandler监听了uv_loop中的backend_fd。当loop中有fd事件触发的时候，eventhandler会执行一次`uv_run`来执行libuv中的任务。 1124 1125综上所述，开发者会发现这样一种现象：**同样的libuv接口在主线程上不生效，但在JS Worker线程中就没问题。这主要还是因为主线程上所有不通过触发fd来驱动的uv接口都不会得到及时的响应。** 1126 1127另外，在应用主线程中，所有的异步任务尽管最终都是通过libuv得到执行的。但是在当前系统中，[libuv的线程池已经对接到了FFRT中](https://gitee.com/openharmony/third_party_libuv/wikis/06-Wiki-%E6%8A%80%E6%9C%AF%E8%B5%84%E6%BA%90/%20libuv%E5%B7%A5%E4%BD%9C%E7%BA%BF%E7%A8%8B%E6%8E%A5%E5%85%A5FFRT%E6%96%B9%E6%A1%88%E5%88%86%E6%9E%90)，任何抛向libuv的异步任务都会在FFRT的线程中得到调度。应用主线程的回调函数也通过PostTask接口插入到eventhandler的队列上。这就意味着ffrt线程上的异步任务完成后不再通过`uv_async_send`的方式触发主线程的回调。过程如下图: 1128 1129 1130 1131我们总结了五种类型的请求任务是直接可以按照正常用法在应用主循环中生效的： 1132 1133- uv_random_t 1134 1135 函数原型： 1136 1137```cpp 1138/** 1139* 将一个工作请求添加到事件循环的队列中。 1140* 1141* @param loop 事件循环 1142* @param req 随机数请求 1143* @param buf 存储随机数的缓冲区 1144* @param buflen 缓冲区的长度 1145* @param flags 一个无符号整数，表示生成随机数的选项 1146* @param cb 随机数生成完成后的回调函数 1147* 1148* @return 成功返回0，失败返回错误码 1149*/ 1150int uv_random(uv_loop_t* loop, 1151 uv_random_t* req, 1152 void* buf, 1153 size_t buflen, 1154 unsigned flags, 1155 uv_random_cb cb); 1156``` 1157 1158- uv_work_t 1159 1160 函数原型： 1161 1162```cpp 1163/** 1164* 将一个工作请求添加到事件循环的队列中。 1165* 1166* 当事件循环在下一次迭代时，work_cb函数将会在一个新的线程中被调用。 1167* 当work_cb函数完成时，after_work_cb函数将会在事件循环的线程中被调用。 1168* 1169* @param loop 事件循环 1170* @param req 工作请求 1171* @param work_cb 在新线程中被调用的函数 1172* @param after_work_cb 在事件循环线程中被调用的函数 1173* 1174* @return 成功返回0，失败返回-1 1175*/ 1176int uv_queue_work(uv_loop_t* loop, 1177 uv_work_t* req, 1178 uv_work_cb work_cb, 1179 uv_after_work_cb after_work_cb); 1180``` 1181 1182- uv_fs_t 1183 1184 文件类提供的所有异步接口，在应用主线程中都是可以生效的。主要有如下： 1185 1186```cpp 1187/** 1188* 异步读取文件 1189* 1190* @param loop 事件循环 1191* @param req 文件操作请求 1192* @param file 文件描述符 1193* @param bufs 读取数据的缓冲区 1194* @param nbufs 缓冲区的数量 1195* @param off 文件的偏移量 1196* @param cb 完成后的回调函数 1197* @return 成功返回0，失败返回-1 1198*/ 1199int uv_fs_read(uv_loop_t* loop, uv_fs_t* req, 1200 uv_file file, 1201 const uv_buf_t bufs[], 1202 unsigned int nbufs, 1203 int64_t off, 1204 uv_fs_cb cb); 1205 1206/** 1207* 异步打开文件 1208* 1209* @param loop 事件循环 1210* @param req 文件操作请求 1211* @param path 文件路径 1212* @param flags 打开文件的方式 1213* @param mode 文件权限 1214* @param cb 完成后的回调函数 1215* 1216* @return 成功返回0，失败返回-1 1217*/ 1218int uv_fs_open(uv_loop_t* loop, 1219 uv_fs_t* req, 1220 const char* path, 1221 int flags, 1222 int mode, 1223 uv_fs_cb cb); 1224 1225/** 1226* 异步发送文件 1227* 1228* @param loop 事件循环 1229* @param req 文件操作请求 1230* @param out_fd 输出文件描述符 1231* @param in_fd 输入文件描述符 1232* @param off 文件的偏移量 1233* @param len 发送的长度 1234* @param cb 完成后的回调函数 1235* 1236* @return 成功返回0，失败返回-1 1237*/ 1238int uv_fs_sendfile(uv_loop_t* loop, 1239 uv_fs_t* req, 1240 uv_file out_fd, 1241 uv_file in_fd, 1242 int64_t off, 1243 size_t len, 1244 uv_fs_cb cb); 1245 1246/** 1247* 异步写入文件 1248* 1249* @param loop 事件循环 1250* @param req 文件操作请求 1251* @param file 文件描述符 1252* @param bufs 要写入的数据 1253* @param nbufs 数据的数量 1254* @param off 文件的偏移量 1255* @param cb 完成后的回调函数 1256* 1257* @return 成功返回0，失败返回-1 1258*/ 1259int uv_fs_write(uv_loop_t* loop, 1260 uv_fs_t* req, 1261 uv_file file, 1262 const uv_buf_t bufs[], 1263 unsigned int nbufs, 1264 int64_t off, 1265 uv_fs_cb cb); 1266 1267/** 1268* 异步复制文件 1269* 1270* @param loop 事件循环 1271* @param req 文件操作请求 1272* @param path 源文件路径 1273* @param new_path 目标文件路径 1274* @param flags 复制选项 1275* @param cb 完成后的回调函数 1276* 1277* @return 成功返回0，失败返回-1 1278*/ 1279int uv_fs_copyfile(uv_loop_t* loop, 1280 uv_fs_t* req, 1281 const char* path, 1282 const char* new_path 1283 int flags, 1284 uv_fs_cb cb); 1285``` 1286 1287- uv_getaddrinfo_t 1288 1289 函数原型： 1290 1291```cpp 1292/** 1293* 异步获取地址信息 1294* 1295* @param loop 事件循环 1296* @param req 地址信息请求 1297* @param cb 完成后的回调函数 1298* @param hostname 主机名 1299* @param service 服务名 1300* @param hints 地址信息提示 1301* 1302* @return 成功返回0，失败返回-1 1303*/ 1304int uv_getaddrinfo(uv_loop_t* loop, 1305 uv_getaddrinfo_t* req, 1306 uv_getaddrinfo_cb cb, 1307 const char* hostname, 1308 const char* service, 1309 const struct addrinfo* hints); 1310``` 1311 1312- uv_getnameinfo_t 1313 1314 函数原型： 1315 1316```cpp 1317/** 1318* 异步获取名称信息 1319* 1320* @param loop 事件循环 1321* @param req 名称信息请求 1322* @param getnameinfo_cb 完成后的回调函数 1323* @param addr 地址 1324* @param flags 标志 1325* 1326* @return 成功返回0，失败返回-1 1327*/ 1328int uv_getnameinfo(uv_loop_t* loop, 1329 uv_getnameinfo_t* req, 1330 uv_getnameinfo_cb getnameinfo_cb, 1331 const struct sockaddr* addr, 1332 int flags); 1333``` 1334 1335在应用主线程上不生效的接口主要包括： 1336 1337- idle句柄 1338- prepare句柄 1339- check句柄 1340- signal相关函数 1341- tcp及udp相关函数 1342 1343## 技术案例 1344 1345[libuv中主线程timer回调事件触发时间不正确原因](https://gitee.com/openharmony/third_party_libuv/wikis/06-Wiki-%E6%8A%80%E6%9C%AF%E8%B5%84%E6%BA%90/libuv%E4%B8%AD%E4%B8%BB%E7%BA%BF%E7%A8%8Btimer%E5%9B%9E%E8%B0%83%E4%BA%8B%E4%BB%B6%E8%A7%A6%E5%8F%91%E6%97%B6%E9%97%B4%E4%B8%8D%E6%AD%A3%E7%A1%AE%E5%8E%9F%E5%9B%A0) 1346 1347[libuv工作线程接入FFRT方案分析](https://gitee.com/openharmony/third_party_libuv/wikis/06-Wiki-%E6%8A%80%E6%9C%AF%E8%B5%84%E6%BA%90/%20libuv%E5%B7%A5%E4%BD%9C%E7%BA%BF%E7%A8%8B%E6%8E%A5%E5%85%A5FFRT%E6%96%B9%E6%A1%88%E5%88%86%E6%9E%90) 1348 1349[QoS感知的libuv、Node-API异步接口整改FAQ](https://gitee.com/openharmony/third_party_libuv/wikis/06-Wiki-%E6%8A%80%E6%9C%AF%E8%B5%84%E6%BA%90/QoS%E6%84%9F%E7%9F%A5%E7%9A%84libuv%E3%80%81napi%E5%BC%82%E6%AD%A5%E6%8E%A5%E5%8F%A3%E6%95%B4%E6%94%B9FAQ) 1350
