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## Overview 11 12The **task.h** file declares the task APIs in C. 13 14**File to include**: <ffrt/task.h> 15 16**Library**: libffrt.z.so 17 18**System capability**: SystemCapability.Resourceschedule.Ffrt.Core 19 20**Since**: 10 21 22**Related module**: [FFRT](capi-ffrt.md) 23 24## Summary 25 26### Function 27 28| Name| Description| 29| -- | -- | 30| [FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr)](#ffrt_task_attr_init) | Initializes a task attribute.| 31| [FFRT_C_API void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name)](#ffrt_task_attr_set_name) | Sets a task name.| 32| [FFRT_C_API const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_name) | Obtains a task name.| 33| [FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr)](#ffrt_task_attr_destroy) | Destroys a task attribute.| 34| [FFRT_C_API void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos)](#ffrt_task_attr_set_qos) | Sets the task QoS.| 35| [FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_qos) | Obtains the task 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) | Sets the task delay time.| 37| [FFRT_C_API uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr)](#ffrt_task_attr_get_delay) | Obtains the task delay time.| 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) | Sets the task priority in the queue.| 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) | Obtains the task priority in the queue.| 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) | Sets the task 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) | Obtains the task stack size.| 42| [FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos)](#ffrt_this_task_update_qos) | Updates the task QoS.| 43| [FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(void)](#ffrt_this_task_get_qos) | Obtains the task QoS.| 44| [FFRT_C_API uint64_t ffrt_this_task_get_id(void)](#ffrt_this_task_get_id) | Obtains the ID of this task.| 45| [FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind)](#ffrt_alloc_auto_managed_function_storage_base) | Applies for memory for the task execution function struct.| 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) | Submits a task.| 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) | Submits a task, and obtains the task handle.| 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) | Submits a task. It is a simplified wrapper of **ffrt_submit_base**. This API assumes that the callback function does not need to be destroyed. The task function and parameters are encapsulated into a general task structure, which is then passed to **ffrt_submit_base** along with other parameters.| 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) | Submits a task, and obtains the task handle. It is a simplified wrapper of **ffrt_submit_h_base**. This API assumes that the callback function does not need to be destroyed. The task function and parameters are encapsulated into a general task structure, which is then passed to **ffrt_submit_h_base** along with other parameters.| 50| [FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle)](#ffrt_task_handle_inc_ref) | Increases the number of task handle references.| 51| [FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle)](#ffrt_task_handle_dec_ref) | Decreases the number of task handle references.| 52| [FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle)](#ffrt_task_handle_destroy) | Destroys a task handle.| 53| [FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps)](#ffrt_wait_deps) | Waits until the dependent tasks are complete.| 54| [FFRT_C_API void ffrt_wait(void)](#ffrt_wait) | Waits until all submitted tasks are complete.| 55 56## Function Description 57 58### ffrt_task_attr_init() 59 60``` 61FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr) 62``` 63 64**Description** 65 66Initializes a task attribute. 67 68**Since**: 10 69 70 71**Parameters** 72 73| Name| Description| 74| -- | -- | 75| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 76 77**Returns** 78 79| Type| Description| 80| -- | -- | 81| FFRT_C_API int | Returns **0** if the task attribute is initialized;<br> returns **-1** otherwise.| 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**Description** 90 91Sets a task name. 92 93**Since**: 10 94 95 96**Parameters** 97 98| Name| Description| 99| -- | -- | 100| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 101| const char* name | Pointer to the task 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**Description** 110 111Obtains a task name. 112 113**Since**: 10 114 115 116**Parameters** 117 118| Name| Description| 119| -- | -- | 120| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 121 122**Returns** 123 124| Type| Description| 125| -- | -- | 126| FFRT_C_API const char* | Returns a non-null pointer to the task name if the name is obtained;<br> returns a null pointer otherwise.| 127 128### ffrt_task_attr_destroy() 129 130``` 131FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr) 132``` 133 134**Description** 135 136Destroys a task attribute. 137 138**Since**: 10 139 140 141**Parameters** 142 143| Name| Description| 144| -- | -- | 145| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 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**Description** 154 155Sets the task QoS. 156 157**Since**: 10 158 159 160**Parameters** 161 162| Name | Description| 163|---------------------------------------------------------| -- | 164| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 165| [ffrt_qos_t](capi-type-def-h.md#variables) qos | Task 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**Description** 174 175Obtains the task QoS. 176 177**Since**: 10 178 179 180**Parameters** 181 182| Name| Description| 183| -- | -- | 184| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 185 186**Returns** 187 188| Type| Description| 189| -- | -- | 190| FFRT_C_API [ffrt_qos_t](capi-type-def-h.md#variables)| Returns the QoS, which is **ffrt_qos_default** by 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**Description** 199 200Sets the task delay time. 201 202**Since**: 10 203 204 205**Parameters** 206 207| Name| Description| 208| -- | -- | 209| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 210| uint64_t delay_us | Delay time, in microseconds.| 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**Description** 219 220Obtains the task delay time. 221 222**Since**: 10 223 224 225**Parameters** 226 227| Name| Description| 228| -- | -- | 229| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 230 231**Returns** 232 233| Type| Description| 234| -- | -- | 235| FFRT_C_API uint64_t | Returns the delay time.| 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**Description** 244 245Sets the task priority in the queue. 246 247**Since**: 12 248 249 250**Parameters** 251 252| Name| Description| 253| -- | -- | 254| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 255| [ffrt_queue_priority_t](capi-type-def-h.md#ffrt_queue_priority_t) priority | Task 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**Description** 264 265Obtains the task priority in the queue. 266 267**Since**: 12 268 269 270**Parameters** 271 272| Name| Description| 273| -- | -- | 274| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 275 276**Returns** 277 278| Type | Description| 279|---------------------------------------------------------| -- | 280| FFRT_C_API [ffrt_queue_priority_t](capi-type-def-h.md#ffrt_queue_priority_t) | Returns the task priority.| 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**Description** 289 290Sets the task stack size. 291 292**Since**: 12 293 294 295**Parameters** 296 297| Name| Description| 298| -- | -- | 299| [ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 300| uint64_t size | Size of the task stack, in bytes.| 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**Description** 309 310Obtains the task stack size. 311 312**Since**: 12 313 314 315**Parameters** 316 317| Name| Description| 318| -- | -- | 319| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 320 321**Returns** 322 323| Type| Description| 324| -- | -- | 325| FFRT_C_API uint64_t | Returns the task stack size, in bytes.| 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**Description** 334 335Updates the task QoS. 336 337**Since**: 10 338 339 340**Parameters** 341 342| Name| Description| 343| -- | -- | 344| [ffrt_qos_t](capi-type-def-h.md#variables) qos| QoS to be updated.| 345 346**Returns** 347 348| Type| Description| 349| -- | -- | 350| FFRT_C_API int | Returns **0** if the QoS is updated;<br> returns **-1** otherwise.| 351 352### ffrt_this_task_get_qos() 353 354``` 355FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(void) 356``` 357 358**Description** 359 360Obtains the task QoS. 361 362**Since**: 12 363 364**Returns** 365 366| Type| Description| 367| -- | -- | 368| FFRT_C_API [ffrt_qos_t](capi-type-def-h.md#variables)| Returns the task QoS.| 369 370### ffrt_this_task_get_id() 371 372``` 373FFRT_C_API uint64_t ffrt_this_task_get_id(void) 374``` 375 376**Description** 377 378Obtains the ID of this task. 379 380**Since**: 10 381 382**Returns** 383 384| Type| Description| 385| -- | -- | 386| FFRT_C_API uint64_t | Returns the 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**Description** 395 396Applies for memory for the task execution function struct. 397 398**Since**: 10 399 400 401**Parameters** 402 403| Name| Description| 404| -- | -- | 405| [ffrt_function_kind_t](capi-type-def-h.md#ffrt_function_kind_t) kind | Type of the task execution function, which can be general or queue.| 406 407**Returns** 408 409| Type| Description| 410| -- | -- | 411| FFRT_C_API void * | Returns a non-null pointer if the memory is allocated;<br> returns a null pointer otherwise.| 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**Description** 420 421Submits a task. 422 423**Since**: 10 424 425 426**Parameters** 427 428| Name| Description| 429| -- | -- | 430| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | Pointer to the task execution function.| 431| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | Pointer to the input dependencies.| 432| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | Pointer to the output dependencies.| 433| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 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**Description** 442 443Submits a task, and obtains the task handle. 444 445**Since**: 10 446 447 448**Parameters** 449 450| Name| Description| 451| -- | -- | 452| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | Pointer to the task execution function.| 453| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | Pointer to the input dependencies.| 454| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | Pointer to the output dependencies.| 455| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 456 457**Returns** 458 459| Type | Description| 460|-----------------------------------| -- | 461| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | Returns a non-null task handle if the task is submitted;<br> returns a null pointer otherwise.| 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**Description** 470 471Submits a task. It is a simplified wrapper of **ffrt_submit_base**. This API assumes that the callback function does not need to be destroyed. The task function and parameters are encapsulated into a general task structure, which is then passed to **ffrt_submit_base** along with other parameters. 472 473**Since**: 20 474 475 476**Parameters** 477 478| Name| Description| 479| -- | -- | 480| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | Task function.| 481| void* arg | Pointer to the argument.| 482| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | Pointer to the input dependencies.| 483| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | Pointer to the output dependencies.| 484| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 485 486**References** 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**Description** 498 499Submits a task, and obtains the task handle. It is a simplified wrapper of **ffrt_submit_h_base**. This API assumes that the callback function does not need to be destroyed. The task function and parameters are encapsulated into a general task structure, which is then passed to **ffrt_submit_h_base** along with other parameters. 500 501**Since**: 20 502 503 504**Parameters** 505 506| Name| Description| 507| -- | -- | 508| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | Task function.| 509| void* arg | Pointer to the argument.| 510| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* in_deps | Pointer to the input dependencies.| 511| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* out_deps | Pointer to the output dependencies.| 512| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 513 514**Returns** 515 516| Type| Description| 517| -- | -- | 518| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | Returns a non-null task handle if the task is submitted;<br> returns a null pointer otherwise.| 519 520**References** 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**Description** 532 533Increases the number of task handle references. 534 535**Since**: 12 536 537 538**Parameters** 539 540| Name| Description| 541| -- | -- | 542| [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) handle | Task handle.| 543 544**Returns** 545 546| Type| Description| 547| -- | -- | 548| FFRT_C_API uint32_t | Returns the original number of task handle references.| 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**Description** 557 558Decreases the number of task handle references. 559 560**Since**: 12 561 562 563**Parameters** 564 565| Name| Description| 566| -- | -- | 567| [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) handle | Task handle.| 568 569**Returns** 570 571| Type| Description| 572| -- | -- | 573| FFRT_C_API uint32_t | Returns the original number of task handle references.| 574 575### ffrt_task_handle_destroy() 576 577``` 578FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle) 579``` 580 581**Description** 582 583Destroys a task handle. 584 585**Since**: 10 586 587 588**Parameters** 589 590| Name| Description| 591| -- | -- | 592| [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) handle | Task handle.| 593 594### ffrt_wait_deps() 595 596``` 597FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps) 598``` 599 600**Description** 601 602Waits until the dependent tasks are complete. 603 604**Since**: 10 605 606 607**Parameters** 608 609| Name| Description| 610| -- | -- | 611| [const ffrt_deps_t](capi-ffrt-ffrt-deps-t.md)* deps | Pointer to the dependencies.| 612 613### ffrt_wait() 614 615``` 616FFRT_C_API void ffrt_wait(void) 617``` 618 619**Description** 620 621Waits until all submitted tasks are complete. 622 623**Since**: 10 624