• 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```cpp
29#include <iostream>
30#include <unistd.h>
31#include "ffrt/ffrt.h" // From the OpenHarmony third-party library "@ppd/ffrt"
32
33class BankQueueSystem {
34private:
35    std::unique_ptr<ffrt::queue> queue_;
36
37public:
38    BankQueueSystem(const char *name, int concurrency)
39    {
40        queue_ = std::make_unique<ffrt::queue>(
41            ffrt::queue_concurrent, name, ffrt::queue_attr().max_concurrency(concurrency));
42        std::cout << "bank system has been initialized" << std::endl;
43    }
44
45    ~BankQueueSystem()
46    {
47        queue_ = nullptr;
48        std::cout << "bank system has been destroyed" << std::endl;
49    }
50
51    // Start to queue, that is, submit queue tasks.
52    ffrt::task_handle Enter(const std::function<void()>& func, const char *name, ffrt_queue_priority_t level, int delay)
53    {
54        return queue_->submit_h(func, ffrt::task_attr().name(name).priority(level).delay(delay));
55    }
56
57    // Exit the queue, that is, cancel queue tasks.
58    int Exit(const ffrt::task_handle &t)
59    {
60        return queue_->cancel(t);
61    }
62
63    // Wait for tasks in the queue.
64    void Wait(const ffrt::task_handle& handle)
65    {
66        queue_->wait(handle);
67    }
68};
69
70void BankBusiness()
71{
72    usleep(100 * 1000);
73    std::cout << "saving or withdraw ordinary customer" << std::endl;
74}
75
76void BankBusinessVIP()
77{
78    usleep(100 * 1000);
79    std::cout << "saving or withdraw VIP" << std::endl;
80}
81
82int main()
83{
84    BankQueueSystem bankQueue("Bank", 2);
85
86    auto task1 = bankQueue.Enter(BankBusiness, "customer1", ffrt_queue_priority_low, 0);
87    auto task2 = bankQueue.Enter(BankBusiness, "customer2", ffrt_queue_priority_low, 0);
88    // VIP customers have the priority to enjoy services.
89    auto task3 = bankQueue.Enter(BankBusinessVIP, "customer3 vip", ffrt_queue_priority_high, 0);
90    auto task4 = bankQueue.Enter(BankBusiness, "customer4", ffrt_queue_priority_low, 0);
91    auto task5 = bankQueue.Enter(BankBusiness, "customer5", ffrt_queue_priority_low, 0);
92
93    // Cancel the service for customer 4.
94    bankQueue.Exit(task4);
95
96    // Wait until all customer services are complete.
97    bankQueue.Wait(task5);
98    return 0;
99}
100```
101
102## Available APIs
103
104The main FFRT APIs involved in the preceding example are as follows:
105
106| Name                                                                                                                         | Description        |
107| ----------------------------------------------------------------------------------------------------------------------------- | ------------ |
108| class [task_attr](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#task_attr)   | Task attribute class.|
109| class [queue_attr](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#queue_attr) | Queue attribute class.|
110| class [queue](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#queue)           | Queue class.    |
111
112> **NOTE**
113>
114> - For details about how to use FFRT C++ APIs, see [Using FFRT C++ APIs](ffrt-development-guideline.md#using-ffrt-c-api-1).
115> - 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.
116
117## Constraints
118
1191. 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.
120