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 queue.h 27 * 28 * @brief Declares the queue 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_QUEUE_H 37 #define FFRT_API_C_QUEUE_H 38 39 #include "type_def.h" 40 41 /** 42 * @brief Enumerates the queue types. 43 * 44 * @since 12 45 */ 46 typedef enum { 47 /** Serial queue. */ 48 ffrt_queue_serial, 49 /** Concurrent queue. */ 50 ffrt_queue_concurrent, 51 /** Invalid queue. */ 52 ffrt_queue_max 53 } ffrt_queue_type_t; 54 55 /** 56 * @brief Defines the queue handle, which identifies different queues. 57 * 58 * @since 10 59 */ 60 typedef void* ffrt_queue_t; 61 62 /** 63 * @brief Initializes a queue attribute. 64 * 65 * @param attr Indicates a pointer to the queue attribute. 66 * @return Returns <b>0</b> if the queue attribute is initialized; 67 returns <b>-1</b> otherwise. 68 * @since 10 69 */ 70 FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr); 71 72 /** 73 * @brief Destroys a queue attribute, the user needs to invoke this interface. 74 * 75 * @param attr Indicates a pointer to the queue attribute. 76 * @since 10 77 */ 78 FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr); 79 80 /** 81 * @brief Sets the QoS for a queue attribute. 82 * 83 * @param attr Indicates a pointer to the queue attribute. 84 * @param qos Indicates the QoS. 85 * @since 10 86 */ 87 FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos); 88 89 /** 90 * @brief Gets the QoS of a queue attribute. 91 * 92 * @param attr Indicates a pointer to the queue attribute. 93 * @return Returns the QoS. 94 * @since 10 95 */ 96 FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr); 97 98 /** 99 * @brief Sets the execution timeout of a serial queue attribute. 100 * 101 * The lower limit of timeout value is 1 ms, if the value is less than 1 ms, it will be set to 1 ms. 102 * 103 * @param attr Serial queue attribute pointer. 104 * @param timeout_us Serial queue task execution timeout. 105 * @since 10 106 */ 107 FFRT_C_API void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t timeout_us); 108 109 /** 110 * @brief Gets the execution timeout of a serial queue attribute. 111 * 112 * @param attr Serial queue attribute pointer. 113 * @return Returns the serial queue task execution timeout. 114 * @since 10 115 */ 116 FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr); 117 118 /** 119 * @brief Sets the timeout callback function of a serial queue attribute. 120 * 121 * @warning Do not call `exit` in `f` - this my cause unexpected behavior. 122 * @param attr Serial queue attribute pointer. 123 * @param f Serial queue timeout callback function. 124 * @since 10 125 */ 126 FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_function_header_t* f); 127 128 /** 129 * @brief Gets the timeout callback function of a serial queue attribute. 130 * 131 * @param attr Serial queue attribute pointer. 132 * @return Returns the serial queue task timeout callback function. 133 * @since 10 134 */ 135 FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr); 136 137 /** 138 * @brief Sets the queue max concurrency of a queue attribute. 139 * 140 * @param attr Queue attribute pointer. 141 * @param max_concurrency queue max_concurrency. 142 * @since 12 143 */ 144 FFRT_C_API void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, const int max_concurrency); 145 146 /** 147 * @brief Gets the queue max concurrency of a queue attribute. 148 * 149 * @param attr Queue attribute pointer. 150 * @return Returns the queue max concurrency. 151 * @since 12 152 */ 153 FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr); 154 155 /** 156 * @brief Sets the execution mode of a queue attribute. 157 * 158 * This interface specifies whether tasks in the queue are executed in coroutine mode or thread mode. 159 * By default, tasks are executed in coroutine mode. 160 * Set <b>mode</b> to <b>true</b> to enable thread-based execution. 161 * 162 * @param attr Queue attribute pointer. 163 * @param mode Indicates whether to enable thread-based execution mode. 164 * - <b>true</b>: Tasks are executed as native threads (thread mode). 165 * - <b>false</b>: Tasks are executed as coroutines (default). 166 * @since 20 167 */ 168 FFRT_C_API void ffrt_queue_attr_set_thread_mode(ffrt_queue_attr_t* attr, bool mode); 169 170 /** 171 * @brief Gets the execution mode of a queue attribute. 172 * 173 * This interface returns whether tasks in the queue are configured to run in thread-based execution mode (thread mode). 174 * 175 * @param attr Queue attribute pointer. 176 * @return Returns <b>true</b> if tasks are executed as native threads (thread mode); 177 * returns <b>false</b> if tasks are executed as coroutines (default). 178 * @since 20 179 */ 180 FFRT_C_API bool ffrt_queue_attr_get_thread_mode(const ffrt_queue_attr_t* attr); 181 182 /** 183 * @brief Creates a queue. 184 * 185 * @param type Indicates the queue type. 186 * @param name Indicates a pointer to the queue name. 187 * @param attr Indicates a pointer to the queue attribute. 188 * @return Returns a non-null queue handle if the queue is created; 189 returns a null pointer otherwise. 190 * @since 10 191 */ 192 FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr); 193 194 /** 195 * @brief Destroys a queue, the user needs to invoke this interface. 196 * 197 * @param queue Indicates a queue handle. 198 * @since 10 199 */ 200 FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue); 201 202 /** 203 * @brief Submits a task to a queue. 204 * 205 * @param queue Indicates a queue handle. 206 * @param f Indicates a pointer to the task executor. 207 * @param attr Indicates a pointer to the task attribute. 208 * @since 10 209 */ 210 FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 211 212 /** 213 * @brief Submits a task to the queue, and obtains a task handle. 214 * 215 * @param queue Indicates a queue handle. 216 * @param f Indicates a pointer to the task executor. 217 * @param attr Indicates a pointer to the task attribute. 218 * @return Returns a non-null task handle if the task is submitted; 219 returns a null pointer otherwise. 220 * @since 10 221 */ 222 FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h( 223 ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 224 225 /** 226 * @brief Submits a task to a queue, simplified from of the ffrt_queue_submit interface. 227 * 228 * This interface wraps the provided task function and its argument into a task wrapper designed 229 * for queue submission (ffrt_function_kind_queue). The task destroy callback (after_func), which 230 * would normally handle any post-execution cleanup, is automatically set to NULL in this wrapper, 231 * thus omitting any additional cleanup actions. The resulting task wrapper is then submitted to 232 * the specified queue via the ffrt_queue_submit interface. 233 * 234 * @param queue Indicates a queue handle. 235 * @param func Indicates a task function to be executed. 236 * @param arg Indicates a pointer to the argument or closure data that will be passed to the task function. 237 * @param attr Indicates a pointer to the task attribute. 238 * @see ffrt_queue_submit 239 * @since 20 240 */ 241 FFRT_C_API void ffrt_queue_submit_f(ffrt_queue_t queue, ffrt_function_t func, void* arg, const ffrt_task_attr_t* attr); 242 243 /** 244 * @brief Submits a task to a queue, and obtains a task handle, simplified from the ffrt_queue_submit_h interface. 245 * 246 * This interface wraps the provided task function and its argument into a task wrapper designed 247 * for queue submission (ffrt_function_kind_queue). The task destroy callback (after_func), which 248 * would normally handle any post-execution cleanup, is automatically set to NULL in this wrapper, 249 * thus omitting any additional cleanup actions. The resulting task wrapper is then submitted to 250 * the specified queue via the ffrt_queue_submit_h interface. 251 * 252 * @param queue Indicates a queue handle. 253 * @param func Indicates a task function to be executed. 254 * @param arg Indicates a pointer to the argument or closure data that will be passed to the task function. 255 * @param attr Indicates a pointer to the task attribute. 256 * @return Returns a non-null task handle if the task is submitted; 257 returns a null pointer otherwise. 258 * @see ffrt_queue_submit_h 259 * @since 20 260 */ 261 FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h_f( 262 ffrt_queue_t queue, ffrt_function_t func, void* arg, const ffrt_task_attr_t* attr); 263 264 /** 265 * @brief Waits until a task in the queue is complete. 266 * 267 * @param handle Indicates a task handle. 268 * @since 10 269 */ 270 FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle); 271 272 /** 273 * @brief Cancels a task in the queue. 274 * 275 * @param handle Indicates a task handle. 276 * @return Returns <b>0</b> if the task is canceled; 277 returns <b>-1</b> otherwise. 278 * @since 10 279 */ 280 FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle); 281 282 /** 283 * @brief Gets the application main thread queue. 284 * 285 * @return Returns application main thread queue. 286 * @since 12 287 */ 288 FFRT_C_API ffrt_queue_t ffrt_get_main_queue(void); 289 290 /** 291 * @brief Gets the application worker(ArkTs) thread queue. 292 * 293 * @return Returns application worker(ArkTs) thread queue. 294 * @deprecated since 18 295 * @since 12 296 */ 297 FFRT_C_API ffrt_queue_t ffrt_get_current_queue(void); 298 299 #endif // FFRT_API_C_QUEUE_H 300 /** @} */