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## 概述 11 12声明队列的C接口。 13 14**引用文件：** <ffrt/queue.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_queue_t](capi-ffrt-ffrt-queue-t.md) | 队列句柄。 | 31 32### 枚举 33 34| 名称 | typedef关键字 | 描述 | 35| -- | -- | -- | 36| [ffrt_queue_type_t](#ffrt_queue_type_t) | ffrt_queue_type_t | 队列类型。 | 37 38### 函数 39 40| 名称 | 描述 | 41| -- | -- | 42| [FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr)](#ffrt_queue_attr_init) | 初始化队列属性。 | 43| [FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr)](#ffrt_queue_attr_destroy) | 销毁队列属性。 | 44| [FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos)](#ffrt_queue_attr_set_qos) | 设置队列QoS属性。 | 45| [FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_qos) | 获取队列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) | 设置串行队列timeout属性。超时时间的最小值是1ms，如果设置的值小于1ms，那么超时时间被设置为1ms。 | 47| [FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_timeout) | 获取串行队列任务执行的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) | 设置串行队列超时回调方法。 | 49| [FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_callback) | 获取串行队列超时回调方法。 | 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) | 设置并行队列最大并发度。 | 51| [FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_max_concurrency) | 获取并行队列最大并发度。 | 52| [FFRT_C_API void ffrt_queue_attr_set_thread_mode(ffrt_queue_attr_t* attr, bool mode)](#ffrt_queue_attr_set_thread_mode) | 设置队列中的任务是以协程模式还是以线程模式运行。默认以协程模式运行。 | 53| [FFRT_C_API bool ffrt_queue_attr_get_thread_mode(const ffrt_queue_attr_t* attr)](#ffrt_queue_attr_get_thread_mode) | 获取队列中的任务是以协程模式还是以线程模式运行。 | 54| [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) | 创建队列。 | 55| [FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue)](#ffrt_queue_destroy) | 销毁队列。 | 56| [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) | 提交一个任务到队列中调度执行。 | 57| [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) | 提交一个任务到队列中调度执行，并返回任务句柄。 | 58| [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) | 提交一个任务到队列中调度执行，是ffrt_queue_submit接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为队列任务结构，并将封装后的任务结构和其他参数传递给ffrt_queue_submit接口。 | 59| [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) | 提交一个任务到队列中调度执行，并返回任务句柄，是ffrt_queue_submit_h接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为队列任务结构，并将封装后的任务结构和其他参数传递给ffrt_queue_submit_h接口。 | 60| [FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle)](#ffrt_queue_wait) | 等待队列中一个任务执行完成。 | 61| [FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle)](#ffrt_queue_cancel) | 取消队列中一个任务。 | 62| [FFRT_C_API ffrt_queue_t ffrt_get_main_queue(void)](#ffrt_get_main_queue) | 获取主线程队列。 | 63| [FFRT_C_API ffrt_queue_t ffrt_get_current_queue(void)](#ffrt_get_current_queue) | 获取应用Worker(ArkTs)线程队列。 | 64 65## 枚举类型说明 66 67### ffrt_queue_type_t 68 69``` 70enum ffrt_queue_type_t 71``` 72 73**描述** 74 75队列类型。 76 77**起始版本：** 12 78 79| 枚举项 | 描述 | 80| -- | -- | 81| ffrt_queue_serial | 串行队列 | 82| ffrt_queue_concurrent | 并行队列 | 83| ffrt_queue_max | 无效队列类型 | 84 85 86## 函数说明 87 88### ffrt_queue_attr_init() 89 90``` 91FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr) 92``` 93 94**描述** 95 96初始化队列属性。 97 98**起始版本：** 10 99 100 101**参数：** 102 103| 参数项 | 描述 | 104| -- | -- | 105| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | 106 107**返回：** 108 109| 类型 | 说明 | 110| -- | -- | 111| FFRT_C_API int | 执行成功时返回0，<br> 执行失败时返回-1。 | 112 113### ffrt_queue_attr_destroy() 114 115``` 116FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr) 117``` 118 119**描述** 120 121销毁队列属性。 122 123**起始版本：** 10 124 125 126**参数：** 127 128| 参数项 | 描述 | 129| -- | -- | 130| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | 131 132### ffrt_queue_attr_set_qos() 133 134``` 135FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos) 136``` 137 138**描述** 139 140设置队列QoS属性。 141 142**起始版本：** 10 143 144 145**参数：** 146 147| 参数项 | 描述 | 148|-----------------------------------------------------------| -- | 149| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | 150| [ffrt_qos_t](capi-type-def-h.md#变量) qos | QoS属性值。 | 151 152### ffrt_queue_attr_get_qos() 153 154``` 155FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr) 156``` 157 158**描述** 159 160获取队列QoS属性。 161 162**起始版本：** 10 163 164 165**参数：** 166 167| 参数项 | 描述 | 168| -- | -- | 169| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | 170 171**返回：** 172 173| 类型 | 说明 | 174| -- | -- | 175| FFRT_C_API [ffrt_qos_t](capi-type-def-h.md#变量) | 返回队列的QoS属性。 | 176 177### ffrt_queue_attr_set_timeout() 178 179``` 180FFRT_C_API void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t timeout_us) 181``` 182 183**描述** 184 185设置串行队列timeout属性。超时时间的最小值是1ms，如果设置的值小于1ms，那么超时时间被设置为1ms。 186 187**起始版本：** 10 188 189 190**参数：** 191 192| 参数项 | 描述 | 193| -- | -- | 194| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 串行队列属性指针。 | 195| uint64_t timeout_us | 串行队列任务执行的timeout时间(微秒)。 | 196 197### ffrt_queue_attr_get_timeout() 198 199``` 200FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr) 201``` 202 203**描述** 204 205获取串行队列任务执行的timeout时间。 206 207**起始版本：** 10 208 209 210**参数：** 211 212| 参数项 | 描述 | 213| -- | -- | 214| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 串行队列属性指针。 | 215 216**返回：** 217 218| 类型 | 说明 | 219| -- | -- | 220| FFRT_C_API uint64_t | 返回串行队列任务执行的timeout时间。 | 221 222### ffrt_queue_attr_set_callback() 223 224``` 225FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_function_header_t* f) 226``` 227 228**描述** 229 230设置串行队列超时回调方法。 231 232**起始版本：** 10 233 234 235**参数：** 236 237| 参数项 | 描述 | 238| -- | -- | 239| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 串行队列属性指针。 | 240| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 超时回调方法执行体。 | 241 242### ffrt_queue_attr_get_callback() 243 244``` 245FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr) 246``` 247 248**描述** 249 250获取串行队列超时回调方法。 251 252**起始版本：** 10 253 254 255**参数：** 256 257| 参数项 | 描述 | 258| -- | -- | 259| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 串行队列属性指针。 | 260 261**返回：** 262 263| 类型 | 说明 | 264|----------------------------------------| -- | 265| FFRT_C_API [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* | 返回串行队列超时回调方法。 | 266 267### ffrt_queue_attr_set_max_concurrency() 268 269``` 270FFRT_C_API void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, const int max_concurrency) 271``` 272 273**描述** 274 275设置并行队列最大并发度。 276 277**起始版本：** 12 278 279 280**参数：** 281 282| 参数项 | 描述 | 283| -- | -- | 284| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | 285| const int max_concurrency | 最大并发度。 | 286 287### ffrt_queue_attr_get_max_concurrency() 288 289``` 290FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr) 291``` 292 293**描述** 294 295获取并行队列最大并发度。 296 297**起始版本：** 12 298 299 300**参数：** 301 302| 参数项 | 描述 | 303| -- | -- | 304| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | 305 306**返回：** 307 308| 类型 | 说明 | 309| -- | -- | 310| FFRT_C_API int | 返回最大并发度。 | 311 312### ffrt_queue_attr_set_thread_mode() 313 314``` 315FFRT_C_API void ffrt_queue_attr_set_thread_mode(ffrt_queue_attr_t* attr, bool mode) 316``` 317 318**描述** 319 320设置队列中的任务是以协程模式还是以线程模式运行。默认以协程模式运行。 321 322**起始版本：** 20 323 324 325**参数：** 326 327| 参数项 | 描述 | 328| -- | -- | 329| [ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | 330| bool mode | 设置队列任务运行方式。true表示以线程模式运行, false表示以协程方式运行。 | 331 332### ffrt_queue_attr_get_thread_mode() 333 334``` 335FFRT_C_API bool ffrt_queue_attr_get_thread_mode(const ffrt_queue_attr_t* attr) 336``` 337 338**描述** 339 340获取队列中的任务是以协程模式还是以线程模式运行。 341 342**起始版本：** 20 343 344 345**参数：** 346 347| 参数项 | 描述 | 348| -- | -- | 349| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性指针。 | 350 351**返回：** 352 353| 类型 | 说明 | 354| -- | -- | 355| FFRT_C_API bool | true表示以线程模式运行，false表示以协程模式运行。 | 356 357### ffrt_queue_create() 358 359``` 360FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr) 361``` 362 363**描述** 364 365创建队列。 366 367**起始版本：** 10 368 369 370**参数：** 371 372| 参数项 | 描述 | 373| -- | -- | 374| [ffrt_queue_type_t](capi-queue-h.md#ffrt_queue_type_t) type | 队列类型。 | 375| const char* name | 队列名字。 | 376| [const ffrt_queue_attr_t](capi-ffrt-ffrt-queue-attr-t.md)* attr | 队列属性。 | 377 378**返回：** 379 380| 类型 | 说明 | 381|-----------------------------| -- | 382| FFRT_C_API [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) | 创建队列成功返回非空队列句柄，<br> 创建队列失败返回空指针。 | 383 384### ffrt_queue_destroy() 385 386``` 387FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue) 388``` 389 390**描述** 391 392销毁队列。 393 394**起始版本：** 10 395 396 397**参数：** 398 399| 参数项 | 描述 | 400| -- | -- | 401| [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列句柄。 | 402 403### ffrt_queue_submit() 404 405``` 406FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr) 407``` 408 409**描述** 410 411提交一个任务到队列中调度执行。 412 413**起始版本：** 10 414 415 416**参数：** 417 418| 参数项 | 描述 | 419| -- | -- | 420| [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列句柄。 | 421| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 任务的执行体。 | 422| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | 423 424### ffrt_queue_submit_h() 425 426``` 427FFRT_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) 428``` 429 430**描述** 431 432提交一个任务到队列中调度执行，并返回任务句柄。 433 434**起始版本：** 10 435 436 437**参数：** 438 439| 参数项 | 描述 | 440| -- | -- | 441| [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列句柄。 | 442| [ffrt_function_header_t](capi-ffrt-ffrt-function-header-t.md)* f | 任务的执行体。 | 443| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | 444 445**返回：** 446 447| 类型 | 说明 | 448|-----------------------------------| -- | 449| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | 提交成功返回非空任务句柄，<br> 提交失败返回空指针。 | 450 451### ffrt_queue_submit_f() 452 453``` 454FFRT_C_API void ffrt_queue_submit_f(ffrt_queue_t queue, ffrt_function_t func, void* arg, const ffrt_task_attr_t* attr) 455``` 456 457**描述** 458 459提交一个任务到队列中调度执行，是ffrt_queue_submit接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为队列任务结构，并将封装后的任务结构和其他参数传递给ffrt_queue_submit接口。 460 461**起始版本：** 20 462 463 464**参数：** 465 466| 参数项 | 描述 | 467| -- | -- | 468| [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列句柄。 | 469| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | 指定的任务函数。 | 470| void* arg | 传递给任务函数的参数。 | 471| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | 472 473**参考：** 474 475[ffrt_queue_submit](capi-queue-h.md#ffrt_queue_submit) 476 477 478### ffrt_queue_submit_h_f() 479 480``` 481FFRT_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) 482``` 483 484**描述** 485 486提交一个任务到队列中调度执行，并返回任务句柄，是ffrt_queue_submit_h接口的简化包装形式。该接口假定任务不需要销毁回调函数，给定的任务函数和参数被包装为队列任务结构，并将封装后的任务结构和其他参数传递给ffrt_queue_submit_h接口。 487 488**起始版本：** 20 489 490 491**参数：** 492 493| 参数项 | 描述 | 494| -- | -- | 495| [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) queue | 队列句柄。 | 496| [ffrt_function_t](capi-type-def-h.md#ffrt_function_t) func | 指定的任务函数。 | 497| void* arg | 传递给任务函数的参数。 | 498| [const ffrt_task_attr_t](capi-ffrt-ffrt-task-attr-t.md)* attr | 任务属性。 | 499 500**返回：** 501 502| 类型 | 说明 | 503| -- | -- | 504| FFRT_C_API [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) | 提交成功返回非空任务句柄，<br> 提交失败返回空指针。 | 505 506**参考：** 507 508[ffrt_queue_submit_h](capi-queue-h.md#ffrt_queue_submit_h) 509 510 511### ffrt_queue_wait() 512 513``` 514FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle) 515``` 516 517**描述** 518 519等待队列中一个任务执行完成。 520 521**起始版本：** 10 522 523 524**参数：** 525 526| 参数项 | 描述 | 527| -- | -- | 528| [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) handle | 任务句柄。 | 529 530### ffrt_queue_cancel() 531 532``` 533FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle) 534``` 535 536**描述** 537 538取消队列中一个任务。 539 540**起始版本：** 10 541 542 543**参数：** 544 545| 参数项 | 描述 | 546| -- | -- | 547| [ffrt_task_handle_t](capi-ffrt-ffrt-task-handle-t.md) handle | 任务句柄。 | 548 549**返回：** 550 551| 类型 | 说明 | 552| -- | -- | 553| FFRT_C_API int | 取消任务成功返回0，<br> 取消任务失败返回-1。 | 554 555### ffrt_get_main_queue() 556 557``` 558FFRT_C_API ffrt_queue_t ffrt_get_main_queue(void) 559``` 560 561**描述** 562 563获取主线程队列。 564 565**起始版本：** 12 566 567**返回：** 568 569| 类型 | 说明 | 570| -- | -- | 571| FFRT_C_API [ffrt_queue_t](capi-ffrt-ffrt-queue-t.md) | 返回主线程队列句柄。 | 572 573### ffrt_get_current_queue() 574 575``` 576FFRT_C_API ffrt_queue_t ffrt_get_current_queue(void) 577``` 578 579**描述** 580 581获取应用Worker(ArkTs)线程队列。 582 583**起始版本：** 12 584 585**废弃版本：** 18 586 587**返回：** 588 589| 类型 | 说明 | 590| -- | -- | 591| FFRT_C_API ffrt_queue_t | 返回当前线程队列句柄。 | 592 593 594