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 Sets the schedule timeout of a task attribute. 153 * 154 * The lower limit of timeout value is 1 ms, if the value is less than 1 ms, it will be set to 1 ms. 155 * 156 * @param attr Indicates a pointer to the task attribute. 157 * @param timeout_us task scheduler timeout. 158 */ 159 FFRT_C_API void ffrt_task_attr_set_timeout(ffrt_task_attr_t* attr, uint64_t timeout_us); 160 161 /** 162 * @brief Gets the schedule timeout of a task attribute. 163 * 164 * @param attr Indicates a pointer to the task attribute. 165 * @return Returns the task schedule timeout. 166 */ 167 FFRT_C_API uint64_t ffrt_task_attr_get_timeout(const ffrt_task_attr_t* attr); 168 169 /** 170 * @brief Updates the QoS of this task. 171 * 172 * @param qos Indicates the new QoS. 173 * @return Returns <b>0</b> if the QoS is updated; 174 returns <b>-1</b> otherwise. 175 * @since 10 176 */ 177 FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos); 178 179 /** 180 * @brief Gets the QoS of this task. 181 * 182 * @return Returns the task qos. 183 * @since 12 184 */ 185 FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(void); 186 187 /** 188 * @brief Gets the ID of this task. 189 * 190 * @return Returns the task ID. 191 * @since 10 192 */ 193 FFRT_C_API uint64_t ffrt_this_task_get_id(void); 194 195 /** 196 * @brief Applies memory for the function execution structure. 197 * 198 * @param kind Indicates the type of the function execution structure, which can be common or queue. 199 * @return Returns a non-null pointer if the memory is allocated; 200 returns a null pointer otherwise. 201 * @since 10 202 */ 203 FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind); 204 205 /** 206 * @brief Submits a task. 207 * 208 * @param f Indicates a pointer to the task executor. 209 * @param in_deps Indicates a pointer to the input dependencies. 210 * @param out_deps Indicates a pointer to the output dependencies. 211 * @param attr Indicates a pointer to the task attribute. 212 * @since 10 213 */ 214 FFRT_C_API void ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, 215 const ffrt_task_attr_t* attr); 216 217 /** 218 * @brief Submits a task, and obtains a task handle. 219 * 220 * @param f Indicates a pointer to the task executor. 221 * @param in_deps Indicates a pointer to the input dependencies. 222 * @param out_deps Indicates a pointer to the output dependencies. 223 * @param attr Indicates a pointer to the task attribute. 224 * @return Returns a non-null task handle if the task is submitted; 225 returns a null pointer otherwise. 226 * @since 10 227 */ 228 FFRT_C_API ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, 229 const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr); 230 231 /** 232 * @brief Submits a task, simplified from the ffrt_submit_base interface. 233 * 234 * This interface wraps the provided task function and its argument into a task wrapper 235 * designated as a general task (ffrt_function_kind_general). During wrapper creation, the 236 * task destroy callback (after_func), which is intended to handle any post-execution cleanup, 237 * is simplified to NULL. The resulting task wrapper is then submitted using the underlying 238 * ffrt_submit_base interface. 239 * 240 * @param func Indicates a task function to be executed. 241 * @param arg Indicates a pointer to the argument or closure data that will be passed to the task function. 242 * @param in_deps Indicates a pointer to the input dependencies. 243 * @param out_deps Indicates a pointer to the output dependencies. 244 * @param attr Indicates a pointer to the task attribute. 245 * @see ffrt_submit_base 246 * @since 20 247 */ 248 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, 249 const ffrt_task_attr_t* attr); 250 251 /** 252 * @brief Submits a task, and obtains a task handle, simplified from the ffrt_submit_h_base interface. 253 * 254 * This interface wraps the provided task function and its argument into a task wrapper 255 * designated as a general task (ffrt_function_kind_general). During wrapper creation, the 256 * task destroy callback (after_func), which is intended to handle any post-execution cleanup, 257 * is simplified to NULL. The resulting task wrapper is then submitted using the underlying 258 * ffrt_submit_h_base interface. 259 * 260 * @param func Indicates a task function to be executed. 261 * @param arg Indicates a pointer to the argument or closure data that will be passed to the task function. 262 * @param in_deps Indicates a pointer to the input dependencies. 263 * @param out_deps Indicates a pointer to the output dependencies. 264 * @param attr Indicates a pointer to the task attribute. 265 * @return Returns a non-null task handle if the task is submitted; 266 returns a null pointer otherwise. 267 * @see ffrt_submit_h_base 268 * @since 20 269 */ 270 FFRT_C_API ffrt_task_handle_t ffrt_submit_h_f(ffrt_function_t func, void* arg, const ffrt_deps_t* in_deps, 271 const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr); 272 273 /** 274 * @brief Increases reference count of a task. 275 * 276 * @param handle Indicates a task handle. 277 * @return Returns the task handle original reference count. 278 * @since 12 279 */ 280 FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle); 281 282 /** 283 * @brief Decreases reference count of a task. 284 * 285 * @param handle Indicates a task handle. 286 * @return Returns the task handle original reference count. 287 * @since 12 288 */ 289 FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle); 290 291 /** 292 * @brief Destroys a task handle, the user needs to invoke this interface. 293 * 294 * @param handle Indicates a task handle. 295 * @since 10 296 */ 297 FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle); 298 299 /** 300 * @brief Waits until the dependent tasks are complete. 301 * 302 * @param deps Indicates a pointer to the dependent tasks. 303 * @since 10 304 */ 305 FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps); 306 307 /** 308 * @brief Waits until all submitted tasks are complete. 309 * 310 * @since 10 311 */ 312 FFRT_C_API void ffrt_wait(void); 313 314 /** 315 * @brief Sets the thread stack size of a specified QoS level. 316 * 317 * @param qos Indicates the QoS. 318 * @param stack_size Indicates worker thread stack size. 319 */ 320 FFRT_C_API ffrt_error_t ffrt_set_worker_stack_size(ffrt_qos_t qos, size_t stack_size); 321 322 /** 323 * @brief Gets gid of a task. 324 * 325 * @param handle Indicates a task handle. 326 * @return Returns gid. 327 */ 328 FFRT_C_API uint64_t ffrt_task_handle_get_id(ffrt_task_handle_t handle); 329 330 #endif // FFRT_API_C_TASK_H 331 /** @} */