• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Function Flow Runtime Concurrent Queue (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## Overview
11
12The FFRT concurrent queue provides the capability of setting the priority and queue concurrency. Tasks in the queue can be executed on multiple threads at the same time, achieving better effects.
13
14- **Queue concurrency**: You can set the maximum concurrency of a queue to control the number of tasks that can be executed at the same time. This avoids system resource impact caused by excessive concurrent tasks, ensuring system stability and performance.
15- **Task priority**: You can set a priority for each task. Different tasks are scheduled and executed strictly based on the priority. Tasks with the same priority are executed in sequence. Tasks with higher priorities are executed prior to those with lower priorities to ensure that key tasks can be processed in a timely manner.
16
17## Example: Bank Service System
18
19For example, each customer (common customer or VIP customer) submits a service request to the bank service system. The service request of the VIP customer can be processed first.
20The bank system has two windows for handling service requests submitted by customers. You can use the FFRT paradigm to perform the following modeling:
21
22- **Queuing logic**: concurrent queue.
23- **Service window**: concurrency of the concurrent queue, which also equals the number of FFRT Worker threads.
24- **Customer level**: priority of concurrent queue tasks.
25
26The implementation code is as follows:
27
28```c
29#include <stdio.h>
30#include <unistd.h>
31#include "ffrt/ffrt.h" // From the OpenHarmony third-party library "@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    // Create a concurrent queue.
40    ffrt_queue_t queue = ffrt_queue_create(ffrt_queue_concurrent, name, &queue_attr);
41
42    // Destroy the queue attributes after the queue is created.
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// Encapsulate the operation of submitting a task to a queue into a function.
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// Encapsulate the operation of canceling a task in a queue into a function.
80int cancel_request(ffrt_task_handle_t request)
81{
82    return ffrt_queue_cancel(request);
83}
84
85// Encapsulate the operation of waiting for a task in a queue into a function.
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 customers have the priority to enjoy services.
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    // Cancel the service for customer 4.
107    cancel_request(task4);
108
109    // Wait until all customer services are complete.
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## Available APIs
123
124The main FFRT APIs involved in the preceding example are as follows:
125
126| Name                                                                                              | Description                  |
127| -------------------------------------------------------------------------------------------------- | ---------------------- |
128| [ffrt_queue_create](ffrt-api-guideline-c.md#ffrt_queue_t)                                     | Creates a queue.            |
129| [ffrt_queue_destroy](ffrt-api-guideline-c.md#ffrt_queue_t)                                   | Destroys a queue.            |
130| [ffrt_task_attr_set_queue_priority](ffrt-api-guideline-c.md#ffrt_task_attr_t)     | Sets the priority of a task in a queue.  |
131| [ffrt_queue_attr_set_max_concurrency](ffrt-api-guideline-c.md#ffrt_queue_attr_t) | Sets the concurrency of the concurrent queue.|
132| [ffrt_queue_submit_h_f](ffrt-api-guideline-c.md#ffrt_queue_t)                             | Submits a task to a queue.  |
133
134> **NOTE**
135>
136> - For details about how to use FFRT C++ APIs, see [Using FFRT C++ APIs](ffrt-development-guideline.md#using-ffrt-c-api-1).
137> - When using FFRT C or C++ APIs, you can use the FFRT C++ API third-party library to simplify the header file inclusion, that is, use the `#include "ffrt/ffrt.h"` header file to include statements.
138
139## Constraints
140
1411. `ffrt_queue_attr_t` must be initialized by calling `ffrt_queue_attr_init` before the attribute is set or obtained. If `ffrt_queue_attr_t` is no longer used, `ffrt_queue_attr_destroy` needs to be explicitly called to release resources.
1422. `ffrt_queue_t` must explicitly call `ffrt_queue_destroy` to release resources before the process exits.
1433. It is recommended that the maximum concurrency of a concurrent queue be within a proper range. If the value is too large, it is meaningless to exceed the number of Worker threads. If the value is too small, the system resource utilization may be low.
144