1# Function Flow Runtime开发指导 2 3## 介绍 4 5FFRT编程模型是一种基于任务和数据驱动的并发编程模型，允许开发者通过任务及其依赖关系描述的方式进行应用开发。 6通过FFRT编程模型，开发者可专注于应用功能开发，由FFRT在运行时根据任务依赖状态和可用执行资源自动并发调度和执行任务。 7 8本文用于指导开发者基于FFRT编程模型实现并行编程。 9 10## 维测 11 12### 超时监测 13 14FFRT提供开发者队列级和任务级超时维测机制，用来监控用户业务中承载重要职责的队列和任务在FFRT调度的端到端时间。 15 16- 当队列中任务发生超时，FFRT打印告警日志并通过回调接口通知到业务。 17- 当任务发生超时，FFRT打印告警日志并调用进程级回调函数。 18 19> **注意：** 20> 21> 任务超时时执行的回调函数进程范围内唯一，需要在任务提交之前由业务方配置到FFRT中，不支持在提交任务或任务超时检测过程中配置。 22 23具体接口包括： 24 25| C++接口 | C接口 | 描述 | 26| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------- | 27| [task_attr::timeout](ffrt-api-guideline-cpp.md#set-task-timeout) | [ffrt_task_attr_set_timeout](ffrt-api-guideline-c.md#ffrt_task_attr_set_timeout) | 设置任务超时时间。 | 28| [queue_attr::timeout](ffrt-api-guideline-cpp.md#set-queue-timeout) | [ffrt_queue_attr_set_timeout](ffrt-api-guideline-c.md#ffrt_queue_attr_set_timeout) | 设置队列超时时间。 | 29| [queue_attr::callback](ffrt-api-guideline-cpp.md#set-queue-callback) | [ffrt_queue_attr_set_callback](ffrt-api-guideline-c.md#ffrt_queue_attr_set_callback) | 设置队列超时回调函数。 | 30 31### 长耗时任务监测 32 33#### 机制 34 35- 长耗时任务打印机制 当任务执行时间超过一秒时，会触发一次堆栈打印，后续该任务堆栈打印频率调整为一分钟。连续打印十次后，打印频率调整为十分钟。再触发十次打印后，打印频率固定为三十分钟。 36- 该机制的堆栈打印调用的是DFX的`GetBacktraceStringByTid`接口，该接口会向阻塞线程发送抓栈信号，触发中断并抓取调用栈返回。 37 38#### 样例 39 40在对应进程日志中搜索RecordSymbolAndBacktrace关键字，对应的日志示例如下： 41 42```txt 43W C01719/ffrt: 60500:RecordSymbolAndBacktrace:159 Tid[16579] function occupies worker for more than [1]s. 44W C01719/ffrt: 60501:RecordSymbolAndBacktrace:164 Backtrace: 45W C01719/ffrt: #00 pc 00000000000075f0 /system/lib64/module/file/libhash.z.so 46W C01719/ffrt: #01 pc 0000000000008758 /system/lib64/module/file/libhash.z.so 47W C01719/ffrt: #02 pc 0000000000012b98 /system/lib64/module/file/libhash.z.so 48W C01719/ffrt: #03 pc 000000000002aaa0 /system/lib64/platformsdk/libfilemgmt_libn.z.so 49W C01719/ffrt: #04 pc 0000000000054b2c /system/lib64/platformsdk/libace_napi.z.so 50W C01719/ffrt: #05 pc 00000000000133a8 /system/lib64/platformsdk/libuv.so 51W C01719/ffrt: #06 pc 00000000000461a0 /system/lib64/chipset-sdk/libffrt.so 52W C01719/ffrt: #07 pc 0000000000046d44 /system/lib64/chipset-sdk/libffrt.so 53W C01719/ffrt: #08 pc 0000000000046a6c /system/lib64/chipset-sdk/libffrt.so 54W C01719/ffrt: #09 pc 00000000000467b0 /system/lib64/chipset-sdk/libffrt.so 55``` 56 57该维测会打印出Worker上执行时间超过阈值的任务堆栈、Worker线程号、执行时间，请自行根据堆栈找对应组件确认阻塞原因。 58 59#### 注意事项 60 61不涉及。 62 63### 运行信息转储 64 65#### 机制 66 67FFRT提供一个对外的接口`ffrt_dump`以便转储FFRT子系统运行时的内部信息，主要包含： 68 691. FFRT统计信息：提交任务数，运行任务数，协程切换次数，任务完成数； 702. Worker线程信息：每个QoS下的Worker数量，Worker id，当前运行的任务id，任务名以及任务类型； 713. 普通任务信息：当前进程中还未释放的普通任务，dump每个任务的任务名，id及调用栈信息； 724. 队列任务信息：当前进程中还未释放的队列任务，dump每个任务的任务名，id及调用栈信息。 73 74在当前进程发生freeze时，OH的DFX模块会主动调用`ffrt_dump`接口转储FFRT的信息，落盘到freeze文件中，存储到`/data/log/faultlog/faultlogger/`目录下，用户可以直接利用该文件中的任务调用栈信息定位对应任务的卡顿问题。 75 76#### 样例 77 78```txt 79ready task ptr: qos 0 readptr 79 writeptr 79 80ready task ptr: qos 1 readptr 360 writeptr 360 81ready task ptr: qos 2 readptr 19 writeptr 19 82ready task ptr: qos 3 readptr 0 writeptr 0 83ready task ptr: qos 4 readptr 0 writeptr 0 84ready task ptr: qos 5 readptr 65 writeptr 65 85ready task ptr: qos 6 readptr 0 writeptr 0 86ready task ptr: qos 7 readptr 0 writeptr 0 87submit queue: readptr 24 writeptr 24 88intr wake: status 255 89proc status: taskCnt 23 vercnt 0sigCnt0 90 |-> worker count 91 qos 0: worker num:1 tid:31676 92 qos 2: worker num:3 tid:51349, 28769, 28565 93 qos 5: worker num:1 tid:30605 94 |-> worker status 95 qos 0: worker tid 31676 is running nothing 96 qos 2: worker tid 51349 is running nothing 97 qos 2: worker tid 28769 is running, task id 24591 name sq_CesSrvMain_12_PublishCommonEventDetailed_24591 fromTid 43928 createTime 2024-11-27 02:52:27.325248 executeTime 2024-11-27 02:52:27.326150 98 qos 2: worker tid 28565 is running, task id 24611 name sq_dfx_freeze_task_queue_16_NotifyAppFaultTask_24611 fromTid 43833 createTime 2024-11-27 02:52:38.114787 executeTime 2024-11-27 02:52:38.115424 99 qos 5: worker tid 30605 is running, task id 24595 name sq_AbilityManagerService_19_SubmitTaskInner_24595 fromTid 43610 createTime 2024-11-27 02:52:27.844237 executeTime 2024-11-27 02:52:27.844573 100 |-> ready queue status 101 |-> blocked by task dependence 102 <1/1>stack: task id 3,qos 2,name AgingTask fromTid 43417 createTime 2024-11-27 01:21:39.641673 executeTime 2024-11-27 01:21:39.642290 103#00 pc 0000000000065c5c /system/lib64/ndk/libffrt.so(CoYield()+560)(22be57f01a789a03813d26a19c3a4042) 104#01 pc 00000000000a3268 /system/lib64/ndk/libffrt.so(ffrt::this_task::SleepUntilImpl(std::__h::chrono::time_point<std::__h::chrono::steady_clock, std::__h::chrono::duration<long long, std::__h::ratio<1l, 1000000000l>>> const&)+356)(22be57f01a789a03813d26a19c3a4042) 105#02 pc 00000000000a39b4 /system/lib64/ndk/libffrt.so(ffrt_usleep+60)(22be57f01a789a03813d26a19c3a4042) 106#03 pc 0000000000420de0 /system/lib64/libbms.z.so(2eb52bd03af1b9a31e14ffe60bfc39da) 107#04 pc 00000000000a6a2c /system/lib64/ndk/libffrt.so(ffrt::CPUEUTask::Execute()+300)(22be57f01a789a03813d26a19c3a4042) 108#05 pc 0000000000066d18 /system/lib64/ndk/libffrt.so(22be57f01a789a03813d26a19c3a4042) 109``` 110 111#### 注意事项 112 113由于OH DFX模块在freeze时有处理时间的要求，低概率会导致`ffrt_dump`中收集的信息不全，freeze处理时间耗尽，此时落盘的信息会有缺失。 114 115### 黑匣子日志 116 117#### 机制 118 119进程Crash发生时，FFRT模块收到信号（`SIGABRT`、`SIGBUS`、`SIGFPE`、`SIGILL`、`SIGSTKFLT`、`SIGSTOP`、`SIGSYS`和`SIGTRAP`），将FFRT当前重要的运行时信息保存至faultlog中，包括：正在运行的task；当前Worker的运行信息和调用栈信息；当前普通任务信息；当前队列任务信息等。用户可利用这些信息中的内容辅助定位Crash问题。 120 121#### 样例 122 123```txt 124C01719/CameraDaemon/ffrt: 9986:operator():254 <<<=== ffrt black box(BBOX) start ===>>> 125C01719/CameraDaemon/ffrt: 9987:SaveCurrent:63 <<<=== current status ===>>> 126C01719/CameraDaemon/ffrt: 9988:SaveCurrent:68 signal SIGABRT triggered: source tid 5962, task id 17, qos 2, name SvrWatchdog 127C01719/CameraDaemon/ffrt: 9989:SaveWorkerStatus:94 <<<=== worker status ===>>> 128C01719/CameraDaemon/ffrt: 9990:SaveWorkerStatus:100 qos 0: worker tid 6410 is running nothing 129C01719/CameraDaemon/ffrt: 9991:SaveWorkerStatus:100 qos 2: worker tid 5968 is running nothing 130C01719/CameraDaemon/ffrt: 9992:SaveWorkerStatus:100 qos 2: worker tid 5964 is running nothing 131C01719/CameraDaemon/ffrt: 9993:SaveWorkerStatus:100 qos 2: worker tid 5963 is running nothing 132C01719/CameraDaemon/ffrt: 9994:SaveWorkerStatus:105 qos 2: worker tid 5962 is running task id 17 name SvrWatchdog 133C01719/CameraDaemon/ffrt: 9995:SaveWorkerStatus:100 qos 2: worker tid 5967 is running nothing 134C01719/CameraDaemon/ffrt: 9996:SaveWorkerStatus:100 qos 2: worker tid 5965 is running nothing 135C01719/CameraDaemon/ffrt: 9997:SaveWorkerStatus:100 qos 2: worker tid 5961 is running nothing 136C01719/CameraDaemon/ffrt: 9998:SaveWorkerStatus:100 qos 2: worker tid 1146 is running nothing 137C01719/CameraDaemon/ffrt: 9999:SaveWorkerStatus:100 qos 2: worker tid 1145 is running nothing 138C01719/CameraDaemon/ffrt: 10000:SaveWorkerStatus:100 qos 2: worker tid 5966 is running nothing 139``` 140 141#### 注意事项 142 143不涉及。 144 145### Trace打点 146 147#### 机制 148 149FFRT任务的调度和执行过程中，利用了OH系统的Trace打点能力，对任务在FFRT框架中的状态流转做了实时跟踪，用户可以借助Trace图形化工具来分析任务的行为是否符合预期。 150 151#### 样例 152 1531. 启动Trace抓取 154 155 ```shell 156 hdc shell "hitrace -t 10 -b 20480 -o /data/local/tmp/in_systrace.ftrace sched freq idle ffrt" 157 # -t：指定trace采集时长，在采集过程中所有的trace记录会落盘保存 158 # -b：指定trace记录缓存大小，buffer不足的情况下可能导致部分记录被覆盖没有落盘 159 # -o：指定trace落盘存储路径 160 ``` 161 1622. 图形化工具呈现 163 164 将Trace落盘的文件从设备中取出来，借助图形化工具进行分析，例如：[Perfetto](https://perfetto.dev/)。 165 166#### 注意事项 167 168用户也可以在自己业务代码中加入Trace打点，以界定问题的范围。需注意在高频调用流程中，加入Trace打点会有系统开销，会对业务性能造成影响。 169 170### Debug日志 171 172#### 机制 173 174- FFRT默认不开启Debug级别的日志，用户可以通过命令的方式打开，以获取更丰富的维测信息支撑开发阶段的问题定位。 175- 打开FFRT Debug日志开关： 176 177 ```shell 178 hdc shell hilog -b DEBUG -D 0xD001719 179 ``` 180 181- 恢复默认FFRT INFO日志级别: 182 183 ```shell 184 hdc shell hilog -b INFO -D 0xD001719 185 ``` 186 187#### 样例 188 189```txt 1904190 5631 D C01719/neboard:EngineServiceAbility:1/ffrt: 275337:Detach:147 qos 3 thread not joinable 1913257 6075 D C01719/com.ohos.sceneboard/ffrt: 513070:SetDefaultThreadAttr:148 qos apply tid[6075] level[3] 192``` 193 194#### 注意事项 195 196由于FFRT是系统底座，支撑大量上层业务及框架的运行，全局打开Debug日志会导致日志超限，影响其他模块日志的正常输出。 197 198## 开发步骤 199 200以下步骤描述了如何使用FFRT提供的Native API接口，创建并行任务和串行队列任务以及销毁相应资源。 201 2021. 在项目`CMakeLists.txt`中添加动态链接库： 203 204 ```txt 205 libffrt.z.so 206 ``` 207 2082. 在项目中包含对应的头文件： 209 210 ```cpp 211 #include "ffrt/task.h" 212 #include "ffrt/type_def.h" 213 #include "ffrt/condition_variable.h" 214 #include "ffrt/loop.h" 215 #include "ffrt/mutex.h" 216 #include "ffrt/queue.h" 217 #include "ffrt/sleep.h" 218 #include "ffrt/timer.h" 219 ``` 220 2213. 对执行的函数进行封装： 222 223 ```cpp 224 // 第一种使用模板，支持C++ 225 template<class T> 226 struct function { 227 ffrt_function_header_t header; 228 T closure; 229 }; 230 231 template<class T> 232 void exec_function_wrapper(void* t) 233 { 234 auto f = reinterpret_cast<function<std::decay_t<T>>*>(t); 235 f->closure(); 236 } 237 238 template<class T> 239 void destroy_function_wrapper(void* t) 240 { 241 auto f = reinterpret_cast<function<std::decay_t<T>>*>(t); 242 f->closure = nullptr; 243 } 244 245 template<class T> 246 inline ffrt_function_header_t* create_function_wrapper(T&& func, 247 ffrt_function_kind_t kind = ffrt_function_kind_general) 248 { 249 using function_type = function<std::decay_t<T>>; 250 static_assert(sizeof(function_type) <= ffrt_auto_managed_function_storage_size, 251 "size of function must be less than ffrt_auto_managed_function_storage_size"); 252 253 auto p = ffrt_alloc_auto_managed_function_storage_base(kind); 254 auto f = new (p)function_type; 255 f->header.exec = exec_function_wrapper<T>; 256 f->header.destroy = destroy_function_wrapper<T>; 257 f->closure = std::forward<T>(func); 258 return reinterpret_cast<ffrt_function_header_t*>(f); 259 } 260 261 // 第二种创建方式 262 typedef struct { 263 ffrt_function_header_t header; 264 ffrt_function_t func; 265 ffrt_function_t after_func; 266 void* arg; 267 } c_function_t; 268 269 static inline void ffrt_exec_function_wrapper(void* t) 270 { 271 c_function_t* f = (c_function_t *)t; 272 if (f->func) { 273 f->func(f->arg); 274 } 275 } 276 277 static inline void ffrt_destroy_function_wrapper(void* t) 278 { 279 c_function_t* f = (c_function_t *)t; 280 if (f->after_func) { 281 f->after_func(f->arg); 282 } 283 } 284 285 #define FFRT_STATIC_ASSERT(cond, msg) int x(int static_assertion_##msg[(cond) ? 1 : -1]) 286 static inline ffrt_function_header_t *ffrt_create_function_wrapper(const ffrt_function_t func, 287 const ffrt_function_t after_func, void *arg) 288 { 289 FFRT_STATIC_ASSERT(sizeof(c_function_t) <= ffrt_auto_managed_function_storage_size, 290 size_of_function_must_be_less_than_ffrt_auto_managed_function_storage_size); 291 292 c_function_t* f = (c_function_t *)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general); 293 f->header.exec = ffrt_exec_function_wrapper; 294 f->header.destroy = ffrt_destroy_function_wrapper; 295 f->func = func; 296 f->after_func = after_func; 297 f->arg = arg; 298 return (ffrt_function_header_t *)f; 299 } 300 301 // 样例：待提交执行的函数 302 void OnePlusForTest(void* arg) 303 { 304 (*static_cast<int*>(arg)) += 1; 305 } 306 ``` 307 3084. 设置任务属性值，包括QoS等级、任务名称等，具体可以参考接口文档。 309 310 ```cpp 311 // ******初始化并行任务属性****** 312 ffrt_task_attr_t attr; 313 ffrt_task_attr_init(&attr); 314 315 // ******创建串行队列****** 316 317 // 创建串行队列的属性 318 ffrt_queue_attr_t queue_attr; 319 // 创建串行队列的handle 320 ffrt_queue_t queue_handle; 321 322 // 初始化队列属性 323 (void)ffrt_queue_attr_init(&queue_attr); 324 325 // 如有需要，设置指定QoS等级 326 ffrt_queue_attr_set_qos(&queue_attr, static_cast<ffrt_qos_t>(ffrt_qos_inherit)); 327 // 如有需要，设置超时时间(ms) 328 ffrt_queue_attr_set_timeout(&queue_attr, 10000); 329 // 如有需要，设置超时回调 330 int x = 0; 331 ffrt_queue_attr_set_callback(&queue_attr, ffrt_create_function_wrapper(OnePlusForTest, NULL, &x, 332 ffrt_function_kind_queue)); 333 334 // 基于属性，初始化队列 335 queue_handle = ffrt_queue_create(ffrt_queue_serial, "test_queue", &queue_attr); 336 ``` 337 3385. 提交任务。 339 340 ```cpp 341 int a = 0; 342 // ******并行任务****** 343 // 提交不带handle返回值的并行任务 344 ffrt_submit_base(ffrt_create_function_wrapper(OnePlusForTest, NULL, &a), NULL, NULL, &attr); 345 // 提交带handle返回值的并行任务 346 ffrt_task_handle_t task = ffrt_submit_h_base( 347 ffrt_create_function_wrapper(OnePlusForTest, NULL, &a), NULL, NULL, &attr); 348 349 // ******串行任务****** 350 // 提交不返回handle的串行队列任务 351 ffrt_queue_submit(queue_handle, ffrt_create_function_wrapper(OnePlusForTest, nullptr, &a, 352 ffrt_function_kind_queue), nullptr); 353 // 提交带handle的串行队列任务 354 ffrt_task_handle_t handle = ffrt_queue_submit_h(queue_handle, 355 ffrt_create_function_wrapper(OnePlusForTest, nullptr, &a, ffrt_function_kind_queue), nullptr); 356 357 // 如果需要等待执行结果，则调用wait 358 const std::vector<ffrt_dependence_t> wait_deps = {{ffrt_dependence_task, task}}; 359 ffrt_deps_t wait{static_cast<uint32_t>(wait_deps.size()), wait_deps.data()}; 360 ffrt_wait_deps(&wait); 361 362 ffrt_queue_wait(handle); 363 ``` 364 3656. 任务提交完成后销毁相应资源。 366 367 ```cpp 368 // ******销毁并行任务****** 369 ffrt_task_attr_destroy(&attr); 370 ffrt_task_handle_destroy(task); 371 372 // ******销毁串行队列任务****** 373 // 先销毁任务handle，再销毁队列 374 ffrt_queue_attr_destroy(&queue_attr); 375 ffrt_task_handle_destroy(handle); 376 ffrt_queue_destroy(queue_handle); 377 ``` 378 379## 使用建议 380 381### 建议1：函数化 382 383- 程序过程各步骤以函数封装表达，函数满足类纯函数特性。 384- 无全局数据访问。 385- 无内部状态保留。 386- 通过`ffrt_submit_base()`接口以异步任务方式提交函数执行。 387- 将函数访问的数据对象以及访问方式在`ffrt_submit_base()`接口中的`in_deps`和`out_deps`参数表达。 388- 程序员通过`in_deps`和`out_deps`参数表达任务间依赖关系以保证程序执行的正确性。 389 390> 做到纯函数的好处在于：1. 能够最大化挖掘并行度，2.避免DataRace和锁的问题。 391> 392> 在实际中，可以根据场景放松纯函数的约束，但前提是： 393> 394> - 确定添加的`in_deps`和`out_deps`可确保程序正确执行。 395> - 通过FFRT提供的锁机制保护对全局变量的访问。 396 397### 建议2：使用FFRT提供的替代API 398 399- 禁止在FFRT任务中使用系统线程库API创建线程，使用`submit`提交任务。 400- 使用FFRT提供的锁，条件变量，睡眠，IO等API代替系统线程库API。 401 - 使用系统线程库API可能造成工作线程阻塞，引起额外性能开销。 402 403### 建议3：Deadline机制 404 405- 必须用于具备周期/重复执行特征的处理流程。 406- 在有明确时间约束和性能关键的处理流程中使用，避免滥用。 407- 在相对大颗粒度的处理流程中使用，例如具有16.6ms时间约束的帧处理流程。 408 409### 建议4：从线程模型迁移 410 411- 创建线程替代为创建FFRT任务。 412 - 线程从逻辑上类似无`in_deps`的任务。 413- 识别线程间的依赖关系，并将其表达在任务的依赖关系`in_deps`和`out_deps`上。 414- 线程内计算过程分解为异步任务调用。 415- 通过任务依赖关系和锁机制避免并发任务数据竞争问题。 416 417### 建议5：推荐使用C++接口 418 419- FFRT的C++接口是基于C接口实现，在使用API接口时可以手动添加C++相关头文件后配套使用。 420 421## 约束限制 422 423### 线程局部变量使用约束 424 425FFRT Task中使用线程局部变量存在风险，说明如下： 426 427- 线程局部变量包括C/C++语言提供的`thread_local`定义的变量和使用`pthread_key_create`创建的变量。 428- FFRT支持任务调度，任务被调度到哪个线程是随机的，进而使用线程局部变量是有风险的，这一点和所有其他支持任务并发调度的框架一致。 429- FFRT的任务默认以协程的方式运行，任务执行过程中可能发生协程退出，恢复执行时，执行该任务的线程可能发生变更。 430 431### 线程绑定使用约束 432 433- FFRT支持任务调度，任务调度到哪个线程是随机的，thread_idx/线程优先级/线程亲和性等与线程绑定的行为禁止在任务中使用。 434 435### 标准库同步原语使用约束 436 437FFRT任务中使用标准库的互斥锁可能发生死锁，需要更换为FFRT提供的互斥锁，说明如下： 438 439- 互斥锁在`lock()`成功时记录调用者“执行栈”作为锁的所有者，在后续`lock()`时会判断调用者是否为当前执行栈，如果是则返回成功，以支持在同一个执行栈中嵌套获取锁。在标准库的实现中，“执行栈”以线程标识表示。 440- 在FFRT任务中使用标准库的互斥锁，如果在外层和内层`lock()`之间，发生任务（协程）退出，任务恢复执行时在不同于首次调用`lock()`的FFRT Worker线程上，则判断当前线程不是所有者，`lock()`失败，FFRT Worker线程被挂起，后面的`unlock()`不会被执行，从而出现死锁。 441 442### 对进程`fork()`场景的支持说明 443 444- 在未使用FFRT的进程中，创建子进程，支持在该子进程中使用FFRT。 445- 在已经使用FFRT的进程中，单独以`fork()`方式创建子进程，不支持在该子进程中使用FFRT。 446- 在已经使用FFRT的进程中，同时以`fork()`和`exec()`方式创建子进程，支持在子进程中使用FFRT。 447 448### 以动态库方式部署FFRT 449 450- 只能以动态库方式部署FFRT，静态库部署可能有多实例问题，例如：当多个被同一进程加载的so都以静态库的方式使用FFRT时，FFRT会被实例化成多份，其行为是未知的，这也不是FFRT设计的初衷。 451 452### 输入输出依赖数量的限制 453 454- 使用`ffrt_submit_base`接口进行任务提交时，每个任务的输入依赖和输出依赖的数量之和不能超过8个。 455- 使用`ffrt_submit_h_base`接口进行任务提交时，每个任务的输入依赖和输出依赖的数量之和不能超过7个。 456- 参数既作为输入依赖又作为输出依赖的时候，统计依赖数量时只统计一次，如输入依赖是`{&x}`，输出依赖也是`{&x}`，实际依赖的数量是1。 457 458## 常见反模式 459 460### C API中初始化FFRT对象后，对象的置空与销毁由用户负责 461 462- 为保证较高的性能，FFRT的C API中内部不包含对对象的销毁状态的标记，用户需要合理地进行资源的释放，重复调用各个对象的销毁操作，其结果是未定义的。 463- 错误示例1，重复调用销毁函数可能造成不可预知的数据损坏： 464 465 ```cpp 466 #include "ffrt.h" 467 void abnormal_case_1() 468 { 469 ffrt_task_handle_t h = ffrt_submit_h([](){printf("Test task running...\n");}, NULL, NULL, NULL, NULL, NULL); 470 // ... 471 ffrt_task_handle_destroy(h); 472 ffrt_task_handle_destroy(h); // 重复释放 473 } 474 ``` 475 476- 错误示例2，未调用销毁函数会造成内存泄漏： 477 478 ```cpp 479 #include "ffrt.h" 480 void abnormal_case_2() 481 { 482 ffrt_task_handle_t h = ffrt_submit_h([](){printf("Test task running...\n");}, NULL, NULL, NULL, NULL, NULL); 483 // ... 484 // 内存泄露 485 } 486 ``` 487 488- 建议示例，仅调用一次销毁函数，如有必要可进行置空： 489 490 ```cpp 491 #include "ffrt.h" 492 void normal_case() 493 { 494 ffrt_task_handle_t h = ffrt_submit_h([](){printf("Test task running...\n");}, NULL, NULL, NULL, NULL, NULL); 495 // ... 496 ffrt_task_handle_destroy(h); 497 h = nullptr; // 必要时置空任务句柄变量 498 } 499 ``` 500 501### 变量生命周期错误 502 503- FFRT提交任务中应注意对象或资源在其生命周期内可能出现的误用，这些错误会导致程序崩溃、数据损坏或者难以调试的问题。 504- 错误示例1，变量生命周期已结束导致的UAF问题： 505 506 ```cpp 507 #include "ffrt.h" 508 void abnormal_case_3() 509 { 510 int x = 0; 511 ffrt::submit([&] { 512 usleep(1000); // 模拟业务处理逻辑 513 x++; // 此时变量生命周期可能已结束，对变量的访问会发生UAF问题 514 }); 515 } 516 ``` 517 518- 错误示例2，互斥锁生命周期已结束继续使用导致功能异常： 519 520 ```cpp 521 #include "ffrt.h" 522 void abnormal_case_4() 523 { 524 ffrt::mutex lock; 525 ffrt::submit([&] { 526 lock.lock(); // 对FFRT锁进行操作时，要保证其生命周期 527 usleep(1000); // 模拟业务处理逻辑 528 lock.unlock(); // 对FFRT锁进行操作时，要保证其生命周期 529 }); 530 } 531 ``` 532 533## Using FFRT in DevEco IDE 534 535### Using FFRT C API 536 537NDK（Native Development Kit）是HarmonyOS SDK提供的Native API的集合，方便开发者使用C或C++语言实现应用的关键功能。 538 539FFRT C API已集成在NDK中，在DevEco IDE中可以直接使用对应的接口。 540 541```cpp 542#include "ffrt/task.h" 543#include "ffrt/type_def.h" 544#include "ffrt/condition_variable.h" 545#include "ffrt/loop.h" 546#include "ffrt/mutex.h" 547#include "ffrt/queue.h" 548#include "ffrt/sleep.h" 549#include "ffrt/timer.h" 550``` 551 552### Using FFRT C++ API 553 554FFRT的部署依赖FFRT动态库`libffrt.so`和一组头文件，其中动态库仅导出C接口，C++接口调用C接口，并基于头文件的方式将API中的C++元素编译到用户的动态库中，从而保证了ABI兼容性。 555 556 557 558如果要使用FFRT C++ API，需要使用FFRT三方库[@ppd/ffrt](https://ohpm.openharmony.cn/#/cn/detail/@ppd%2Fffrt)，该三方库是由FFRT官方维护的FFRT C++ API库。 559 560在模块目录下执行三方库安装命令： 561 562```shell 563ohpm install @ppd/ffrt 564``` 565 566也可以直接在`oh-package.json5`文件中配置对应的依赖，由IDE自动进行三方库下载安装。 567 568同时在模块`CMakeLists.txt`文件中添加依赖： 569 570```txt 571target_link_libraries(<target_name> PUBLIC libffrt.z.so ffrt::ffrtapi) 572``` 573 574至此就可以在代码中使用FFRT C++接口： 575 576```cpp 577#include "ffrt/cpp/task.h" 578#include "ffrt/cpp/condition_variable.h" 579#include "ffrt/cpp/mutex.h" 580#include "ffrt/cpp/queue.h" 581#include "ffrt/cpp/sleep.h" 582``` 583
