1# FFRT 2 3 4## Overview 5 6Function Flow Runtime (FFRT) is a software runtime library that works with the Function Flow programming model. It is used to schedule and execute tasks of an application developed on the Function Flow programming model. 7 8**System capability**: SystemCapability.Resourceschedule.Ffrt.Core 9 10**Since**: 10 11 12 13## Summary 14 15 16### Files 17 18| Name| Description| 19| -------- | -------- | 20| [condition_variable.h](condition__variable_8h.md) | Declares the condition variable interfaces in C.| 21| [mutex.h](mutex_8h.md) | Declares the mutex interfaces in C.| 22| [queue.h](queue_8h.md) | Declares the queue interfaces in C.| 23| [sleep.h](sleep_8h.md) | Declares the sleep and yield interfaces in C.| 24| [task.h](task_8h.md) | Declares the task interfaces in C.| 25| [type_def.h](type__def_8h.md) | Declares the common types.| 26 27 28### Structs 29 30| Name| Description| 31| -------- | -------- | 32| struct [ffrt_function_header_t](ffrt__function__header__t.md) | Describes a task executor.| 33| struct [ffrt_dependence_t](ffrt__dependence__t.md) | Describes a dependency.| 34| struct [ffrt_deps_t](ffrt__deps__t.md) | Describes dependencies.| 35| struct [ffrt_task_attr_t](ffrt__task__attr__t.md) | Describes a task attribute.| 36| struct [ffrt_queue_attr_t](ffrt__queue__attr__t.md) | Describes a queue attribute.| 37| struct [ffrt_condattr_t](ffrt__condattr__t.md) | Describes a condition variable attribute.| 38| struct [ffrt_mutexattr_t](ffrt__mutexattr__t.md) | Describes a mutex attribute.| 39| struct [ffrt_mutex_t](ffrt__mutex__t.md) | Describes a mutex.| 40| struct [ffrt_cond_t](ffrt__cond__t.md) | Describes a condition variable.| 41 42 43### Types 44 45| Name| Description| 46| -------- | -------- | 47| typedef void \* ffrt_queue_t | Defines the handle to a queue.| 48| typedef int ffrt_qos_t | Defines the QoS type.| 49| typedef void(\* ffrt_function_t ) (void \*) | Defines the type of the pointer to a task execution function.| 50| typedef void \* ffrt_task_handle_t | Defines the handle to a task.| 51 52 53### Enums 54 55| Name| Description| 56| -------- | -------- | 57| [ffrt_queue_type_t](#ffrt_queue_type_t) { ffrt_queue_serial, **ffrt_queue_max** } | Enumerates the queue types.| 58| [ffrt_qos_default_t](#ffrt_qos_default_t) {<br>ffrt_qos_inherit = -1, ffrt_qos_background, ffrt_qos_utility, ffrt_qos_default,<br>ffrt_qos_user_initiated<br>} | Enumerates the task QoS types.| 59| [ffrt_storage_size_t](#ffrt_storage_size_t) {<br>ffrt_task_attr_storage_size = 128, ffrt_auto_managed_function_storage_size = 64 + sizeof(ffrt_function_header_t), ffrt_mutex_storage_size = 64, ffrt_cond_storage_size = 64,<br>ffrt_queue_attr_storage_size = 128<br>} | Enumerates the storage sizes available for different types of structs.| 60| [ffrt_function_kind_t](#ffrt_function_kind_t) { ffrt_function_kind_general, ffrt_function_kind_queue } | Enumerates the task types.| 61| [ffrt_dependence_type_t](#ffrt_dependence_type_t) { ffrt_dependence_data, ffrt_dependence_task } | Enumerates the dependency types.| 62| [ffrt_error_t](#ffrt_error_t) {<br>ffrt_error = -1, ffrt_success = 0, ffrt_error_nomem = ENOMEM, ffrt_error_timedout = ETIMEDOUT,<br>ffrt_error_busy = EBUSY, ffrt_error_inval = EINVAL<br>} | Enumerates the FFRT error codes.| 63 64 65### Functions 66 67| Name| Description| 68| -------- | -------- | 69| FFRT_C_API int [ffrt_cond_init](#ffrt_cond_init) ([ffrt_cond_t](ffrt__cond__t.md) \*cond, const [ffrt_condattr_t](ffrt__condattr__t.md) \*attr) | Initializes a condition variable.| 70| FFRT_C_API int [ffrt_cond_signal](#ffrt_cond_signal) ([ffrt_cond_t](ffrt__cond__t.md) \*cond) | Unblocks at least one of the threads that are blocked on a condition variable.| 71| FFRT_C_API int [ffrt_cond_broadcast](#ffrt_cond_broadcast) ([ffrt_cond_t](ffrt__cond__t.md) \*cond) | Unblocks all threads currently blocked on a condition variable.| 72| FFRT_C_API int [ffrt_cond_wait](#ffrt_cond_wait) ([ffrt_cond_t](ffrt__cond__t.md) \*cond, [ffrt_mutex_t](ffrt__mutex__t.md) \*mutex) | Blocks the calling thread on a condition variable.| 73| FFRT_C_API int [ffrt_cond_timedwait](#ffrt_cond_timedwait) ([ffrt_cond_t](ffrt__cond__t.md) \*cond, [ffrt_mutex_t](ffrt__mutex__t.md) \*mutex, const struct timespec \*time_point) | Blocks the calling thread on a condition variable for a given duration.| 74| FFRT_C_API int [ffrt_cond_destroy](#ffrt_cond_destroy) ([ffrt_cond_t](ffrt__cond__t.md) \*cond) | Destroys a condition variable.| 75| FFRT_C_API int [ffrt_mutex_init](#ffrt_mutex_init) ([ffrt_mutex_t](ffrt__mutex__t.md) \*mutex, const [ffrt_mutexattr_t](ffrt__mutexattr__t.md) \*attr) | Initializes a mutex.| 76| FFRT_C_API int [ffrt_mutex_lock](#ffrt_mutex_lock) ([ffrt_mutex_t](ffrt__mutex__t.md) \*mutex) | Locks a mutex.| 77| FFRT_C_API int [ffrt_mutex_unlock](#ffrt_mutex_unlock) ([ffrt_mutex_t](ffrt__mutex__t.md) \*mutex) | Unlocks a mutex.| 78| FFRT_C_API int [ffrt_mutex_trylock](#ffrt_mutex_trylock) ([ffrt_mutex_t](ffrt__mutex__t.md) \*mutex) | Attempts to lock a mutex.| 79| FFRT_C_API int [ffrt_mutex_destroy](#ffrt_mutex_destroy) ([ffrt_mutex_t](ffrt__mutex__t.md) \*mutex) | Destroys a mutex.| 80| FFRT_C_API int [ffrt_queue_attr_init](#ffrt_queue_attr_init) ([ffrt_queue_attr_t](ffrt__queue__attr__t.md) \*attr) | Initializes a queue attribute.| 81| FFRT_C_API void [ffrt_queue_attr_destroy](#ffrt_queue_attr_destroy) ([ffrt_queue_attr_t](ffrt__queue__attr__t.md) \*attr) | Destroys a queue attribute.| 82| FFRT_C_API void [ffrt_queue_attr_set_qos](#ffrt_queue_attr_set_qos) ([ffrt_queue_attr_t](ffrt__queue__attr__t.md) \*attr, ffrt_qos_t qos) | Sets the queue QoS.| 83| FFRT_C_API ffrt_qos_t[ffrt_queue_attr_get_qos](#ffrt_queue_attr_get_qos) (const [ffrt_queue_attr_t](ffrt__queue__attr__t.md) \*attr) | Obtains the queue QoS.| 84| FFRT_C_API void [ffrt_queue_attr_set_timeout](#ffrt_queue_attr_set_timeout) ([ffrt_queue_attr_t](ffrt__queue__attr__t.md) \*attr, uint64_t timeout_us) | Sets the queue timeout.| 85| FFRT_C_API uint64_t [ffrt_queue_attr_get_timeout](#ffrt_queue_attr_get_timeout) (const [ffrt_queue_attr_t](ffrt__queue__attr__t.md) \*attr) | Obtains the queue timeout.| 86| FFRT_C_API void [ffrt_queue_attr_set_callback](#ffrt_queue_attr_set_callback) ([ffrt_queue_attr_t](ffrt__queue__attr__t.md) \*attr, [ffrt_function_header_t](ffrt__function__header__t.md) \*f) | Sets a callback that is invoked when a queue task times out.| 87| FFRT_C_API [ffrt_function_header_t](ffrt__function__header__t.md) \* [ffrt_queue_attr_get_callback](#ffrt_queue_attr_get_callback) (const [ffrt_queue_attr_t](ffrt__queue__attr__t.md) \*attr) | Obtains the callback that is invoked when a queue task times out.| 88| FFRT_C_API ffrt_queue_t[ffrt_queue_create](#ffrt_queue_create) ([ffrt_queue_type_t](#ffrt_queue_type_t) type, const char \*name, const [ffrt_queue_attr_t](ffrt__queue__attr__t.md) \*attr) | Creates a queue.| 89| FFRT_C_API void [ffrt_queue_destroy](#ffrt_queue_destroy) (ffrt_queue_t queue) | Destroys a queue.| 90| FFRT_C_API void [ffrt_queue_submit](#ffrt_queue_submit) (ffrt_queue_t queue, [ffrt_function_header_t](ffrt__function__header__t.md) \*f, const [ffrt_task_attr_t](ffrt__task__attr__t.md) \*attr) | Submits a task to a queue.| 91| FFRT_C_API ffrt_task_handle_t[ffrt_queue_submit_h](#ffrt_queue_submit_h) (ffrt_queue_t queue, [ffrt_function_header_t](ffrt__function__header__t.md) \*f, const [ffrt_task_attr_t](ffrt__task__attr__t.md) \*attr) | Submits a task to a queue, and obtains a task handle.| 92| FFRT_C_API void [ffrt_queue_wait](#ffrt_queue_wait) (ffrt_task_handle_t handle) | Waits until a task in the queue is complete.| 93| FFRT_C_API int [ffrt_queue_cancel](#ffrt_queue_cancel) (ffrt_task_handle_t handle) | Cancels a task in the queue.| 94| FFRT_C_API int [ffrt_usleep](#ffrt_usleep) (uint64_t usec) | Suspends the calling thread for a given duration.| 95| FFRT_C_API void [ffrt_yield](#ffrt_yield) (void) | Passes control to other tasks so that they can be executed.| 96| FFRT_C_API int [ffrt_task_attr_init](#ffrt_task_attr_init) ([ffrt_task_attr_t](ffrt__task__attr__t.md) \*attr) | Initializes a task attribute.| 97| FFRT_C_API void [ffrt_task_attr_set_name](#ffrt_task_attr_set_name) ([ffrt_task_attr_t](ffrt__task__attr__t.md) \*attr, const char \*name) | Sets a task name.| 98| FFRT_C_API const char \* [ffrt_task_attr_get_name](#ffrt_task_attr_get_name) (const [ffrt_task_attr_t](ffrt__task__attr__t.md) \*attr) | Obtains a task name.| 99| FFRT_C_API void [ffrt_task_attr_destroy](#ffrt_task_attr_destroy) ([ffrt_task_attr_t](ffrt__task__attr__t.md) \*attr) | Destroys a task attribute.| 100| FFRT_C_API void [ffrt_task_attr_set_qos](#ffrt_task_attr_set_qos) ([ffrt_task_attr_t](ffrt__task__attr__t.md) \*attr, ffrt_qos_t qos) | Sets the task QoS.| 101| FFRT_C_API ffrt_qos_t[ffrt_task_attr_get_qos](#ffrt_task_attr_get_qos) (const [ffrt_task_attr_t](ffrt__task__attr__t.md) \*attr) | Obtains the task QoS.| 102| FFRT_C_API void [ffrt_task_attr_set_delay](#ffrt_task_attr_set_delay) ([ffrt_task_attr_t](ffrt__task__attr__t.md) \*attr, uint64_t delay_us) | Sets the task delay time.| 103| FFRT_C_API uint64_t [ffrt_task_attr_get_delay](#ffrt_task_attr_get_delay) (const [ffrt_task_attr_t](ffrt__task__attr__t.md) \*attr) | Obtains the task delay time.| 104| FFRT_C_API int [ffrt_this_task_update_qos](#ffrt_this_task_update_qos) (ffrt_qos_t qos) | Updates the task QoS.| 105| FFRT_C_API uint64_t [ffrt_this_task_get_id](#ffrt_this_task_get_id) (void) | Obtains the task ID.| 106| FFRT_C_API void \* [ffrt_alloc_auto_managed_function_storage_base](#ffrt_alloc_auto_managed_function_storage_base) ([ffrt_function_kind_t](#ffrt_function_kind_t) kind) | Applies for memory for the task execution function struct.| 107| FFRT_C_API void [ffrt_submit_base](#ffrt_submit_base) ([ffrt_function_header_t](ffrt__function__header__t.md) \*f, const [ffrt_deps_t](ffrt__deps__t.md) \*in_deps, const [ffrt_deps_t](ffrt__deps__t.md) \*out_deps, const [ffrt_task_attr_t](ffrt__task__attr__t.md) \*attr) | Submits a task.| 108| FFRT_C_API ffrt_task_handle_t[ffrt_submit_h_base](#ffrt_submit_h_base) ([ffrt_function_header_t](ffrt__function__header__t.md) \*f, const [ffrt_deps_t](ffrt__deps__t.md) \*in_deps, const [ffrt_deps_t](ffrt__deps__t.md) \*out_deps, const [ffrt_task_attr_t](ffrt__task__attr__t.md) \*attr) | Submits a task, and obtains a task handle.| 109| FFRT_C_API void [ffrt_task_handle_destroy](#ffrt_task_handle_destroy) (ffrt_task_handle_t handle) | Destroys a task handle.| 110| FFRT_C_API void [ffrt_wait_deps](#ffrt_wait_deps) (const [ffrt_deps_t](ffrt__deps__t.md) \*deps) | Waits until the dependent tasks are complete.| 111| FFRT_C_API void [ffrt_wait](#ffrt_wait) (void) | Waits until all submitted tasks are complete.| 112 113 114### Variables 115 116| Name| Description| 117| -------- | -------- | 118| ffrt_function_t[ffrt_function_header_t::exec](#exec) | Function used to execute a task.| 119| ffrt_function_t[ffrt_function_header_t::destroy](#destroy) | Function used to destroy a task.| 120| uint64_t [ffrt_function_header_t::reserve](#reserve) [2] | Reserved bit.| 121| [ffrt_dependence_type_t](#ffrt_dependence_type_t)[ffrt_dependence_t::type](#type) | Dependency type.| 122| const void \* [ffrt_dependence_t::ptr](#ptr) | Address of the dependency data.| 123| uint32_t [ffrt_deps_t::len](#len) | Number of dependencies.| 124| const [ffrt_dependence_t](ffrt__dependence__t.md) \* [ffrt_deps_t::items](#items) | Dependency data.| 125| uint32_t [ffrt_task_attr_t::storage](#storage-46) [(ffrt_task_attr_storage_size+sizeof(uint32_t) - 1)/sizeof(uint32_t)] | Storage size of a task attribute.| 126| uint32_t [ffrt_queue_attr_t::storage](#storage-36) [(ffrt_queue_attr_storage_size+sizeof(uint32_t) - 1)/sizeof(uint32_t)] | Storage size of a queue attribute.| 127| long [ffrt_condattr_t::storage](#storage-56) | Storage size of a condition variable attribute.| 128| long [ffrt_mutexattr_t::storage](#storage-66) | Storage size of a mutex attribute.| 129| uint32_t [ffrt_mutex_t::storage](#storage-26) [(ffrt_mutex_storage_size+sizeof(uint32_t) - 1)/sizeof(uint32_t)] | Storage size of a mutex.| 130| uint32_t [ffrt_cond_t::storage](#storage-16) [(ffrt_cond_storage_size+sizeof(uint32_t) - 1)/sizeof(uint32_t)] | Storage size of a condition variable.| 131 132 133## Enum Description 134 135 136### ffrt_dependence_type_t 137 138``` 139enum ffrt_dependence_type_t 140``` 141 142**Description** 143 144Enumerates the dependency types. 145 146| Value| Description| 147| -------- | -------- | 148| ffrt_dependence_data | Data dependency.| 149| ffrt_dependence_task | Task dependency.| 150 151 152### ffrt_error_t 153 154``` 155enum ffrt_error_t 156``` 157 158**Description** 159 160Enumerates the FFRT error codes. 161 162| Value| Description| 163| -------- | -------- | 164| ffrt_error | Failure.| 165| ffrt_success | Success.| 166| ffrt_error_nomem | Insufficient memory.| 167| ffrt_error_timedout | Timeout.| 168| ffrt_error_busy | Try again.| 169| ffrt_error_inval | Invalid value.| 170 171 172### ffrt_function_kind_t 173 174``` 175enum ffrt_function_kind_t 176``` 177 178**Description** 179 180Enumerates the task types. 181 182| Value| Description| 183| -------- | -------- | 184| ffrt_function_kind_general | General task.| 185| ffrt_function_kind_queue | Queue task.| 186 187 188### ffrt_qos_default_t 189 190``` 191enum ffrt_qos_default_t 192``` 193 194**Description** 195 196Enumerates the task QoS types. 197 198| Value| Description| 199| -------- | -------- | 200| ffrt_qos_inherit | Inherits the QoS of the current task.| 201| ffrt_qos_background | Background task.| 202| ffrt_qos_utility | Real-time tool.| 203| ffrt_qos_default | Default type.| 204| ffrt_qos_user_initiated | User initiated.| 205 206 207### ffrt_queue_type_t 208 209``` 210enum ffrt_queue_type_t 211``` 212 213**Description** 214 215Enumerates the queue types. 216 217| Value| Description| 218| -------- | -------- | 219| ffrt_queue_serial | Serial queue.| 220 221 222### ffrt_storage_size_t 223 224``` 225enum ffrt_storage_size_t 226``` 227 228**Description** 229 230Enumerates the storage sizes available for different types of structs. 231 232| Value| Description| 233| -------- | -------- | 234| ffrt_task_attr_storage_size | Storage size for the task attribute struct.| 235| ffrt_auto_managed_function_storage_size | Storage size for the task execution function struct.| 236| ffrt_mutex_storage_size | Storage size for the mutex struct.| 237| ffrt_cond_storage_size | Storage size for the condition variable struct.| 238| ffrt_queue_attr_storage_size | Storage size for the queue attribute struct.| 239 240 241## Function Description 242 243 244### ffrt_alloc_auto_managed_function_storage_base() 245 246``` 247FFRT_C_API void* ffrt_alloc_auto_managed_function_storage_base (ffrt_function_kind_t kind) 248``` 249 250**Description** 251 252Applies for memory for the task execution function struct. 253 254**Since**: 10 255 256**Parameters** 257 258| Name| Description| 259| -------- | -------- | 260| kind | Type of the task execution function, which can be general or queue.| 261 262**Returns** 263 264Returns a non-null pointer if the memory is allocated; returns a null pointer otherwise. 265 266 267### ffrt_cond_broadcast() 268 269``` 270FFRT_C_API int ffrt_cond_broadcast (ffrt_cond_t * cond) 271``` 272 273**Description** 274 275Unblocks all threads currently blocked on a condition variable. 276 277**Since**: 10 278 279**Parameters** 280 281| Name| Description| 282| -------- | -------- | 283| cond | Pointer to the condition variable.| 284 285**Returns** 286 287Returns **ffrt_thrd_success** if all the threads are unblocked; returns **ffrt_thrd_error** otherwise. 288 289 290### ffrt_cond_destroy() 291 292``` 293FFRT_C_API int ffrt_cond_destroy (ffrt_cond_t * cond) 294``` 295 296**Description** 297 298Destroys a condition variable. 299 300**Since**: 10 301 302**Parameters** 303 304| Name| Description| 305| -------- | -------- | 306| cond | Pointer to the condition variable.| 307 308**Returns** 309 310Returns **ffrt_thrd_success** if the condition variable is destroyed; returns **ffrt_thrd_error** otherwise. 311 312 313### ffrt_cond_init() 314 315``` 316FFRT_C_API int ffrt_cond_init (ffrt_cond_t * cond, const ffrt_condattr_t * attr ) 317``` 318 319**Description** 320 321Initializes a condition variable. 322 323**Since**: 10 324 325**Parameters** 326 327| Name| Description| 328| -------- | -------- | 329| cond | Pointer to the condition variable.| 330| attr | Pointer to the condition variable attribute.| 331 332**Returns** 333 334Returns **ffrt_thrd_success** if the condition variable is initialized; returns **ffrt_thrd_error** otherwise. 335 336 337### ffrt_cond_signal() 338 339``` 340FFRT_C_API int ffrt_cond_signal (ffrt_cond_t * cond) 341``` 342 343**Description** 344 345Unblocks at least one of the threads that are blocked on a condition variable. 346 347**Since**: 10 348 349**Parameters** 350 351| Name| Description| 352| -------- | -------- | 353| cond | Pointer to the condition variable.| 354 355**Returns** 356 357Returns **ffrt_thrd_success** if at least one of the threads is unblocked; returns **ffrt_thrd_error** otherwise. 358 359 360### ffrt_cond_timedwait() 361 362``` 363FFRT_C_API int ffrt_cond_timedwait (ffrt_cond_t * cond, ffrt_mutex_t * mutex, const struct timespec * time_point ) 364``` 365 366**Description** 367 368Blocks the calling thread on a condition variable for a given duration. 369 370**Since**: 10 371 372**Parameters** 373 374| Name| Description| 375| -------- | -------- | 376| cond | Pointer to the condition variable.| 377| mutex | Pointer to the mutex.| 378| time_point | Pointer to the maximum duration that the thread is blocked. If **ffrt_cond_signal** or **ffrt_cond_broadcast** is not called to unblock the thread when the maximum duration reaches, the thread is automatically unblocked.| 379 380**Returns** 381 382Returns **ffrt_thrd_success** if the thread is blocked; returns **ffrt_thrd_timedout** if the maximum duration reaches; returns **ffrt_thrd_error** if the blocking fails. 383 384 385### ffrt_cond_wait() 386 387``` 388FFRT_C_API int ffrt_cond_wait (ffrt_cond_t * cond, ffrt_mutex_t * mutex ) 389``` 390 391**Description** 392 393Blocks the calling thread on a condition variable. 394 395**Since**: 10 396 397**Parameters** 398 399| Name| Description| 400| -------- | -------- | 401| cond | Pointer to the condition variable.| 402| mutex | Pointer to the mutex.| 403 404**Returns** 405 406Returns **ffrt_thrd_success** if the thread is blocked; returns **ffrt_thrd_error** if the blocking fails. 407 408 409### ffrt_mutex_destroy() 410 411``` 412FFRT_C_API int ffrt_mutex_destroy (ffrt_mutex_t * mutex) 413``` 414 415**Description** 416 417Destroys a mutex. 418 419**Since**: 10 420 421**Parameters** 422 423| Name| Description| 424| -------- | -------- | 425| mutex | Pointer to the mutex.| 426 427**Returns** 428 429Returns **ffrt_thrd_success** if the mutex is destroyed; returns **ffrt_thrd_error** otherwise. 430 431 432### ffrt_mutex_init() 433 434``` 435FFRT_C_API int ffrt_mutex_init (ffrt_mutex_t * mutex, const ffrt_mutexattr_t * attr ) 436``` 437 438**Description** 439 440Initializes a mutex. 441 442**Since**: 10 443 444**Parameters** 445 446| Name| Description| 447| -------- | -------- | 448| mutex | Pointer to the mutex.| 449| attr | Pointer to the mutex attribute.| 450 451**Returns** 452 453Returns **ffrt_thrd_success** if the mutex is initialized; returns **ffrt_thrd_error** otherwise. 454 455 456### ffrt_mutex_lock() 457 458``` 459FFRT_C_API int ffrt_mutex_lock (ffrt_mutex_t * mutex) 460``` 461 462**Description** 463 464Locks a mutex. 465 466**Since**: 10 467 468**Parameters** 469 470| Name| Description| 471| -------- | -------- | 472| mutex | Pointer to the mutex.| 473 474**Returns** 475 476Returns **ffrt_thrd_success** if the mutex is locked; returns **ffrt_thrd_error** or blocks the calling thread otherwise. 477 478 479### ffrt_mutex_trylock() 480 481``` 482FFRT_C_API int ffrt_mutex_trylock (ffrt_mutex_t * mutex) 483``` 484 485**Description** 486 487Attempts to lock a mutex. 488 489**Since**: 10 490 491**Parameters** 492 493| Name| Description| 494| -------- | -------- | 495| mutex | Pointer to the mutex.| 496 497**Returns** 498 499Returns **ffrt_thrd_success** if the mutex is locked; returns **ffrt_thrd_error** or **ffrt_thrd_busy** otherwise. 500 501 502### ffrt_mutex_unlock() 503 504``` 505FFRT_C_API int ffrt_mutex_unlock (ffrt_mutex_t * mutex) 506``` 507 508**Description** 509 510Unlocks a mutex. 511 512**Since**: 10 513 514**Parameters** 515 516| Name| Description| 517| -------- | -------- | 518| mutex | Pointer to the mutex.| 519 520**Returns** 521 522Returns **ffrt_thrd_success** if the mutex is unlocked; returns **ffrt_thrd_error** otherwise. 523 524 525### ffrt_queue_attr_destroy() 526 527``` 528FFRT_C_API void ffrt_queue_attr_destroy (ffrt_queue_attr_t * attr) 529``` 530 531**Description** 532 533Destroys a queue attribute. 534 535**Since**: 10 536 537**Parameters** 538 539| Name| Description| 540| -------- | -------- | 541| attr | Pointer to the queue attribute.| 542 543 544### ffrt_queue_attr_get_callback() 545 546``` 547FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback (const ffrt_queue_attr_t * attr) 548``` 549 550**Description** 551 552Obtains the callback that is invoked when a queue task times out. 553 554**Since**: 10 555 556**Parameters** 557 558| Name| Description| 559| -------- | -------- | 560| attr | Pointer to the queue attribute.| 561 562**Returns** 563 564Returns the callback. 565 566 567### ffrt_queue_attr_get_qos() 568 569``` 570FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos (const ffrt_queue_attr_t * attr) 571``` 572 573**Description** 574 575Obtains the queue QoS. 576 577**Since**: 10 578 579**Parameters** 580 581| Name| Description| 582| -------- | -------- | 583| attr | Pointer to the queue attribute.| 584 585**Returns** 586 587Returns the QoS. 588 589 590### ffrt_queue_attr_get_timeout() 591 592``` 593FFRT_C_API uint64_t ffrt_queue_attr_get_timeout (const ffrt_queue_attr_t * attr) 594``` 595 596**Description** 597 598Obtains the queue timeout. 599 600**Since**: 10 601 602**Parameters** 603 604| Name| Description| 605| -------- | -------- | 606| attr | Pointer to the queue attribute.| 607 608**Returns** 609 610Returns the timeout. 611 612 613### ffrt_queue_attr_init() 614 615``` 616FFRT_C_API int ffrt_queue_attr_init (ffrt_queue_attr_t * attr) 617``` 618 619**Description** 620 621Initializes a queue attribute. 622 623**Since**: 10 624 625**Parameters** 626 627| Name| Description| 628| -------- | -------- | 629| attr | Pointer to the queue attribute.| 630 631**Returns** 632 633Returns **0** if the queue attribute is initialized; returns **-1** otherwise. 634 635 636### ffrt_queue_attr_set_callback() 637 638``` 639FFRT_C_API void ffrt_queue_attr_set_callback (ffrt_queue_attr_t * attr, ffrt_function_header_t * f ) 640``` 641 642**Description** 643 644Sets a callback that is invoked when a queue task times out. 645 646**Since**: 10 647 648**Parameters** 649 650| Name| Description| 651| -------- | -------- | 652| attr | Pointer to the queue attribute.| 653| f | Pointer to the callback function.| 654 655 656### ffrt_queue_attr_set_qos() 657 658``` 659FFRT_C_API void ffrt_queue_attr_set_qos (ffrt_queue_attr_t * attr, ffrt_qos_t qos ) 660``` 661 662**Description** 663 664Sets the queue QoS. 665 666**Since**: 10 667 668**Parameters** 669 670| Name| Description| 671| -------- | -------- | 672| attr | Pointer to the queue attribute.| 673| qos | QoS.| 674 675 676### ffrt_queue_attr_set_timeout() 677 678``` 679FFRT_C_API void ffrt_queue_attr_set_timeout (ffrt_queue_attr_t * attr, uint64_t timeout_us ) 680``` 681 682**Description** 683 684Sets the queue timeout. 685 686**Since**: 10 687 688**Parameters** 689 690| Name| Description| 691| -------- | -------- | 692| attr | Pointer to the queue attribute.| 693| timeout_us | Timeout.| 694 695 696### ffrt_queue_cancel() 697 698``` 699FFRT_C_API int ffrt_queue_cancel (ffrt_task_handle_t handle) 700``` 701 702**Description** 703 704Cancels a task in the queue. 705 706**Since**: 10 707 708**Parameters** 709 710| Name| Description| 711| -------- | -------- | 712| handle | Task handle.| 713 714**Returns** 715 716Returns **0** if the task is canceled; returns **-1** otherwise. 717 718 719### ffrt_queue_create() 720 721``` 722FFRT_C_API ffrt_queue_t ffrt_queue_create (ffrt_queue_type_t type, const char * name, const ffrt_queue_attr_t * attr ) 723``` 724 725**Description** 726 727Creates a queue. 728 729**Since**: 10 730 731**Parameters** 732 733| Name| Description| 734| -------- | -------- | 735| type | Queue type.| 736| name | Pointer to the queue name.| 737| attr | Pointer to the queue attribute.| 738 739**Returns** 740 741Returns a non-null queue handle if the queue is created; returns a null pointer otherwise. 742 743 744### ffrt_queue_destroy() 745 746``` 747FFRT_C_API void ffrt_queue_destroy (ffrt_queue_t queue) 748``` 749 750**Description** 751 752Destroys a queue. 753 754**Since**: 10 755 756**Parameters** 757 758| Name| Description| 759| -------- | -------- | 760| queue | Queue handle.| 761 762 763### ffrt_queue_submit() 764 765``` 766FFRT_C_API void ffrt_queue_submit (ffrt_queue_t queue, ffrt_function_header_t * f, const ffrt_task_attr_t * attr ) 767``` 768 769**Description** 770 771Submits a task to a queue. 772 773**Since**: 10 774 775**Parameters** 776 777| Name| Description| 778| -------- | -------- | 779| queue | Queue handle.| 780| f | Pointer to the task execution function.| 781| attr | Pointer to the task attribute.| 782 783 784### ffrt_queue_submit_h() 785 786``` 787FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h (ffrt_queue_t queue, ffrt_function_header_t * f, const ffrt_task_attr_t * attr ) 788``` 789 790**Description** 791 792Submits a task to a queue, and obtains a task handle. 793 794**Since**: 10 795 796**Parameters** 797 798| Name| Description| 799| -------- | -------- | 800| queue | Queue handle.| 801| f | Pointer to the task execution function.| 802| attr | Pointer to the task attribute.| 803 804**Returns** 805 806Returns a non-null task handle if the task is submitted; returns a null pointer otherwise. 807 808 809### ffrt_queue_wait() 810 811``` 812FFRT_C_API void ffrt_queue_wait (ffrt_task_handle_t handle) 813``` 814 815**Description** 816 817Waits until a task in the queue is complete. 818 819**Since**: 10 820 821**Parameters** 822 823| Name| Description| 824| -------- | -------- | 825| handle | Task handle.| 826 827 828### ffrt_submit_base() 829 830``` 831FFRT_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 ) 832``` 833 834**Description** 835 836Submits a task. 837 838**Since**: 10 839 840**Parameters** 841 842| Name| Description| 843| -------- | -------- | 844| f | Pointer to the task execution function.| 845| in_deps | Pointer to the input dependencies.| 846| out_deps | Pointer to the output dependencies.| 847| attr | Pointer to the task attribute.| 848 849 850### ffrt_submit_h_base() 851 852``` 853FFRT_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 ) 854``` 855 856**Description** 857 858Submits a task, and obtains a task handle. 859 860**Since**: 10 861 862**Parameters** 863 864| Name| Description| 865| -------- | -------- | 866| f | Pointer to the task execution function.| 867| in_deps | Pointer to the input dependencies.| 868| out_deps | Pointer to the output dependencies.| 869| attr | Pointer to the task attribute.| 870 871**Returns** 872 873Returns a non-null task handle if the task is submitted; returns a null pointer otherwise. 874 875 876### ffrt_task_attr_destroy() 877 878``` 879FFRT_C_API void ffrt_task_attr_destroy (ffrt_task_attr_t * attr) 880``` 881 882**Description** 883 884Destroys a task attribute. 885 886**Since**: 10 887 888**Parameters** 889 890| Name| Description| 891| -------- | -------- | 892| attr | Pointer to the task attribute.| 893 894 895### ffrt_task_attr_get_delay() 896 897``` 898FFRT_C_API uint64_t ffrt_task_attr_get_delay (const ffrt_task_attr_t * attr) 899``` 900 901**Description** 902 903Obtains the task delay time. 904 905**Since**: 10 906 907**Parameters** 908 909| Name| Description| 910| -------- | -------- | 911| attr | Pointer to the task attribute.| 912 913**Returns** 914 915Returns the delay time. 916 917 918### ffrt_task_attr_get_name() 919 920``` 921FFRT_C_API const char* ffrt_task_attr_get_name (const ffrt_task_attr_t * attr) 922``` 923 924**Description** 925 926Obtains a task name. 927 928**Since**: 10 929 930**Parameters** 931 932| Name| Description| 933| -------- | -------- | 934| attr | Pointer to the task attribute.| 935 936**Returns** 937 938Returns a non-null pointer to the task name if the name is obtained; returns a null pointer otherwise. 939 940 941### ffrt_task_attr_get_qos() 942 943``` 944FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos (const ffrt_task_attr_t * attr) 945``` 946 947**Description** 948 949Obtains the task QoS. 950 951**Since**: 10 952 953**Parameters** 954 955| Name| Description| 956| -------- | -------- | 957| attr | Pointer to the task attribute.| 958 959**Returns** 960 961Returns the QoS, which is **ffrt_qos_default** by default. 962 963 964### ffrt_task_attr_init() 965 966``` 967FFRT_C_API int ffrt_task_attr_init (ffrt_task_attr_t * attr) 968``` 969 970**Description** 971 972Initializes a task attribute. 973 974**Since**: 10 975 976**Parameters** 977 978| Name| Description| 979| -------- | -------- | 980| attr | Pointer to the task attribute.| 981 982**Returns** 983 984Returns **0** if the task attribute is initialized; returns **-1** otherwise. 985 986 987### ffrt_task_attr_set_delay() 988 989``` 990FFRT_C_API void ffrt_task_attr_set_delay (ffrt_task_attr_t * attr, uint64_t delay_us ) 991``` 992 993**Description** 994 995Sets the task delay time. 996 997**Since**: 10 998 999**Parameters** 1000 1001| Name| Description| 1002| -------- | -------- | 1003| attr | Pointer to the task attribute.| 1004| delay_us | Delay time, in microseconds.| 1005 1006 1007### ffrt_task_attr_set_name() 1008 1009``` 1010FFRT_C_API void ffrt_task_attr_set_name (ffrt_task_attr_t * attr, const char * name ) 1011``` 1012 1013**Description** 1014 1015Sets a task name. 1016 1017**Since**: 10 1018 1019**Parameters** 1020 1021| Name| Description| 1022| -------- | -------- | 1023| attr | Pointer to the task attribute.| 1024| name | Pointer to the task name.| 1025 1026 1027### ffrt_task_attr_set_qos() 1028 1029``` 1030FFRT_C_API void ffrt_task_attr_set_qos (ffrt_task_attr_t * attr, ffrt_qos_t qos ) 1031``` 1032 1033**Description** 1034 1035Sets the task QoS. 1036 1037**Since**: 10 1038 1039**Parameters** 1040 1041| Name| Description| 1042| -------- | -------- | 1043| attr | Pointer to the task attribute.| 1044| qos | QoS.| 1045 1046 1047### ffrt_task_handle_destroy() 1048 1049``` 1050FFRT_C_API void ffrt_task_handle_destroy (ffrt_task_handle_t handle) 1051``` 1052 1053**Description** 1054 1055Destroys a task handle. 1056 1057**Since**: 10 1058 1059**Parameters** 1060 1061| Name| Description| 1062| -------- | -------- | 1063| handle | Task handle.| 1064 1065 1066### ffrt_this_task_get_id() 1067 1068``` 1069FFRT_C_API uint64_t ffrt_this_task_get_id (void ) 1070``` 1071 1072**Description** 1073 1074Obtains the task ID. 1075 1076**Since**: 10 1077 1078**Returns** 1079 1080Returns the ID. 1081 1082 1083### ffrt_this_task_update_qos() 1084 1085``` 1086FFRT_C_API int ffrt_this_task_update_qos (ffrt_qos_t qos) 1087``` 1088 1089**Description** 1090 1091Updates the task QoS. 1092 1093**Since**: 10 1094 1095**Parameters** 1096 1097| Name| Description| 1098| -------- | -------- | 1099| qos | New QoS.| 1100 1101**Returns** 1102 1103Returns **0** if the QoS is updated; returns **-1** otherwise. 1104 1105 1106### ffrt_usleep() 1107 1108``` 1109FFRT_C_API int ffrt_usleep (uint64_t usec) 1110``` 1111 1112**Description** 1113 1114Suspends the calling thread for a given duration. 1115 1116**Since**: 10 1117 1118**Parameters** 1119 1120| Name| Description| 1121| -------- | -------- | 1122| usec | Duration that the calling thread is suspended, in microseconds. | 1123 1124**Returns** 1125 1126Returns **ffrt_thrd_success** if the thread is suspended; returns **ffrt_thrd_error** otherwise. 1127 1128 1129### ffrt_wait() 1130 1131``` 1132FFRT_C_API void ffrt_wait (void ) 1133``` 1134 1135**Description** 1136 1137Waits until all submitted tasks are complete. 1138 1139**Since**: 10 1140 1141 1142### ffrt_wait_deps() 1143 1144``` 1145FFRT_C_API void ffrt_wait_deps (const ffrt_deps_t * deps) 1146``` 1147 1148**Description** 1149 1150Waits until the dependent tasks are complete. 1151 1152**Since**: 10 1153 1154**Parameters** 1155 1156| Name| Description| 1157| -------- | -------- | 1158| deps | Pointer to the dependencies.| 1159 1160 1161### ffrt_yield() 1162 1163``` 1164FFRT_C_API void ffrt_yield (void ) 1165``` 1166 1167**Description** 1168 1169Passes control to other tasks so that they can be executed. 1170 1171**Since**: 10 1172 1173 1174## Variable Description 1175 1176 1177### destroy 1178 1179``` 1180ffrt_function_t ffrt_function_header_t::destroy 1181``` 1182 1183**Description** 1184 1185Function used to destroy a task. 1186 1187 1188### exec 1189 1190``` 1191ffrt_function_t ffrt_function_header_t::exec 1192``` 1193 1194**Description** 1195 1196Function used to execute a task. 1197 1198 1199### items 1200 1201``` 1202const ffrt_dependence_t* ffrt_deps_t::items 1203``` 1204 1205**Description** 1206 1207Dependency data. 1208 1209 1210### len 1211 1212``` 1213uint32_t ffrt_deps_t::len 1214``` 1215 1216**Description** 1217 1218Number of dependencies. 1219 1220 1221### ptr 1222 1223``` 1224const void* ffrt_dependence_t::ptr 1225``` 1226 1227**Description** 1228 1229Address of the dependency data. 1230 1231 1232### reserve 1233 1234``` 1235uint64_t ffrt_function_header_t::reserve[2] 1236``` 1237 1238**Description** 1239 1240Reserved bit. 1241 1242 1243### storage [1/6] 1244 1245``` 1246uint32_t ffrt_cond_t::storage[(ffrt_cond_storage_size+sizeof(uint32_t) - 1)/sizeof(uint32_t)] 1247``` 1248 1249**Description** 1250 1251Storage size of a condition variable. 1252 1253 1254### storage [2/6] 1255 1256``` 1257uint32_t ffrt_mutex_t::storage[(ffrt_mutex_storage_size+sizeof(uint32_t) - 1)/sizeof(uint32_t)] 1258``` 1259 1260**Description** 1261 1262Storage size of a mutex. 1263 1264 1265### storage [3/6] 1266 1267``` 1268uint32_t ffrt_queue_attr_t::storage[(ffrt_queue_attr_storage_size+sizeof(uint32_t) - 1)/sizeof(uint32_t)] 1269``` 1270 1271**Description** 1272 1273Storage size of a queue attribute. 1274 1275 1276### storage [4/6] 1277 1278``` 1279uint32_t ffrt_task_attr_t::storage[(ffrt_task_attr_storage_size+sizeof(uint32_t) - 1)/sizeof(uint32_t)] 1280``` 1281 1282**Description** 1283 1284Storage size of a task attribute. 1285 1286 1287### storage [5/6] 1288 1289``` 1290long ffrt_condattr_t::storage 1291``` 1292 1293**Description** 1294 1295Storage size of a condition variable attribute. 1296 1297 1298### storage [6/6] 1299 1300``` 1301long ffrt_mutexattr_t::storage 1302``` 1303 1304**Description** 1305 1306Storage size of a mutex attribute. 1307 1308 1309### type 1310 1311``` 1312ffrt_dependence_type_t ffrt_dependence_t::type 1313``` 1314 1315**Description** 1316 1317Dependency type. 1318