• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Function Flow Runtime Concurrent Queue (C++)
2
3## Overview
4
5The 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 effect.
6
7- **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.
8- **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.
9
10## Example: Bank Service System
11
12For 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.
13The bank system has two windows for handling service requests submitted by customers. You can use the FFRT paradigm to perform the following modeling:
14
15- **Queuing logic**: concurrent queue.
16- **Service window**: concurrency of the concurrent queue, which also equals the number of FFRT Worker threads.
17- **Customer level**: priority of concurrent queue tasks.
18
19The implementation code is as follows:
20
21```cpp
22#include <iostream>
23#include <unistd.h>
24#include "ffrt/cpp/queue.h"
25#include "ffrt/cpp/task.h"
26
27class BankQueueSystem {
28private:
29    std::unique_ptr<ffrt::queue> queue_;
30
31public:
32    BankQueueSystem(const char *name, int concurrency)
33    {
34        queue_ = std::make_unique<ffrt::queue>(
35            ffrt::queue_concurrent, name, ffrt::queue_attr().max_concurrency(concurrency));
36        std::cout << "bank system has been initialized" << std::endl;
37    }
38
39    ~BankQueueSystem()
40    {
41        queue_ = nullptr;
42        std::cout << "bank system has been destroyed" << std::endl;
43    }
44
45    // Start to queue, that is, submit queue tasks.
46    ffrt::task_handle Enter(const std::function<void()>& func, const char *name, ffrt_queue_priority_t level, int delay)
47    {
48        return queue_->submit_h(func, ffrt::task_attr().name(name).priority(level).delay(delay));
49    }
50
51    // Exit the queue, that is, cancel queue tasks.
52    int Exit(const ffrt::task_handle &t)
53    {
54        return queue_->cancel(t);
55    }
56
57    // Wait for tasks in the queue.
58    void Wait(const ffrt::task_handle& handle)
59    {
60        queue_->wait(handle);
61    }
62};
63
64void BankBusiness()
65{
66    usleep(100 * 1000);
67    std::cout << "saving or withdraw ordinary customer" << std::endl;
68}
69
70void BankBusinessVIP()
71{
72    usleep(100 * 1000);
73    std::cout << "saving or withdraw VIP" << std::endl;
74}
75
76int main()
77{
78    BankQueueSystem bankQueue("Bank", 2);
79
80    bankQueue.Enter(BankBusiness, "customer1", ffrt_queue_priority_low, 0);
81    bankQueue.Enter(BankBusiness, "customer2", ffrt_queue_priority_low, 0);
82    bankQueue.Enter(BankBusiness, "customer3", ffrt_queue_priority_low, 0);
83    bankQueue.Enter(BankBusiness, "customer4", ffrt_queue_priority_low, 0);
84
85    // VIP customers have the priority to enjoy services.
86    bankQueue.Enter(BankBusinessVIP, "vip", ffrt_queue_priority_high, 0);
87
88    ffrt::task_handle handle = bankQueue.Enter(BankBusiness, "customer5", ffrt_queue_priority_low, 0);
89    ffrt::task_handle handleLast = bankQueue.Enter(BankBusiness, "customer6", ffrt_queue_priority_low, 0);
90
91    // Cancel the service for customer 5.
92    bankQueue.Exit(handle);
93
94    // Wait until all customer services are complete.
95    bankQueue.Wait(handleLast);
96    return 0;
97}
98```
99
100## Available APIs
101
102The main FFRT APIs involved in the preceding example are as follows:
103
104| Name                                                                                                                         | Description        |
105| ----------------------------------------------------------------------------------------------------------------------------- | ------------ |
106| class [task_attr](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#task_attr)   | Task attribute class.|
107| class [queue_attr](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#queue_attr) | Queue attribute class.|
108| class [queue](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#queue)           | Queue class.    |
109
110> **NOTE**
111>
112> For details about how to use FFRT C++ APIs, see [Using FFRT C++ APIs](ffrt-development-guideline.md#using-ffrt-c-api-1).
113
114## Constraints
115
1161. 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.
117