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 #ifndef FFRT_API_C_EXECUTOR_TASK_H 16 #define FFRT_API_C_EXECUTOR_TASK_H 17 18 #include <stdint.h> 19 #include <stdbool.h> 20 #include <sys/epoll.h> 21 #include "type_def_ext.h" 22 #include "c/timer.h" 23 24 /** 25 * @brief Struct of the executor_task, also aligns with the base task class. 26 */ 27 typedef struct ffrt_executor_task { 28 uintptr_t reserved[2]; 29 uintptr_t type; // 0: TaskCtx, 1~: Dynamicly Define Task, User Space Address: libuv work 30 void* wq[2]; 31 } ffrt_executor_task_t; 32 33 /** 34 * @brief The executor task types. 35 */ 36 typedef enum { 37 ffrt_normal_task = 0, 38 ffrt_io_task = 1, 39 ffrt_uv_task, // only used to register func for libuv 40 ffrt_queue_task, 41 ffrt_xpu_task, 42 ffrt_invalid_task, 43 } ffrt_executor_task_type_t; 44 45 /** 46 * @brief Function defined to be executed by the workers. 47 * 48 * @param data Indicates the args of the function defined by users. 49 * @param qos Indicates the qos of the task. 50 * @version 1.0 51 */ 52 typedef void (*ffrt_executor_task_func)(ffrt_executor_task_t* data, ffrt_qos_t qos); 53 54 /** 55 * @brief Registers a user-defined function for the workers to execute. 56 * 57 * @param func Indicates a user-defined function. 58 * @param type Indicates which task type the function belongs to. 59 * @version 1.0 60 */ 61 FFRT_C_API void ffrt_executor_task_register_func(ffrt_executor_task_func func, ffrt_executor_task_type_t type); 62 63 /** 64 * @brief Submits a UV task or IO task. 65 * 66 * @param task Indicates a pointer to the task. 67 * @param attr Indicates a pointer to the task attribute. 68 * @version 1.0 69 */ 70 FFRT_C_API void ffrt_executor_task_submit(ffrt_executor_task_t* task, const ffrt_task_attr_t* attr); 71 72 /** 73 * @brief Cancels a UV task or IO task. 74 * 75 * @param task Indicates a pointer to the task. 76 * @param attr Indicates the qos of the task. 77 * @return Returns success or failed. 78 * @version 1.0 79 * 80 */ 81 FFRT_C_API int ffrt_executor_task_cancel(ffrt_executor_task_t* task, const ffrt_qos_t qos); 82 83 /** 84 * @brief Wakeups the ffrt poller. 85 * 86 * @param qos Indicates the qos of the poller. 87 * @version 1.0 88 */ 89 FFRT_C_API void ffrt_poller_wakeup(ffrt_qos_t qos); 90 91 /** 92 * @brief Gets the number of epoll operations performed. 93 * 94 * @param qos Indicates the qos of the poller. 95 * @version 1.0 96 */ 97 FFRT_C_API uint8_t ffrt_epoll_get_count(ffrt_qos_t qos); 98 99 /** 100 * @brief Querys the ffrt timer. 101 * 102 * @param handler Indicates the handler of the timer. 103 * @version 1.0 104 */ 105 FFRT_C_API ffrt_timer_query_t ffrt_timer_query(ffrt_qos_t qos, ffrt_timer_t handle); 106 107 /** 108 * @brief Submits a fd event to the poller. 109 * 110 * @param qos Indicates the qos of the poller. 111 * @param op Indicates the option of the event. 112 * @param fd Indicates the fd of the event. 113 * @param events Indicates the events of the events. 114 * @param data Indicates the args of the event callback function. 115 * @param cb Indicates the callback function of the event. 116 * @version 1.0 117 */ 118 FFRT_C_API int ffrt_epoll_ctl(ffrt_qos_t qos, int op, int fd, uint32_t events, void* data, ffrt_poller_cb cb); 119 120 /** 121 * @brief Waits an epoll event. 122 * 123 * @param qos Indicates the qos of the poller. 124 * @param events Indicates the events of the event. 125 * @param max_events Indicates the max event value. 126 * @param timeout Indicates the time to timeout. 127 * @version 1.0 128 */ 129 FFRT_C_API int ffrt_epoll_wait(ffrt_qos_t qos, struct epoll_event* events, int max_events, int timeout); 130 131 /** 132 * @brief Gets the time a task has waited in the poller. 133 * 134 * @param taskHandle Indicates the pointer of a task. 135 * @version 1.0 136 */ 137 FFRT_C_API uint64_t ffrt_epoll_get_wait_time(void* taskHandle); 138 139 /** 140 * @brief Submit a coroutine IO task. 141 * 142 * @param co Indicates the args of a task executor function. 143 * @param exec Indicates a task executor function. 144 * @param destroy Indicates the destroy function of a task. 145 * @param in_deps Indicates a pointer to the input dependencies. 146 * @param out_deps Indicates a pointer to the output dependencies. 147 * @param attr Indicates a task attribute. 148 * @version 1.0 149 */ 150 FFRT_C_API void ffrt_submit_coroutine(void* co, ffrt_coroutine_ptr_t exec, ffrt_function_t destroy, 151 const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr); 152 153 /** 154 * @brief Wakeups a coroutine IO task. 155 * 156 * @param task Indicates a pointer to the task. 157 * @version 1.0 158 */ 159 FFRT_C_API void ffrt_wake_coroutine(void* task); 160 161 /** 162 * @brief Get the pointer of the current task. 163 * 164 * @return Returns a pointer. 165 * @version 1.0 166 */ 167 FFRT_C_API void* ffrt_get_current_task(void); 168 169 /** 170 * @brief Obtains current coroutine stack address and size. 171 * 172 * @param stack_addr Coroutine stack address. 173 * @param size Coroutine stack size. 174 * @return Returns <b>0</b> if the stack is obtained; 175 * returns <b>-1</b> otherwise. 176 * @since 12 177 * @version 1.0 178 */ 179 FFRT_C_API bool ffrt_get_current_coroutine_stack(void** stack_addr, size_t* size); 180 181 /** 182 * @brief Obtains current task. 183 * 184 * @param none. 185 * @return Returns current task. 186 * @since 12 187 * @version 1.0 188 */ 189 FFRT_C_API void* ffrt_get_cur_task(void); 190 191 /** 192 * @brief Set the taskLocal flag in ffrt_task_attr. 193 * 194 * @param attr The ffrt_task_attr struct. 195 * @param task_local The bool value to be set. 196 * @return none. 197 * @since 12 198 * @version 1.0 199 */ 200 FFRT_C_API void ffrt_task_attr_set_local(ffrt_task_attr_t* attr, bool task_local); 201 202 /** 203 * @brief Obtains the taskLocal flag in ffrt_task_attr. 204 * 205 * @param attr The ffrt_task_attr struct. 206 * @return The bool value of task_local. 207 * @since 12 208 * @version 1.0 209 */ 210 FFRT_C_API bool ffrt_task_attr_get_local(ffrt_task_attr_t* attr); 211 212 /** 213 * @brief Obtains the thread id of the input task handle. 214 * 215 * @param task_handle The task pointer. 216 * @return The thread id of the input task handle. 217 * @version 1.0 218 */ 219 FFRT_C_API pthread_t ffrt_task_get_tid(void* task_handle); 220 221 /** 222 * @brief Obtains the task id cached by the current thread. 223 * 224 * @return Returns the task id. 225 * @version 1.0 226 */ 227 FFRT_C_API uint64_t ffrt_get_cur_cached_task_id(void); 228 #endif