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 Provides FFRT C APIs. 21 * 22 * @since 10 23 */ 24 25 /** 26 * @file task.h 27 * 28 * @brief Declares the task interfaces in C. 29 * 30 * @library libffrt.z.so 31 * @kit FunctionFlowRuntimeKit 32 * @syscap SystemCapability.Resourceschedule.Ffrt.Core 33 * @since 10 34 */ 35 36 #ifndef FFRT_API_C_TASK_H 37 #define FFRT_API_C_TASK_H 38 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 */ 50 FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr); 51 52 /** 53 * @brief Sets the name of a task attribute. 54 * 55 * @param attr Indicates a pointer to the task attribute. 56 * @param name Indicates a pointer to the task name. 57 * @since 10 58 */ 59 FFRT_C_API void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name); 60 61 /** 62 * @brief Gets the name of a task attribute. 63 * 64 * @param attr Indicates a pointer to the task attribute. 65 * @return Returns a non-null pointer to the task name if the name is obtained; 66 returns a null pointer otherwise. 67 * @since 10 68 */ 69 FFRT_C_API const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr); 70 71 /** 72 * @brief Destroys a task attribute, the user needs to invoke this interface. 73 * 74 * @param attr Indicates a pointer to the task attribute. 75 * @since 10 76 */ 77 FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr); 78 79 /** 80 * @brief Sets the QoS of a task attribute. 81 * 82 * @param attr Indicates a pointer to the task attribute. 83 * @param qos Indicates the QoS. 84 * @since 10 85 */ 86 FFRT_C_API void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos); 87 88 /** 89 * @brief Gets the QoS of a task attribute. 90 * 91 * @param attr Indicates a pointer to the task attribute. 92 * @return Returns the QoS, which is <b>ffrt_qos_default</b> by default. 93 * @since 10 94 */ 95 FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr); 96 97 /** 98 * @brief Sets the delay time of a task attribute. 99 * 100 * @param attr Indicates a pointer to the task attribute. 101 * @param delay_us Indicates the delay time, in microseconds. 102 * @since 10 103 */ 104 FFRT_C_API void ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_us); 105 106 /** 107 * @brief Gets the delay time of a task attribute. 108 * 109 * @param attr Indicates a pointer to the task attribute. 110 * @return Returns the delay time. 111 * @since 10 112 */ 113 FFRT_C_API uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr); 114 115 /** 116 * @brief Sets the priority of a task attribute. 117 * 118 * @param attr Indicates a pointer to the task attribute. 119 * @param priority Indicates the execute priority of concurrent queue task. 120 * @since 12 121 */ 122 FFRT_C_API void ffrt_task_attr_set_queue_priority(ffrt_task_attr_t* attr, ffrt_queue_priority_t priority); 123 124 /** 125 * @brief Gets the priority of a task attribute. 126 * 127 * @param attr Indicates a pointer to the task attribute. 128 * @return Returns the priority of concurrent queue task. 129 * @since 12 130 */ 131 FFRT_C_API ffrt_queue_priority_t ffrt_task_attr_get_queue_priority(const ffrt_task_attr_t* attr); 132 133 /** 134 * @brief Sets the stack size of a task attribute. 135 * 136 * @param attr Indicates a pointer to the task attribute. 137 * @param size Indicates the task stack size, unit is byte. 138 * @since 12 139 */ 140 FFRT_C_API void ffrt_task_attr_set_stack_size(ffrt_task_attr_t* attr, uint64_t size); 141 142 /** 143 * @brief Gets the stack size of a task attribute. 144 * 145 * @param attr Indicates a pointer to the task attribute. 146 * @return Returns the task stack size, unit is byte. 147 * @since 12 148 */ 149 FFRT_C_API uint64_t ffrt_task_attr_get_stack_size(const ffrt_task_attr_t* attr); 150 151 /** 152 * @brief Updates the QoS of this task. 153 * 154 * @param qos Indicates the new QoS. 155 * @return Returns <b>0</b> if the QoS is updated; 156 returns <b>-1</b> otherwise. 157 * @since 10 158 */ 159 FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos); 160 161 /** 162 * @brief Gets the QoS of this task. 163 * 164 * @return Returns the task qos. 165 * @since 12 166 */ 167 FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(void); 168 169 /** 170 * @brief Gets the ID of this task. 171 * 172 * @return Returns the task ID. 173 * @since 10 174 */ 175 FFRT_C_API uint64_t ffrt_this_task_get_id(void); 176 177 /** 178 * @brief Applies memory for the function execution structure. 179 * 180 * @param kind Indicates the type of the function execution structure, which can be common or queue. 181 * @return Returns a non-null pointer if the memory is allocated; 182 returns a null pointer otherwise. 183 * @since 10 184 */ 185 FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind); 186 187 /** 188 * @brief Submits a task. 189 * 190 * @param f Indicates a pointer to the task executor. 191 * @param in_deps Indicates a pointer to the input dependencies. 192 * @param out_deps Indicates a pointer to the output dependencies. 193 * @param attr Indicates a pointer to the task attribute. 194 * @since 10 195 */ 196 FFRT_C_API void ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, 197 const ffrt_task_attr_t* attr); 198 199 /** 200 * @brief Submits a task, and obtains a task handle. 201 * 202 * @param f Indicates a pointer to the task executor. 203 * @param in_deps Indicates a pointer to the input dependencies. 204 * @param out_deps Indicates a pointer to the output dependencies. 205 * @param attr Indicates a pointer to the task attribute. 206 * @return Returns a non-null task handle if the task is submitted; 207 returns a null pointer otherwise. 208 * @since 10 209 */ 210 FFRT_C_API ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, 211 const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr); 212 213 /** 214 * @brief Submits a task, simplified from the ffrt_submit_base interface. 215 * 216 * This interface wraps the provided task function and its argument into a task wrapper 217 * designated as a general task (ffrt_function_kind_general). During wrapper creation, the 218 * task destroy callback (after_func), which is intended to handle any post-execution cleanup, 219 * is simplified to NULL. The resulting task wrapper is then submitted using the underlying 220 * ffrt_submit_base interface. 221 * 222 * @param func Indicates a task function to be executed. 223 * @param arg Indicates a pointer to the argument or closure data that will be passed to the task function. 224 * @param in_deps Indicates a pointer to the input dependencies. 225 * @param out_deps Indicates a pointer to the output dependencies. 226 * @param attr Indicates a pointer to the task attribute. 227 * @see ffrt_submit_base 228 * @since 20 229 */ 230 FFRT_C_API void ffrt_submit_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, 231 const ffrt_task_attr_t* attr); 232 233 /** 234 * @brief Submits a task, and obtains a task handle, simplified from the ffrt_submit_h_base interface. 235 * 236 * This interface wraps the provided task function and its argument into a task wrapper 237 * designated as a general task (ffrt_function_kind_general). During wrapper creation, the 238 * task destroy callback (after_func), which is intended to handle any post-execution cleanup, 239 * is simplified to NULL. The resulting task wrapper is then submitted using the underlying 240 * ffrt_submit_h_base interface. 241 * 242 * @param func Indicates a task function to be executed. 243 * @param arg Indicates a pointer to the argument or closure data that will be passed to the task function. 244 * @param in_deps Indicates a pointer to the input dependencies. 245 * @param out_deps Indicates a pointer to the output dependencies. 246 * @param attr Indicates a pointer to the task attribute. 247 * @return Returns a non-null task handle if the task is submitted; 248 returns a null pointer otherwise. 249 * @see ffrt_submit_h_base 250 * @since 20 251 */ 252 FFRT_C_API ffrt_task_handle_t ffrt_submit_h_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, 253 const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr); 254 255 /** 256 * @brief Increases reference count of a task. 257 * 258 * @param handle Indicates a task handle. 259 * @return Returns the task handle original reference count. 260 * @since 12 261 */ 262 FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle); 263 264 /** 265 * @brief Decreases reference count of a task. 266 * 267 * @param handle Indicates a task handle. 268 * @return Returns the task handle original reference count. 269 * @since 12 270 */ 271 FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle); 272 273 /** 274 * @brief Destroys a task handle, the user needs to invoke this interface. 275 * 276 * @param handle Indicates a task handle. 277 * @since 10 278 */ 279 FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle); 280 281 /** 282 * @brief Waits until the dependent tasks are complete. 283 * 284 * @param deps Indicates a pointer to the dependent tasks. 285 * @since 10 286 */ 287 FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps); 288 289 /** 290 * @brief Waits until all submitted tasks are complete. 291 * 292 * @since 10 293 */ 294 FFRT_C_API void ffrt_wait(void); 295 296 #endif // FFRT_API_C_TASK_H 297 /** @} */