1 /*
2  * Copyright (c) 2023 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 /**
17  * @file queue.h
18  *
19  * @brief Declares the queue interfaces in C++.
20  *
21  * @since 10
22  * @version 1.0
23  */
24 #ifndef FFRT_API_CPP_QUEUE_H
25 #define FFRT_API_CPP_QUEUE_H
26 
27 #include "c/queue.h"
28 #include "task.h"
29 
30 namespace ffrt {
31 enum queue_type {
32     queue_serial = ffrt_queue_serial,
33     queue_concurrent = ffrt_queue_concurrent,
34     queue_max = ffrt_queue_max,
35 };
36 
37 class queue_attr : public ffrt_queue_attr_t {
38 public:
queue_attr()39     queue_attr()
40     {
41         ffrt_queue_attr_init(this);
42     }
43 
~queue_attr()44     ~queue_attr()
45     {
46         ffrt_queue_attr_destroy(this);
47     }
48 
49     queue_attr(const queue_attr&) = delete;
50     queue_attr& operator=(const queue_attr&) = delete;
51 
52     /**
53      * @brief Sets the QoS for this queue attribute.
54      *
55      * @param attr Indicates the QoS.
56      * @since 10
57      * @version 1.0
58      */
qos(qos qos_)59     inline queue_attr& qos(qos qos_)
60     {
61         ffrt_queue_attr_set_qos(this, qos_);
62         return *this;
63     }
64 
65     // get qos
qos()66     inline int qos() const
67     {
68         return ffrt_queue_attr_get_qos(this);
69     }
70 
71     // set timeout
timeout(uint64_t timeout_us)72     inline queue_attr& timeout(uint64_t timeout_us)
73     {
74         ffrt_queue_attr_set_timeout(this, timeout_us);
75         return *this;
76     }
77 
78     // get timeout
timeout()79     inline uint64_t timeout() const
80     {
81         return ffrt_queue_attr_get_timeout(this);
82     }
83 
84     // set timeout callback
callback(const std::function<void ()> & func)85     inline queue_attr& callback(const std::function<void()>& func)
86     {
87         ffrt_queue_attr_set_callback(this, create_function_wrapper(func, ffrt_function_kind_queue));
88         return *this;
89     }
90 
91     // get timeout callback
callback()92     inline ffrt_function_header_t* callback() const
93     {
94         return ffrt_queue_attr_get_callback(this);
95     }
96 
97     // set max concurrency of queue
max_concurrency(const int max_concurrency)98     inline queue_attr& max_concurrency(const int max_concurrency)
99     {
100         ffrt_queue_attr_set_max_concurrency(this, max_concurrency);
101         return *this;
102     }
103 
104     // get max concurrency of queue
max_concurrency()105     inline int max_concurrency() const
106     {
107         return ffrt_queue_attr_get_max_concurrency(this);
108     }
109 };
110 
111 class queue {
112 public:
113     queue(const queue_type type, const char* name, const queue_attr& attr = {})
114     {
115         queue_handle = ffrt_queue_create(ffrt_queue_type_t(type), name, &attr);
116     }
117 
118     queue(const char* name, const queue_attr& attr = {})
119     {
120         queue_handle = ffrt_queue_create(ffrt_queue_serial, name, &attr);
121     }
122 
~queue()123     ~queue()
124     {
125         ffrt_queue_destroy(queue_handle);
126     }
127 
128     queue(queue const&) = delete;
129     void operator=(queue const&) = delete;
130 
131     /**
132      * @brief Submits a task with a specified attribute to this queue.
133      *
134      * @param func Indicates a task executor function closure.
135      * @param attr Indicates a task attribute.
136      * @since 10
137      * @version 1.0
138      */
139     inline void submit(const std::function<void()>& func, const task_attr& attr = {})
140     {
141         ffrt_queue_submit(queue_handle, create_function_wrapper(func, ffrt_function_kind_queue), &attr);
142     }
143 
144     /**
145      * @brief Submits a task with a specified attribute to this queue.
146      *
147      * @param func Indicates a task executor function closure.
148      * @param attr Indicates a task attribute.
149      * @since 10
150      * @version 1.0
151      */
152     inline void submit(std::function<void()>&& func, const task_attr& attr = {})
153     {
154         ffrt_queue_submit(queue_handle, create_function_wrapper(std::move(func), ffrt_function_kind_queue), &attr);
155     }
156 
157     /**
158      * @brief Submits a task with a specified attribute to this queue, and obtains a task handle.
159      *
160      * @param func Indicates a task executor function closure.
161      * @param attr Indicates a task attribute.
162      * @return Returns a non-null task handle if the task is submitted;
163                returns a null pointer otherwise.
164      * @since 10
165      * @version 1.0
166      */
167     inline task_handle submit_h(const std::function<void()>& func, const task_attr& attr = {})
168     {
169         return ffrt_queue_submit_h(queue_handle, create_function_wrapper(func, ffrt_function_kind_queue), &attr);
170     }
171 
172     /**
173      * @brief Submits a task with a specified attribute to this queue, and obtains a task handle.
174      *
175      * @param func Indicates a task executor function closure.
176      * @param attr Indicates a task attribute.
177      * @return Returns a non-null task handle if the task is submitted;
178                returns a null pointer otherwise.
179      * @since 10
180      * @version 1.0
181      */
182     inline task_handle submit_h(std::function<void()>&& func, const task_attr& attr = {})
183     {
184         return ffrt_queue_submit_h(
185             queue_handle, create_function_wrapper(std::move(func), ffrt_function_kind_queue), &attr);
186     }
187 
188     /**
189      * @brief Submits a task with a specified attribute to this queue.
190      *
191      * @param func Indicates a task executor function closure.
192      * @param attr Indicates a task attribute.
193      * @since 10
194      * @version 1.0
195      */
196     inline void submit_head(const std::function<void()>& func, const task_attr& attr = {})
197     {
198         ffrt_queue_submit_head(queue_handle, create_function_wrapper(func, ffrt_function_kind_queue), &attr);
199     }
200 
201     /**
202      * @brief Submits a task with a specified attribute to this queue.
203      *
204      * @param func Indicates a task executor function closure.
205      * @param attr Indicates a task attribute.
206      * @since 10
207      * @version 1.0
208      */
209     inline void submit_head(std::function<void()>&& func, const task_attr& attr = {})
210     {
211         ffrt_queue_submit_head(queue_handle, create_function_wrapper(std::move(func), ffrt_function_kind_queue), &attr);
212     }
213 
214     /**
215      * @brief Submits a task with a specified attribute to this queue, and obtains a task handle.
216      *
217      * @param func Indicates a task executor function closure.
218      * @param attr Indicates a task attribute.
219      * @return Returns a non-null task handle if the task is submitted;
220                returns a null pointer otherwise.
221      * @since 10
222      * @version 1.0
223      */
224     inline task_handle submit_head_h(const std::function<void()>& func, const task_attr& attr = {})
225     {
226         return ffrt_queue_submit_head_h(queue_handle, create_function_wrapper(func, ffrt_function_kind_queue), &attr);
227     }
228 
229     /**
230      * @brief Submits a task with a specified attribute to this queue, and obtains a task handle.
231      *
232      * @param func Indicates a task executor function closure.
233      * @param attr Indicates a task attribute.
234      * @return Returns a non-null task handle if the task is submitted;
235                returns a null pointer otherwise.
236      * @since 10
237      * @version 1.0
238      */
239     inline task_handle submit_head_h(std::function<void()>&& func, const task_attr& attr = {})
240     {
241         return ffrt_queue_submit_head_h(
242             queue_handle, create_function_wrapper(std::move(func), ffrt_function_kind_queue), &attr);
243     }
244 
245     /**
246      * @brief Cancels a task.
247      *
248      * @param handle Indicates a task handle.
249      * @return Returns <b>0</b> if the task is canceled;
250                returns <b>-1</b> otherwise.
251      * @since 10
252      * @version 1.0
253      */
cancel(const task_handle & handle)254     inline int cancel(const task_handle& handle)
255     {
256         return ffrt_queue_cancel(handle);
257     }
258 
259     /**
260      * @brief Waits until a task is complete.
261      *
262      * @param handle Indicates a task handle.
263      * @since 10
264      * @version 1.0
265      */
wait(const task_handle & handle)266     inline void wait(const task_handle& handle)
267     {
268         return ffrt_queue_wait(handle);
269     }
270 
271     /**
272      * @brief Get queue task count.
273      *
274      * @param queue Indicates a queue handle.
275      * @return Returns the queue task count.
276      * @since 10
277      * @version 1.0
278     */
get_task_cnt()279     inline uint64_t get_task_cnt()
280     {
281         return ffrt_queue_get_task_cnt(queue_handle);
282     }
283 
284 private:
285     ffrt_queue_t queue_handle = nullptr;
286 };
287 } // namespace ffrt
288 
289 #endif // FFRT_API_CPP_QUEUE_H