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 task.h
30  *
31  * @brief Declares the task interfaces in C.
32  *
33  * @syscap SystemCapability.Resourceschedule.Ffrt.Core
34  * @since 10
35  * @version 1.0
36  */
37 #ifndef FFRT_API_C_TASK_H
38 #define FFRT_API_C_TASK_H
39 #include <stdint.h>
40 #include "type_def.h"
41 
42 /**
43  * @brief Initializes a task attribute.
44  *
45  * @param attr Indicates a pointer to the task attribute.
46  * @return Returns <b>0</b> if the task attribute is initialized;
47            returns <b>-1</b> otherwise.
48  * @since 10
49  * @version 1.0
50  */
51 FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr);
52 
53 /**
54  * @brief Sets a task name.
55  *
56  * @param attr Indicates a pointer to the task attribute.
57  * @param name Indicates a pointer to the task name.
58  * @since 10
59  * @version 1.0
60  */
61 FFRT_C_API void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name);
62 
63 /**
64  * @brief Obtains a task name.
65  *
66  * @param attr Indicates a pointer to the task attribute.
67  * @return Returns a non-null pointer to the task name if the name is obtained;
68            returns a null pointer otherwise.
69  * @since 10
70  * @version 1.0
71  */
72 FFRT_C_API const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr);
73 
74 /**
75  * @brief Destroys a task attribute.
76  *
77  * @param attr Indicates a pointer to the task attribute.
78  * @since 10
79  * @version 1.0
80  */
81 FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr);
82 
83 /**
84  * @brief Sets the QoS for a task attribute.
85  *
86  * @param attr Indicates a pointer to the task attribute.
87  * @param qos Indicates the QoS.
88  * @since 10
89  * @version 1.0
90  */
91 FFRT_C_API void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos);
92 
93 /**
94  * @brief Obtains the QoS of a task attribute.
95  *
96  * @param attr Indicates a pointer to the task attribute.
97  * @return Returns the QoS, which is <b>ffrt_qos_default</b> by default.
98  * @since 10
99  * @version 1.0
100  */
101 FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr);
102 
103 /**
104  * @brief Sets the task delay time.
105  *
106  * @param attr Indicates a pointer to the task attribute.
107  * @param delay_us Indicates the delay time, in microseconds.
108  * @since 10
109  * @version 1.0
110  */
111 FFRT_C_API void ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_us);
112 
113 /**
114  * @brief Obtains the task delay time.
115  *
116  * @param attr Indicates a pointer to the task attribute.
117  * @return Returns the delay time.
118  * @since 10
119  * @version 1.0
120  */
121 FFRT_C_API uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr);
122 
123 /**
124  * @brief Sets the task priority.
125  *
126  * @param attr Indicates a pointer to the task attribute.
127  * @param priority Indicates the execute priority of concurrent queue task.
128  * @since 12
129  * @version 1.0
130  */
131 FFRT_C_API void ffrt_task_attr_set_queue_priority(ffrt_task_attr_t* attr, ffrt_queue_priority_t priority);
132 
133 /**
134  * @brief Obtains the task priority.
135  *
136  * @param attr Indicates a pointer to the task attribute.
137  * @return Returns the priority of concurrent queue task.
138  * @since 12
139  * @version 1.0
140  */
141 FFRT_C_API ffrt_queue_priority_t ffrt_task_attr_get_queue_priority(const ffrt_task_attr_t* attr);
142 
143 /**
144  * @brief Sets the task stack size.
145  *
146  * @param attr Indicates a pointer to the task attribute.
147  * @param size Indicates the task stack size, unit is byte.
148  * @since 12
149  * @version 1.0
150  */
151 FFRT_C_API void ffrt_task_attr_set_stack_size(ffrt_task_attr_t* attr, uint64_t size);
152 
153 /**
154  * @brief Obtains the task stack size.
155  *
156  * @param attr Indicates a pointer to the task attribute.
157  * @return Returns the task stack size, unit is byte.
158  * @since 12
159  * @version 1.0
160  */
161 FFRT_C_API uint64_t ffrt_task_attr_get_stack_size(const ffrt_task_attr_t* attr);
162 
163 /**
164  * @brief Set the task schedule timeout.
165  *
166  * @param attr Indicates a pointer to the task attribute.
167  * @param timeout_us task scheduler timeout.
168  * @version 1.0
169  */
170 FFRT_C_API void ffrt_task_attr_set_timeout(ffrt_task_attr_t* attr, uint64_t timeout_us);
171 
172 /**
173  * @brief Get the task schedule timeout.
174  *
175  * @param attr Indicates a pointer to the task attribute.
176  * @return Returns the task schedule timeout.
177  * @version 1.0
178  */
179 FFRT_C_API uint64_t ffrt_task_attr_get_timeout(const ffrt_task_attr_t* attr);
180 
181 /**
182  * @brief Updates the QoS of this task.
183  *
184  * @param qos Indicates the new QoS.
185  * @return Returns <b>0</b> if the QoS is updated;
186            returns <b>-1</b> otherwise.
187  * @since 10
188  * @version 1.0
189  */
190 FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos);
191 
192 /**
193  * @brief Obtains the qos of this task.
194  *
195  * @return Returns the task qos.
196  * @since 12
197  * @version 1.0
198  */
199 FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos();
200 
201 /**
202  * @brief Obtains the ID of this task.
203  *
204  * @return Returns the task ID.
205  * @since 10
206  * @version 1.0
207  */
208 FFRT_C_API uint64_t ffrt_this_task_get_id(void);
209 
210 /**
211  * @brief Applies for memory for the function execution structure.
212  *
213  * @param kind Indicates the type of the function execution structure, which can be common or queue.
214  * @return Returns a non-null pointer if the memory is allocated;
215            returns a null pointer otherwise.
216  * @since 10
217  * @version 1.0
218  */
219 FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind);
220 
221 /**
222  * @brief Submits a task.
223  *
224  * @param f Indicates a pointer to the task executor.
225  * @param in_deps Indicates a pointer to the input dependencies.
226  * @param out_deps Indicates a pointer to the output dependencies.
227  * @param attr Indicates a pointer to the task attribute.
228  * @since 10
229  * @version 1.0
230  */
231 FFRT_C_API void ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps,
232     const ffrt_task_attr_t* attr);
233 
234 /**
235  * @brief Submits a task, and obtains a task handle.
236  *
237  * @param f Indicates a pointer to the task executor.
238  * @param in_deps Indicates a pointer to the input dependencies.
239  * @param out_deps Indicates a pointer to the output dependencies.
240  * @param attr Indicates a pointer to the task attribute.
241  * @return Returns a non-null task handle if the task is submitted;
242            returns a null pointer otherwise.
243  * @since 10
244  * @version 1.0
245  */
246 FFRT_C_API ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps,
247     const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr);
248 
249 /**
250  * @brief increase reference count of task handle.
251  *
252  * @param handle Indicates a task handle.
253  * @return return the task handle original reference count.
254  * @since 12
255  * @version 1.0
256  */
257 FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle);
258 
259 /**
260  * @brief decrease reference count of task handle.
261  *
262  * @param handle Indicates a task handle.
263  * @return return the task handle original reference count.
264  * @since 12
265  * @version 1.0
266  */
267 FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle);
268 
269 /**
270  * @brief Destroys a task handle.
271  *
272  * @param handle Indicates a task handle.
273  * @since 10
274  * @version 1.0
275  */
276 FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle);
277 
278 /**
279  * @brief Waits until the dependent tasks are complete.
280  *
281  * @param deps Indicates a pointer to the dependent tasks.
282  * @since 10
283  * @version 1.0
284  */
285 FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps);
286 
287 /**
288  * @brief Waits until all submitted tasks are complete.
289  *
290  * @since 10
291  * @version 1.0
292  */
293 FFRT_C_API void ffrt_wait(void);
294 
295 /**
296  * @brief Sets the thread stack size of a specified QoS level.
297  *
298  * @param qos Indicates the QoS.
299  * @param stack_size Indicates worker thread stack size.
300  * @since 10
301  * @version 1.0
302  */
303 FFRT_C_API ffrt_error_t ffrt_set_worker_stack_size(ffrt_qos_t qos, size_t stack_size);
304 
305 /**
306  * @brief get gid from task handle.
307  *
308  * @param handle Indicates a task handle.
309  * @return Return gid.
310  * @since 10
311  * @version 1.0
312  */
313 FFRT_C_API uint64_t ffrt_task_handle_get_id(ffrt_task_handle_t handle);
314 
315 #endif
316