• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Function Flow Runtime并发队列(C)
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
12FFRT并发队列提供了设置任务优先级（Priority）和队列并发度的能力，使得队列中的任务能同时在多个线程上执行，获得更高的并行效果。
13
14- **队列并发度**：通过队列最大并发度设置，可以控制同一时刻同时执行的任务数量。这有助于避免任务并发过多对系统资源造成冲击，从而保证系统的稳定性和性能。
15- **任务优先级**：用户可以为每个任务设置优先级，不同的任务将严格按照优先级进行调度和执行。相同优先级的任务按照排队顺序执行，高优先级的任务将优先于低优先级的任务执行，确保关键任务能够及时处理。
16
17## 示例：银行服务系统
18
19举例实现一个银行服务系统，每个客户向系统提交一个服务请求，可以区分普通用户和VIP用户，VIP用户的服务请求可以优先得到执行。
20银行系统中有2个窗口，可以并行取出用户提交的服务请求办理。可以利用FFRT的并行队列范式做如下建模：
21
22- **排队逻辑**：并行队列。
23- **服务窗口**：并行队列的并发度，同时也对应FFRT Worker数量。
24- **用户等级**：并行队列任务优先级。
25
26实现代码如下所示：
27
28```c
29#include <stdio.h>
30#include <unistd.h>
31#include "ffrt/ffrt.h" // 来自 OpenHarmony 第三方库 "@ppd/ffrt"
32
33ffrt_queue_t create_bank_system(const char *name, int concurrency)
34{
35    ffrt_queue_attr_t queue_attr;
36    (void)ffrt_queue_attr_init(&queue_attr);
37    ffrt_queue_attr_set_max_concurrency(&queue_attr, concurrency);
38
39    // 创建一个并发队列
40    ffrt_queue_t queue = ffrt_queue_create(ffrt_queue_concurrent, name, &queue_attr);
41
42    // 队列创建完后需要销毁队列属性
43    ffrt_queue_attr_destroy(&queue_attr);
44    if (!queue) {
45        printf("create queue failed\n");
46        return NULL;
47    }
48
49    printf("create bank system successfully\n");
50    return queue;
51}
52
53void destroy_bank_system(ffrt_queue_t queue_handle)
54{
55    ffrt_queue_destroy(queue_handle);
56    printf("destroy bank system successfully\n");
57}
58
59void bank_business(void *arg)
60{
61    usleep(100 * 1000);
62    const char *data = (const char *)arg;
63    printf("saving or withdraw for %s\n", data);
64}
65
66// 封装提交队列任务函数
67ffrt_task_handle_t commit_request(ffrt_queue_t bank, void (*func)(void *), const char *name,
68    ffrt_queue_priority_t level, int delay)
69{
70    ffrt_task_attr_t task_attr;
71    (void)ffrt_task_attr_init(&task_attr);
72    ffrt_task_attr_set_name(&task_attr, name);
73    ffrt_task_attr_set_queue_priority(&task_attr, level);
74    ffrt_task_attr_set_delay(&task_attr, delay);
75
76    return ffrt_queue_submit_h_f(bank, func, name, &task_attr);
77}
78
79// 封装取消队列任务函数
80int cancel_request(ffrt_task_handle_t request)
81{
82    return ffrt_queue_cancel(request);
83}
84
85// 封装等待队列任务函数
86void wait_for_request(ffrt_task_handle_t task)
87{
88    ffrt_queue_wait(task);
89}
90
91int main()
92{
93    ffrt_queue_t bank = create_bank_system("Bank", 2);
94    if (!bank) {
95        printf("create bank system failed\n");
96        return -1;
97    }
98
99    ffrt_task_handle_t task1 = commit_request(bank, bank_business, "customer1", ffrt_queue_priority_low, 0);
100    ffrt_task_handle_t task2 = commit_request(bank, bank_business, "customer2", ffrt_queue_priority_low, 0);
101    // VIP享受更优先的服务
102    ffrt_task_handle_t task3 = commit_request(bank, bank_business, "customer3 VIP", ffrt_queue_priority_high, 0);
103    ffrt_task_handle_t task4 = commit_request(bank, bank_business, "customer4", ffrt_queue_priority_low, 0);
104    ffrt_task_handle_t task5 = commit_request(bank, bank_business, "customer5", ffrt_queue_priority_low, 0);
105
106    // 取消客户4的服务
107    cancel_request(task4);
108
109    // 等待所有的客户服务完成
110    wait_for_request(task5);
111    destroy_bank_system(bank);
112
113    ffrt_task_handle_destroy(task1);
114    ffrt_task_handle_destroy(task2);
115    ffrt_task_handle_destroy(task3);
116    ffrt_task_handle_destroy(task4);
117    ffrt_task_handle_destroy(task5);
118    return 0;
119}
120```
121
122## 接口说明
123
124上述样例中涉及到主要的FFRT的接口包括：
125
126| 名称                                                                                               | 描述                   |
127| -------------------------------------------------------------------------------------------------- | ---------------------- |
128| [ffrt_queue_create](ffrt-api-guideline-c.md#ffrt_queue_t)                                     | 创建队列。             |
129| [ffrt_queue_destroy](ffrt-api-guideline-c.md#ffrt_queue_t)                                   | 销毁队列。             |
130| [ffrt_task_attr_set_queue_priority](ffrt-api-guideline-c.md#ffrt_task_attr_t)     | 设置队列任务优先级。   |
131| [ffrt_queue_attr_set_max_concurrency](ffrt-api-guideline-c.md#ffrt_queue_attr_t) | 设置并发队列的并发度。 |
132| [ffrt_queue_submit_h_f](ffrt-api-guideline-c.md#ffrt_queue_t)                             | 向队列提交一个任务。   |
133
134> **说明：**
135>
136> - 如何使用FFRT C++ API详见：[FFRT C++接口三方库使用指导](ffrt-development-guideline.md#using-ffrt-c-api-1)。
137> - 使用FFRT C接口或C++接口时，都可以通过FFRT C++接口三方库简化头文件包含，即使用`#include "ffrt/ffrt.h"`头文件包含语句。
138
139## 约束限制
140
1411. `ffrt_queue_attr_t`必须先调用`ffrt_queue_attr_init`初始化后再设置/获取属性，不再使用后需要显式调用`ffrt_queue_attr_destroy`释放资源。
1422. `ffrt_queue_t`必须在进程退出前显式调用`ffrt_queue_destroy`释放资源。
1433. 并发队列最大并发度建议控制在合理范围内，配置过大超过Worker线程数没有意义，配置过小可能导致系统资源利用率不足。
144