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  * @addtogroup Ffrt
18  * @{
19  *
20  * @brief ffrt provides APIs.
21  *
22  *
23  * @syscap SystemCapability.Resourceschedule.Ffrt.Core
24  *
25  * @since 10
26  */
27 
28 /**
29  * @file queue.h
30  *
31  * @brief Declares the queue interfaces in C.
32  *
33  * @syscap SystemCapability.Resourceschedule.Ffrt.Core
34  * @since 10
35  * @version 1.0
36  */
37 #ifndef FFRT_API_C_QUEUE_H
38 #define FFRT_API_C_QUEUE_H
39 
40 #include "type_def.h"
41 
42 typedef enum {
43     ffrt_queue_serial,
44     ffrt_queue_concurrent,
45     ffrt_queue_max
46 } ffrt_queue_type_t;
47 
48 typedef void* ffrt_queue_t;
49 
50 /**
51  * @brief Initializes the queue attribute.
52  *
53  * @param attr Indicates a pointer to the queue attribute.
54  * @return Returns <b>0</b> if the queue attribute is initialized;
55            returns <b>-1</b> otherwise.
56  * @since 10
57  * @version 1.0
58  */
59 FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr);
60 
61 /**
62  * @brief Destroys a queue attribute.
63  *
64  * @param attr Indicates a pointer to the queue attribute.
65  * @since 10
66  * @version 1.0
67  */
68 FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr);
69 
70 /**
71  * @brief Sets the QoS for a queue attribute.
72  *
73  * @param attr Indicates a pointer to the queue attribute.
74  * @param attr Indicates the QoS.
75  * @since 10
76  * @version 1.0
77  */
78 FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos);
79 
80 /**
81  * @brief Obtains the QoS of a queue attribute.
82  *
83  * @param attr Indicates a pointer to the queue attribute.
84  * @return Returns the QoS.
85  * @since 10
86  * @version 1.0
87  */
88 FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr);
89 
90 /**
91  * @brief Set the serial queue task execution timeout.
92  *
93  * @param attr Serial Queue Property Pointer.
94  * @param timeout_us Serial queue task execution timeout.
95  * @since 10
96  * @version 1.0
97  */
98 FFRT_C_API void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t timeout_us);
99 
100 /**
101  * @brief Get the serial queue task execution timeout.
102  *
103  * @param attr Serial Queue Property Pointer.
104  * @return Returns the serial queue task execution timeout.
105  * @since 10
106  * @version 1.0
107  */
108 FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr);
109 
110 /**
111  * @brief Set the serial queue timeout callback function.
112  *
113  * @param attr Serial Queue Property Pointer.
114  * @param f Serial queue timeout callback function.
115  * @since 10
116  * @version 1.0
117  */
118 FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_function_header_t* f);
119 
120 /**
121  * @brief Get the serial queue task timeout callback function.
122  *
123  * @param attr Serial Queue Property Pointer.
124  * @return Returns the serial queue task timeout callback function.
125  * @since 10
126  * @version 1.0
127  */
128 FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr);
129 
130 /**
131  * @brief Set the queue max concurrency.
132  *
133  * @param attr Queue Property Pointer.
134  * @param max_concurrency queue max_concurrency.
135  * @since 12
136  * @version 1.0
137  */
138 FFRT_C_API void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, const int max_concurrency);
139 
140 /**
141  * @brief Get the queue max concurrency.
142  *
143  * @param attr Queue Property Pointer.
144  * @return Returns the queue max concurrency.
145  * @since 12
146  * @version 1.0
147  */
148 FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr);
149 
150 /**
151  * @brief Creates a queue.
152  *
153  * @param type Indicates the queue type.
154  * @param name Indicates a pointer to the queue name.
155  * @param attr Indicates a pointer to the queue attribute.
156  * @return Returns a non-null queue handle if the queue is created;
157            returns a null pointer otherwise.
158  * @since 10
159  * @version 1.0
160  */
161 FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr);
162 
163 /**
164  * @brief Destroys a queue.
165  *
166  * @param queue Indicates a queue handle.
167  * @since 10
168  * @version 1.0
169  */
170 FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue);
171 
172 /**
173  * @brief Submits a task to a queue.
174  *
175  * @param queue Indicates a queue handle.
176  * @param f Indicates a pointer to the task executor.
177  * @param attr Indicates a pointer to the task attribute.
178  * @since 10
179  * @version 1.0
180  */
181 FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr);
182 
183 /**
184  * @brief Submits a task to the queue, and obtains a task handle.
185  *
186  * @param queue Indicates a queue handle.
187  * @param f Indicates a pointer to the task executor.
188  * @param attr Indicates a pointer to the task attribute.
189  * @return Returns a non-null task handle if the task is submitted;
190            returns a null pointer otherwise.
191  * @since 10
192  * @version 1.0
193  */
194 FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h(
195     ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr);
196 
197 /**
198  * @brief Waits until a task in the queue is complete.
199  *
200  * @param handle Indicates a task handle.
201  * @since 10
202  * @version 1.0
203  */
204 FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle);
205 
206 /**
207  * @brief Cancels a task in the queue.
208  *
209  * @param handle Indicates a task handle.
210  * @return Returns <b>0</b> if the task is canceled;
211            returns <b>-1</b> otherwise.
212  * @since 10
213  * @version 1.0
214  */
215 FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle);
216 
217 /**
218  * @brief Get application main thread queue.
219  *
220  * @return Returns application main thread queue.
221  * @since 12
222  * @version 1.0
223  */
224 FFRT_C_API ffrt_queue_t ffrt_get_main_queue();
225 
226 /**
227  * @brief Get application worker(ArkTs) thread queue.
228  *
229  * @return Returns application worker(ArkTs) thread queue.
230  * @since 12
231  * @version 1.0
232  */
233 FFRT_C_API ffrt_queue_t ffrt_get_current_queue();
234 
235 /**
236  * @brief Get queue task count.
237  *
238  * @param queue Indicates a queue handle.
239  * @return Returns the queue task count.
240  * @since 10
241  * @version 1.0
242  */
243 FFRT_C_API uint64_t ffrt_queue_get_task_cnt(ffrt_queue_t queue);
244 
245 /**
246  * @brief Submits a task to a queue, for tasks with the same delay, insert the header.
247  *
248  * @param queue Indicates a queue handle.
249  * @param f Indicates a pointer to the task executor.
250  * @param attr Indicates a pointer to the task attribute.
251  * @version 1.0
252  */
253 FFRT_C_API void ffrt_queue_submit_head(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr);
254 
255 /**
256  * @brief Submits a task to the queue, and obtains a task handle, for tasks with the same delay, insert the header.
257  *
258  * @param queue Indicates a queue handle.
259  * @param f Indicates a pointer to the task executor.
260  * @param attr Indicates a pointer to the task attribute.
261  * @return Returns a non-null task handle if the task is submitted;
262            returns a null pointer otherwise.
263  * @version 1.0
264  */
265 FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_head_h(
266     ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr);
267 
268 #endif // FFRT_API_C_QUEUE_H