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