1# task.h 2 3<!--Kit: Function Flow Runtime Kit--> 4<!--Subsystem: Resourceschedule--> 5<!--Owner: @chuchihtung; @yanleo--> 6<!--Designer: @geoffrey_guo; @huangyouzhong--> 7<!--Tester: @lotsof; @sunxuhao--> 8<!--Adviser: @foryourself--> 9 10## 概述 11 12声明任务的C接口。 13 14**引用文件：** <ffrt/task.h> 15 16**库：** libffrt.z.so 17 18**系统能力：** SystemCapability.Resourceschedule.Ffrt.Core 19 20**起始版本：** 10 21 22**相关模块：** [FFRT](capi-ffrt.md) 23 24## 汇总 25 26### 函数 27 28| 名称 | 描述 | 29| -- | -- | 30| [FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr)](#ffrt_task_attr_init) | 初始化任务属性。 | 31| [FFRT_C_API void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name)](#ffrt_task_attr_set_name) | 设置任务名字。 | 32| [FFRT_C_API const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_name) | 获取任务名字。 | 33| [FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr)](#ffrt_task_attr_destroy) | 销毁任务属性。 | 34| [FFRT_C_API void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos)](#ffrt_task_attr_set_qos) | 设置任务QoS。 | 35| [FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_qos) | 获取任务QoS。 | 36| [FFRT_C_API void ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_us)](#ffrt_task_attr_set_delay) | 设置任务延迟时间。 | 37| [FFRT_C_API uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_delay) | 获取任务延迟时间。 | 38| [FFRT_C_API void ffrt_task_attr_set_queue_priority(ffrt_task_attr_t* attr, ffrt_queue_priority_t priority)](#ffrt_task_attr_set_queue_priority) | 设置并行队列任务优先级。 | 39| [FFRT_C_API ffrt_queue_priority_t ffrt_task_attr_get_queue_priority(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_queue_priority) | 获取并行队列任务优先级。 | 40| [FFRT_C_API void ffrt_task_attr_set_stack_size(ffrt_task_attr_t* attr, uint64_t size)](#ffrt_task_attr_set_stack_size) | 设置任务栈大小。 | 41| [FFRT_C_API uint64_t ffrt_task_attr_get_stack_size(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_stack_size) | 获取任务栈大小。 | 42| [FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos)](#ffrt_this_task_update_qos) | 更新任务QoS。 | 43| [FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(void)](#ffrt_this_task_get_qos) | 获取任务QoS。 | 44| [FFRT_C_API uint64_t ffrt_this_task_get_id(void)](#ffrt_this_task_get_id) | 获取任务id。 | 45| [FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind)](#ffrt_alloc_auto_managed_function_storage_base) | 申请函数执行结构的内存。 | 46| [FFRT_C_API void ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps,const ffrt_task_attr_t* attr)](#ffrt_submit_base) | 提交任务调度执行。 | 47| [FFRT_C_API ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps,const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)](#ffrt_submit_h_base) | 提交任务调度执行并返回任务句柄。 | 48| [FFRT_C_API void ffrt_submit_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps,const ffrt_task_attr_t* attr)](#ffrt_submit_f) | 提交任务调度执行，是ffrt_submit_base接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为通用任务结构，并将封装后的任务结构和其他参数传递给ffrt_submit_base接口。 | 49| [FFRT_C_API ffrt_task_handle_t ffrt_submit_h_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps,const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)](#ffrt_submit_h_f) | 提交任务调度执行并返回任务句柄，是ffrt_submit_h_base接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为通用任务结构，并将封装后的任务结构和其他参数传递给ffrt_submit_h_base接口。 | 50| [FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle)](#ffrt_task_handle_inc_ref) | 增加任务句柄的引用数。 | 51| [FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle)](#ffrt_task_handle_dec_ref) | 减少任务句柄的引用计数。 | 52| [FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle)](#ffrt_task_handle_destroy) | 销毁任务句柄。 | 53| [FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps)](#ffrt_wait_deps) | 等待依赖的任务完成，当前任务开始执行。 | 54| [FFRT_C_API void ffrt_wait(void)](#ffrt_wait) | 等待之前所有提交任务完成，当前任务开始执行。 | 55 56## 函数说明 57 58### ffrt_task_attr_init() 59 60``` 61FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr) 62``` 63 64**描述** 65 66初始化任务属性。 67 68**起始版本：** 10 69 70 71**参数：** 72 73| 参数项 | 描述 | 74| -- | -- | 75| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | 76 77**返回：** 78 79| 类型 | 说明 | 80| -- | -- | 81| FFRT_C_API int | 初始化任务属性成功返回0，<br> 初始化任务属性失败返回-1。 | 82 83### ffrt_task_attr_set_name() 84 85``` 86FFRT_C_API void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name) 87``` 88 89**描述** 90 91设置任务名字。 92 93**起始版本：** 10 94 95 96**参数：** 97 98| 参数项 | 描述 | 99| -- | -- | 100| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | 101| const char* name | 任务名字。 | 102 103### ffrt_task_attr_get_name() 104 105``` 106FFRT_C_API const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr) 107``` 108 109**描述** 110 111获取任务名字。 112 113**起始版本：** 10 114 115 116**参数：** 117 118| 参数项 | 描述 | 119| -- | -- | 120| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | 121 122**返回：** 123 124| 类型 | 说明 | 125| -- | -- | 126| FFRT_C_API const char* | 获取任务名字成功返回非空指针，<br> 获取任务名字失败返回空指针。 | 127 128### ffrt_task_attr_destroy() 129 130``` 131FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr) 132``` 133 134**描述** 135 136销毁任务属性。 137 138**起始版本：** 10 139 140 141**参数：** 142 143| 参数项 | 描述 | 144| -- | -- | 145| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | 146 147### ffrt_task_attr_set_qos() 148 149``` 150FFRT_C_API void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos) 151``` 152 153**描述** 154 155设置任务QoS。 156 157**起始版本：** 10 158 159 160**参数：** 161 162| 参数项 | 描述 | 163| -- | -- | 164| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | 165| [ffrt_qos_t](capi-type-def-h.md#变量) qos | 任务QoS。 | 166 167### ffrt_task_attr_get_qos() 168 169``` 170FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr) 171``` 172 173**描述** 174 175获取任务QoS。 176 177**起始版本：** 10 178 179 180**参数：** 181 182| 参数项 | 描述 | 183| -- | -- | 184| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | 185 186**返回：** 187 188| 类型 | 说明 | 189| -- | -- | 190| FFRT_C_API [ffrt_qos_t](capi-type-def-h.md#变量) | 返回任务的QoS，默认返回ffrt_qos_default。 | 191 192### ffrt_task_attr_set_delay() 193 194``` 195FFRT_C_API void ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_us) 196``` 197 198**描述** 199 200设置任务延迟时间。 201 202**起始版本：** 10 203 204 205**参数：** 206 207| 参数项 | 描述 | 208| -- | -- | 209| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | 210| uint64_t delay_us | 任务延迟时间，单位微秒。 | 211 212### ffrt_task_attr_get_delay() 213 214``` 215FFRT_C_API uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr) 216``` 217 218**描述** 219 220获取任务延迟时间。 221 222**起始版本：** 10 223 224 225**参数：** 226 227| 参数项 | 描述 | 228| -- | -- | 229| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | 230 231**返回：** 232 233| 类型 | 说明 | 234| -- | -- | 235| FFRT_C_API uint64_t | 返回任务的延迟时间。 | 236 237### ffrt_task_attr_set_queue_priority() 238 239``` 240FFRT_C_API void ffrt_task_attr_set_queue_priority(ffrt_task_attr_t* attr, ffrt_queue_priority_t priority) 241``` 242 243**描述** 244 245设置并行队列任务优先级。 246 247**起始版本：** 12 248 249 250**参数：** 251 252| 参数项 | 描述 | 253| -- | -- | 254| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | 255| [ffrt_queue_priority_t](capi-type-def-h.md#ffrt_queue_priority_t) priority | 任务优先级。 | 256 257### ffrt_task_attr_get_queue_priority() 258 259``` 260FFRT_C_API ffrt_queue_priority_t ffrt_task_attr_get_queue_priority(const ffrt_task_attr_t* attr) 261``` 262 263**描述** 264 265获取并行队列任务优先级。 266 267**起始版本：** 12 268 269 270**参数：** 271 272| 参数项 | 描述 | 273| -- | -- | 274| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | 275 276**返回：** 277 278| 类型 | 说明 | 279| -- | -- | 280| FFRT_C_API [ffrt_queue_priority_t](capi-type-def-h.md#ffrt_queue_priority_t) | 返回任务优先级。 | 281 282### ffrt_task_attr_set_stack_size() 283 284``` 285FFRT_C_API void ffrt_task_attr_set_stack_size(ffrt_task_attr_t* attr, uint64_t size) 286``` 287 288**描述** 289 290设置任务栈大小。 291 292**起始版本：** 12 293 294 295**参数：** 296 297| 参数项 | 描述 | 298| -- | -- | 299| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | 300| uint64_t size | 任务栈大小，单位是字节。 | 301 302### ffrt_task_attr_get_stack_size() 303 304``` 305FFRT_C_API uint64_t ffrt_task_attr_get_stack_size(const ffrt_task_attr_t* attr) 306``` 307 308**描述** 309 310获取任务栈大小。 311 312**起始版本：** 12 313 314 315**参数：** 316 317| 参数项 | 描述 | 318| -- | -- | 319| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性指针。 | 320 321**返回：** 322 323| 类型 | 说明 | 324| -- | -- | 325| FFRT_C_API uint64_t | 返回任务栈大小，单位是字节。 | 326 327### ffrt_this_task_update_qos() 328 329``` 330FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos) 331``` 332 333**描述** 334 335更新任务QoS。 336 337**起始版本：** 10 338 339 340**参数：** 341 342| 参数项 | 描述 | 343| -- | -- | 344| [ffrt_qos_t](capi-type-def-h.md#变量) qos | 当前任务待更新的QoS。 | 345 346**返回：** 347 348| 类型 | 说明 | 349| -- | -- | 350| FFRT_C_API int | 更新任务QoS成功返回0，<br> 更新任务QoS失败返回-1。 | 351 352### ffrt_this_task_get_qos() 353 354``` 355FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(void) 356``` 357 358**描述** 359 360获取任务QoS。 361 362**起始版本：** 12 363 364**返回：** 365 366| 类型 | 说明 | 367| -- | -- | 368| FFRT_C_API [ffrt_qos_t](capi-type-def-h.md#变量) | 返回任务QoS。 | 369 370### ffrt_this_task_get_id() 371 372``` 373FFRT_C_API uint64_t ffrt_this_task_get_id(void) 374``` 375 376**描述** 377 378获取任务id。 379 380**起始版本：** 10 381 382**返回：** 383 384| 类型 | 说明 | 385| -- | -- | 386| FFRT_C_API uint64_t | 返回当前任务的id。 | 387 388### ffrt_alloc_auto_managed_function_storage_base() 389 390``` 391FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind) 392``` 393 394**描述** 395 396申请函数执行结构的内存。 397 398**起始版本：** 10 399 400 401**参数：** 402 403| 参数项 | 描述 | 404| -- | -- | 405| [ffrt_function_kind_t](capi-type-def-h.md#ffrt_function_kind_t) kind | 函数执行结构类型，支持通用和队列函数执行结构类型。 | 406 407**返回：** 408 409| 类型 | 说明 | 410| -- | -- | 411| FFRT_C_API void * | 申请函数执行结构成功返回非空指针，<br> 申请函数执行结构失败返回空指针。 | 412 413### ffrt_submit_base() 414 415``` 416FFRT_C_API void ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps,const ffrt_task_attr_t* attr) 417``` 418 419**描述** 420 421提交任务调度执行。 422 423**起始版本：** 10 424 425 426**参数：** 427 428| 参数项 | 描述 | 429| -- | -- | 430| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 任务执行体封装的指针。 | 431| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | 输入依赖指针。 | 432| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | 输出依赖指针。 | 433| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | 434 435### ffrt_submit_h_base() 436 437``` 438FFRT_C_API ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps,const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr) 439``` 440 441**描述** 442 443提交任务调度执行并返回任务句柄。 444 445**起始版本：** 10 446 447 448**参数：** 449 450| 参数项 | 描述 | 451| -- | -- | 452| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 任务执行体封装的指针。 | 453| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | 输入依赖指针。 | 454| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | 输出依赖指针。 | 455| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | 456 457**返回：** 458 459| 类型 | 说明 | 460| -- | -- | 461| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | 提交任务成功返回非空任务句柄，<br> 提交任务失败返回空指针。 | 462 463### ffrt_submit_f() 464 465``` 466FFRT_C_API void ffrt_submit_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps,const ffrt_task_attr_t* attr) 467``` 468 469**描述** 470 471提交任务调度执行，是ffrt_submit_base接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为通用任务结构，并将封装后的任务结构和其他参数传递给ffrt_submit_base接口。 472 473**起始版本：** 20 474 475 476**参数：** 477 478| 参数项 | 描述 | 479| -- | -- | 480| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | 指定的任务函数。 | 481| void* arg | 传递给任务函数的参数。 | 482| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | 输入依赖指针。 | 483| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | 输出依赖指针。 | 484| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | 485 486**参考：** 487 488[ffrt_submit_base](capi-task-h.md#ffrt_submit_base) 489 490 491### ffrt_submit_h_f() 492 493``` 494FFRT_C_API ffrt_task_handle_t ffrt_submit_h_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps,const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr) 495``` 496 497**描述** 498 499提交任务调度执行并返回任务句柄，是ffrt_submit_h_base接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为通用任务结构，并将封装后的任务结构和其他参数传递给ffrt_submit_h_base接口。 500 501**起始版本：** 20 502 503 504**参数：** 505 506| 参数项 | 描述 | 507| -- | -- | 508| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | 指定的任务函数。 | 509| void* arg | 传递给任务函数的参数。 | 510| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | 输入依赖指针。 | 511| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | 输出依赖指针。 | 512| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | 513 514**返回：** 515 516| 类型 | 说明 | 517| -- | -- | 518| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | 提交任务成功返回非空任务句柄，<br> 提交任务失败返回空指针。 | 519 520**参考：** 521 522[ffrt_submit_h_base](capi-task-h.md#ffrt_submit_h_base) 523 524 525### ffrt_task_handle_inc_ref() 526 527``` 528FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle) 529``` 530 531**描述** 532 533增加任务句柄的引用数。 534 535**起始版本：** 12 536 537 538**参数：** 539 540| 参数项 | 描述 | 541| -- | -- | 542| [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) handle | 任务句柄。 | 543 544**返回：** 545 546| 类型 | 说明 | 547| -- | -- | 548| FFRT_C_API uint32_t | 返回任务句柄原始引用计数。 | 549 550### ffrt_task_handle_dec_ref() 551 552``` 553FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle) 554``` 555 556**描述** 557 558减少任务句柄的引用计数。 559 560**起始版本：** 12 561 562 563**参数：** 564 565| 参数项 | 描述 | 566| -- | -- | 567| [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) handle | 任务句柄。 | 568 569**返回：** 570 571| 类型 | 说明 | 572| -- | -- | 573| FFRT_C_API uint32_t | 返回任务句柄原始引用计数。 | 574 575### ffrt_task_handle_destroy() 576 577``` 578FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle) 579``` 580 581**描述** 582 583销毁任务句柄。 584 585**起始版本：** 10 586 587 588**参数：** 589 590| 参数项 | 描述 | 591| -- | -- | 592| [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) handle | 任务句柄。 | 593 594### ffrt_wait_deps() 595 596``` 597FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps) 598``` 599 600**描述** 601 602等待依赖的任务完成，当前任务开始执行。 603 604**起始版本：** 10 605 606 607**参数：** 608 609| 参数项 | 描述 | 610| -- | -- | 611| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* deps | 依赖的指针。 | 612 613### ffrt_wait() 614 615``` 616FFRT_C_API void ffrt_wait(void) 617``` 618 619**描述** 620 621等待之前所有提交任务完成，当前任务开始执行。 622 623**起始版本：** 10 624 625 626