1# queue.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 **queue.h** file declares the queue APIs in C. 13 14**File to include**: <ffrt/queue.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### Structs 27 28| Name | Description| 29|------------------|--| 30| [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) | Queue handle. | 31 32### Enums 33 34| Name| typedef Keyword| Description| 35| -- | -- | -- | 36| [ffrt_queue_type_t](#ffrt_queue_type_t) | ffrt_queue_type_t | Enumerates the queue types.| 37 38### Function 39 40| Name| Description| 41| -- | -- | 42| [FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr)](#ffrt_queue_attr_init) | Initializes the queue attribute.| 43| [FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr)](#ffrt_queue_attr_destroy) | Destroys the queue attribute.| 44| [FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos)](#ffrt_queue_attr_set_qos) | Sets the queue QoS.| 45| [FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_qos) | Obtains the queue QoS.| 46| [FFRT_C_API void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t timeout_us)](#ffrt_queue_attr_set_timeout) | Sets the queue timeout. The minimum timeout value is 1 ms. Any value set below this threshold will default to 1 ms.| 47| [FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_timeout) | Obtains the queue timeout.| 48| [FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_function_header_t* f)](#ffrt_queue_attr_set_callback) | Sets a callback that is invoked when a queue task times out.| 49| [FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_callback) | Obtains the callback that is invoked when a queue task times out.| 50| [FFRT_C_API void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, const int max_concurrency)](#ffrt_queue_attr_set_max_concurrency) | Sets the maximum concurrency for a queue, which must be a concurrent queue.| 51| [FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_max_concurrency) | Obtains the maximum concurrency of a queue, which must be a concurrent queue.| 52| [FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr)](#ffrt_queue_create) | Creates a queue.| 53| [FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue)](#ffrt_queue_destroy) | Destroys a queue.| 54| [FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr)](#ffrt_queue_submit) | Submits a task to a queue.| 55| [FFRT_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)](#ffrt_queue_submit_h) | Submits a task to a queue, and obtains the task handle.| 56| [FFRT_C_API void ffrt_queue_submit_f(ffrt_queue_t queue, ffrt_function_t func, void* arg, const ffrt_task_attr_t* attr)](#ffrt_queue_submit_f) | Submits a task to a queue. It is a simplified wrapper of **ffrt_queue_submit**. This API assumes that the callback function does not need to be destroyed. The task function and parameters are encapsulated into a queue task structure, which is then passed to **ffrt_queue_submit** along with other parameters.| 57| [FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h_f(ffrt_queue_t queue, ffrt_function_t func, void* arg, const ffrt_task_attr_t* attr)](#ffrt_queue_submit_h_f) | Submits a task to a queue, and obtains the task handle. It is a simplified wrapper of **ffrt_queue_submit_h**. This API assumes that the callback function does not need to be destroyed. The task function and parameters are encapsulated into a queue task structure, which is then passed to **ffrt_queue_submit_h** along with other parameters.| 58| [FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle)](#ffrt_queue_wait) | Waits until a task in the queue is complete.| 59| [FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle)](#ffrt_queue_cancel) | Cancels a task in the queue.| 60| [FFRT_C_API ffrt_queue_t ffrt_get_main_queue(void)](#ffrt_get_main_queue) | Obtains the main thread queue.| 61| [FFRT_C_API ffrt_queue_t ffrt_get_current_queue(void)](#ffrt_get_current_queue) | Obtains the ArkTS Worker thread queue.| 62 63## Enum Description 64 65### ffrt_queue_type_t 66 67``` 68enum ffrt_queue_type_t 69``` 70 71**Description** 72 73Enumerates the queue types. 74 75**Since**: 12 76 77| Enum Item| Description| 78| -- | -- | 79| ffrt_queue_serial | Serial queue.| 80| ffrt_queue_concurrent | Concurrent queue.| 81| ffrt_queue_max | Invalid queue type.| 82 83 84## Function Description 85 86### ffrt_queue_attr_init() 87 88``` 89FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr) 90``` 91 92**Description** 93 94Initializes the queue attribute. 95 96**Since**: 10 97 98 99**Parameters** 100 101| Name| Description| 102| -- | -- | 103| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | Pointer to the queue attribute.| 104 105**Returns** 106 107| Type| Description| 108| -- | -- | 109| FFRT_C_API int | Returns **0** if the queue attribute is initialized;<br> returns **-1** otherwise.| 110 111### ffrt_queue_attr_destroy() 112 113``` 114FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr) 115``` 116 117**Description** 118 119Destroys the queue attribute. 120 121**Since**: 10 122 123 124**Parameters** 125 126| Name| Description| 127| -- | -- | 128| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | Pointer to the queue attribute.| 129 130### ffrt_queue_attr_set_qos() 131 132``` 133FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos) 134``` 135 136**Description** 137 138Sets the queue QoS. 139 140**Since**: 10 141 142 143**Parameters** 144 145| Name | Description| 146|-----------------------------------------------------------| -- | 147| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | Pointer to the queue attribute.| 148| [ffrt_qos_t](capi-type-def-h.md#variables) qos | QoS.| 149 150### ffrt_queue_attr_get_qos() 151 152``` 153FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr) 154``` 155 156**Description** 157 158Obtains the queue QoS. 159 160**Since**: 10 161 162 163**Parameters** 164 165| Name| Description| 166| -- | -- | 167| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | Pointer to the queue attribute.| 168 169**Returns** 170 171| Type| Description| 172| -- | -- | 173| FFRT_C_API [ffrt_qos_t](capi-type-def-h.md#variables)| Returns the queue QoS.| 174 175### ffrt_queue_attr_set_timeout() 176 177``` 178FFRT_C_API void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t timeout_us) 179``` 180 181**Description** 182 183Sets the serial queue timeout. The minimum timeout value is 1 ms. Any value set below this threshold will default to 1 ms. 184 185**Since**: 10 186 187 188**Parameters** 189 190| Name| Description| 191| -- | -- | 192| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | Pointer to the serial queue attribute.| 193| uint64_t timeout_us | Serial queue timeout, in microseconds.| 194 195### ffrt_queue_attr_get_timeout() 196 197``` 198FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr) 199``` 200 201**Description** 202 203Obtains the serial queue timeout. 204 205**Since**: 10 206 207 208**Parameters** 209 210| Name| Description| 211| -- | -- | 212| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | Pointer to the serial queue attribute.| 213 214**Returns** 215 216| Type| Description| 217| -- | -- | 218| FFRT_C_API uint64_t | Returns the serial queue timeout.| 219 220### ffrt_queue_attr_set_callback() 221 222``` 223FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_function_header_t* f) 224``` 225 226**Description** 227 228Sets a callback that is invoked when a queue task times out. 229 230**Since**: 10 231 232 233**Parameters** 234 235| Name| Description| 236| -- | -- | 237| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | Pointer to the serial queue attribute.| 238| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | Pointer to the callback function invoked upon a timeout.| 239 240### ffrt_queue_attr_get_callback() 241 242``` 243FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr) 244``` 245 246**Description** 247 248Obtains the callback that is invoked when a queue task times out. 249 250**Since**: 10 251 252 253**Parameters** 254 255| Name| Description| 256| -- | -- | 257| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | Pointer to the serial queue attribute.| 258 259**Returns** 260 261| Type | Description| 262|----------------------------------------| -- | 263| FFRT_C_API [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* | Returns the callback.| 264 265### ffrt_queue_attr_set_max_concurrency() 266 267``` 268FFRT_C_API void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, const int max_concurrency) 269``` 270 271**Description** 272 273Sets the maximum concurrency for a concurrent queue. 274 275**Since**: 12 276 277 278**Parameters** 279 280| Name| Description| 281| -- | -- | 282| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | Pointer to the queue attribute.| 283| const int max_concurrency | Maximum concurrency.| 284 285### ffrt_queue_attr_get_max_concurrency() 286 287``` 288FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr) 289``` 290 291**Description** 292 293Obtains the maximum concurrency of a concurrent queue. 294 295**Since**: 12 296 297 298**Parameters** 299 300| Name| Description| 301| -- | -- | 302| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | Pointer to the queue attribute.| 303 304**Returns** 305 306| Type| Description| 307| -- | -- | 308| FFRT_C_API int | Returns the maximum concurrency.| 309 310### ffrt_queue_create() 311 312``` 313FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr) 314``` 315 316**Description** 317 318Creates a queue. 319 320**Since**: 10 321 322 323**Parameters** 324 325| Name| Description| 326| -- | -- | 327| [ffrt_queue_type_t](capi-queue-h.md#ffrt_queue_type_t) type | Queue type.| 328| const char* name | Pointer to the queue name.| 329| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | Pointer to the queue attribute.| 330 331**Returns** 332 333| Type | Description| 334|-----------------------------| -- | 335| FFRT_C_API [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) | Returns a non-null queue handle if the queue is created;<br> returns a null pointer otherwise.| 336 337### ffrt_queue_destroy() 338 339``` 340FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue) 341``` 342 343**Description** 344 345Destroys a queue. 346 347**Since**: 10 348 349 350**Parameters** 351 352| Name| Description| 353| -- | -- | 354| [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | Queue handle.| 355 356### ffrt_queue_submit() 357 358``` 359FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr) 360``` 361 362**Description** 363 364Submits a task to a queue. 365 366**Since**: 10 367 368 369**Parameters** 370 371| Name| Description| 372| -- | -- | 373| [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | Queue handle.| 374| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | Pointer to the task execution function.| 375| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 376 377### ffrt_queue_submit_h() 378 379``` 380FFRT_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) 381``` 382 383**Description** 384 385Submits a task to a queue, and obtains the task handle. 386 387**Since**: 10 388 389 390**Parameters** 391 392| Name| Description| 393| -- | -- | 394| [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | Queue handle.| 395| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | Pointer to the task execution function.| 396| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 397 398**Returns** 399 400| Type | Description| 401|-----------------------------------| -- | 402| 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.| 403 404### ffrt_queue_submit_f() 405 406``` 407FFRT_C_API void ffrt_queue_submit_f(ffrt_queue_t queue, ffrt_function_t func, void* arg, const ffrt_task_attr_t* attr) 408``` 409 410**Description** 411 412Submits a task to a queue. It is a simplified wrapper of **ffrt_queue_submit**. This API assumes that the callback function does not need to be destroyed. The task function and parameters are encapsulated into a queue task structure, which is then passed to **ffrt_queue_submit** along with other parameters. 413 414**Since**: 20 415 416 417**Parameters** 418 419| Name| Description| 420| -- | -- | 421| [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | Queue handle.| 422| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | Task function.| 423| void* arg | Pointer to the argument.| 424| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 425 426**References** 427 428[ffrt_queue_submit](capi-queue-h.md#ffrt_queue_submit) 429 430 431### ffrt_queue_submit_h_f() 432 433``` 434FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h_f(ffrt_queue_t queue, ffrt_function_t func, void* arg, const ffrt_task_attr_t* attr) 435``` 436 437**Description** 438 439Submits a task to a queue, and obtains the task handle. It is a simplified wrapper of **ffrt_queue_submit_h**. This API assumes that the callback function does not need to be destroyed. The task function and parameters are encapsulated into a queue task structure, which is then passed to **ffrt_queue_submit_h** along with other parameters. 440 441**Since**: 20 442 443 444**Parameters** 445 446| Name| Description| 447| -- | -- | 448| [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | Queue handle.| 449| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | Task function.| 450| void* arg | Pointer to the argument.| 451| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | Pointer to the task attribute.| 452 453**Returns** 454 455| Type| Description| 456| -- | -- | 457| 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.| 458 459**References** 460 461[ffrt_queue_submit_h](capi-queue-h.md#ffrt_queue_submit_h) 462 463 464### ffrt_queue_wait() 465 466``` 467FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle) 468``` 469 470**Description** 471 472Waits until a task in the queue is complete. 473 474**Since**: 10 475 476 477**Parameters** 478 479| Name| Description| 480| -- | -- | 481| [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) handle | Task handle.| 482 483### ffrt_queue_cancel() 484 485``` 486FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle) 487``` 488 489**Description** 490 491Cancels a task in the queue. 492 493**Since**: 10 494 495 496**Parameters** 497 498| Name| Description| 499| -- | -- | 500| [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) handle | Task handle.| 501 502**Returns** 503 504| Type| Description| 505| -- | -- | 506| FFRT_C_API int | Returns **0** if the task is canceled;<br> returns **-1** otherwise.| 507 508### ffrt_get_main_queue() 509 510``` 511FFRT_C_API ffrt_queue_t ffrt_get_main_queue(void) 512``` 513 514**Description** 515 516Obtains the main thread queue. 517 518**Since**: 12 519 520**Returns** 521 522| Type| Description| 523| -- | -- | 524| FFRT_C_API [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) | Returns the handle to the main thread queue.| 525 526### ffrt_get_current_queue() 527 528``` 529FFRT_C_API ffrt_queue_t ffrt_get_current_queue(void) 530``` 531 532**Description** 533 534Obtains the ArkTS Worker thread queue. 535 536**Since**: 12 537 538**Deprecated from**: 18 539 540**Returns** 541 542| Type| Description| 543| -- | -- | 544| FFRT_C_API ffrt_queue_t | Returns the handle to the thread queue.| 545