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 */ 51 typedef void (*ffrt_executor_task_func)(ffrt_executor_task_t* data, ffrt_qos_t qos); 52 53 /** 54 * @brief Registers a user-defined function for the workers to execute. 55 * 56 * @param func Indicates a user-defined function. 57 * @param type Indicates which task type the function belongs to. 58 */ 59 FFRT_C_API void ffrt_executor_task_register_func(ffrt_executor_task_func func, ffrt_executor_task_type_t type); 60 61 /** 62 * @brief Submits a UV task or IO task. 63 * 64 * @param task Indicates a pointer to the task. 65 * @param attr Indicates a pointer to the task attribute. 66 */ 67 FFRT_C_API void ffrt_executor_task_submit(ffrt_executor_task_t* task, const ffrt_task_attr_t* attr); 68 69 /** 70 * @brief Cancels a UV task or IO task. 71 * 72 * @param task Indicates a pointer to the task. 73 * @param attr Indicates the qos of the task. 74 * @return Returns success or failed. 75 * 76 */ 77 FFRT_C_API int ffrt_executor_task_cancel(ffrt_executor_task_t* task, const ffrt_qos_t qos); 78 79 /** 80 * @brief Wakeups the ffrt poller. 81 * 82 * @param qos Indicates the qos of the poller. 83 */ 84 FFRT_C_API void ffrt_poller_wakeup(ffrt_qos_t qos); 85 86 /** 87 * @brief Gets the number of epoll operations performed. 88 * 89 * @param qos Indicates the qos of the poller. 90 */ 91 FFRT_C_API uint8_t ffrt_epoll_get_count(ffrt_qos_t qos); 92 93 /** 94 * @brief Querys the ffrt timer. 95 * 96 * @param handler Indicates the handler of the timer. 97 */ 98 FFRT_C_API ffrt_timer_query_t ffrt_timer_query(ffrt_qos_t qos, ffrt_timer_t handle); 99 100 /** 101 * @brief Submits a fd event to the poller. 102 * 103 * FFRT provides two ways to deal with fd events: 104 * - Mode 1: execute the cb function 105 * - Mode 2: register fd event into FFRT by ffrt_epoll_ctl, then wait for fd event by ffrt_epoll_wait 106 * In Mode 1, ffrt_epoll_ctl can be called in user thread or ffrt task 107 * FFRT will monitor the fd event and then execute the cb function. 108 * In Mode 2, both ffrt_epoll_ctl and ffrt_epoll_wait must be called in the same ffrt task. 109 * 110 * @warning Do not call `exit` in `cb` - this my cause unexpected behavior. 111 * 112 * @param qos Indicates the qos of the poller. 113 * @param op Indicates the option of the event. 114 * @param fd Indicates the fd of the event. Only supports eventfd, timerfd, and harware I/O. 115 * @param events Indicates the events of the events. 116 * @param data Indicates the args of the event callback function. 117 * @param cb Indicates the callback function of the event. 118 */ 119 FFRT_C_API int ffrt_epoll_ctl(ffrt_qos_t qos, int op, int fd, uint32_t events, void* data, ffrt_poller_cb cb); 120 121 /** 122 * @brief Waits an epoll event. 123 * 124 * Calling ffrt_epoll_wait will block the task. 125 * Both ffrt_epoll_wait and ffrt_epoll_ctl must be called in the same ffrt task. 126 * 127 * @param qos Indicates the qos of the poller. 128 * @param events Indicates the events of the event. 129 * @param max_events Indicates the max event value. 130 * @param timeout Indicates the time to timeout. 131 */ 132 FFRT_C_API int ffrt_epoll_wait(ffrt_qos_t qos, struct epoll_event* events, int max_events, int timeout); 133 134 /** 135 * @brief Gets the time a task has waited in the poller. 136 * 137 * @param taskHandle Indicates the pointer of a task. 138 */ 139 FFRT_C_API uint64_t ffrt_epoll_get_wait_time(void* taskHandle); 140 141 /** 142 * @brief Submit a coroutine IO task. 143 * 144 * @param co Indicates the args of a task executor function. 145 * @param exec Indicates a task executor function. 146 * @param destroy Indicates the destroy function of a task. 147 * @param in_deps Indicates a pointer to the input dependencies. 148 * @param out_deps Indicates a pointer to the output dependencies. 149 * @param attr Indicates a task attribute. 150 */ 151 FFRT_C_API void ffrt_submit_coroutine(void* co, ffrt_coroutine_ptr_t exec, ffrt_function_t destroy, 152 const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr); 153 154 /** 155 * @brief Wakeups a coroutine IO task. 156 * 157 * @param task Indicates a pointer to the task. 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 */ 166 FFRT_C_API void* ffrt_get_current_task(void); 167 168 /** 169 * @brief Obtains current coroutine stack address and size. 170 * 171 * @param stack_addr Coroutine stack address. 172 * @param size Coroutine stack size. 173 * @return Returns <b>0</b> if the stack is obtained; 174 * returns <b>-1</b> otherwise. 175 * @since 12 176 */ 177 FFRT_C_API bool ffrt_get_current_coroutine_stack(void** stack_addr, size_t* size); 178 179 /** 180 * @brief Obtains current task. 181 * 182 * @param none. 183 * @return Returns current task. 184 * @since 12 185 */ 186 FFRT_C_API void* ffrt_get_cur_task(void); 187 188 /** 189 * @brief Set the taskLocal flag in ffrt_task_attr. 190 * 191 * @param attr The ffrt_task_attr struct. 192 * @param task_local The bool value to be set. 193 * @return none. 194 * @since 12 195 */ 196 FFRT_C_API void ffrt_task_attr_set_local(ffrt_task_attr_t* attr, bool task_local); 197 198 /** 199 * @brief Obtains the taskLocal flag in ffrt_task_attr. 200 * 201 * @param attr The ffrt_task_attr struct. 202 * @return The bool value of task_local. 203 * @since 12 204 */ 205 FFRT_C_API bool ffrt_task_attr_get_local(ffrt_task_attr_t* attr); 206 207 /** 208 * @brief Obtains the thread id of the input task handle. 209 * 210 * @param task_handle The task pointer. 211 * @return The thread id of the input task handle. 212 */ 213 FFRT_C_API pthread_t ffrt_task_get_tid(void* task_handle); 214 215 /** 216 * @brief Obtains the task id cached by the current thread. 217 * 218 * @return Returns the task id. 219 */ 220 FFRT_C_API uint64_t ffrt_get_cur_cached_task_id(void); 221 #endif