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 * @version 1.0 35 */ 36 37 #ifndef FFRT_API_C_QUEUE_H 38 #define FFRT_API_C_QUEUE_H 39 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 * @version 1.0 71 */ 72 FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr); 73 74 /** 75 * @brief Destroys a queue attribute, the user needs to invoke this interface. 76 * 77 * @param attr Indicates a pointer to the queue attribute. 78 * @since 10 79 * @version 1.0 80 */ 81 FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr); 82 83 /** 84 * @brief Sets the QoS for a queue attribute. 85 * 86 * @param attr Indicates a pointer to the queue attribute. 87 * @param qos Indicates the QoS. 88 * @since 10 89 * @version 1.0 90 */ 91 FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos); 92 93 /** 94 * @brief Gets the QoS of a queue attribute. 95 * 96 * @param attr Indicates a pointer to the queue attribute. 97 * @return Returns the QoS. 98 * @since 10 99 * @version 1.0 100 */ 101 FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr); 102 103 /** 104 * @brief Sets the execution timeout of a serial queue attribute. 105 * 106 * @param attr Serial queue attribute pointer. 107 * @param timeout_us Serial queue task execution timeout. 108 * @since 10 109 * @version 1.0 110 */ 111 FFRT_C_API void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t timeout_us); 112 113 /** 114 * @brief Gets the execution timeout of a serial queue attribute. 115 * 116 * @param attr Serial queue attribute pointer. 117 * @return Returns the serial queue task execution timeout. 118 * @since 10 119 * @version 1.0 120 */ 121 FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr); 122 123 /** 124 * @brief Sets the timeout callback function of a serial queue attribute. 125 * 126 * @param attr Serial queue attribute pointer. 127 * @param f Serial queue timeout callback function. 128 * @since 10 129 * @version 1.0 130 */ 131 FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_function_header_t* f); 132 133 /** 134 * @brief Gets the timeout callback function of a serial queue attribute. 135 * 136 * @param attr Serial queue attribute pointer. 137 * @return Returns the serial queue task timeout callback function. 138 * @since 10 139 * @version 1.0 140 */ 141 FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr); 142 143 /** 144 * @brief Sets the queue max concurrency of a queue attribute. 145 * 146 * @param attr Queue attribute pointer. 147 * @param max_concurrency queue max_concurrency. 148 * @since 12 149 * @version 1.0 150 */ 151 FFRT_C_API void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, const int max_concurrency); 152 153 /** 154 * @brief Gets the queue max concurrency of a queue attribute. 155 * 156 * @param attr Queue attribute pointer. 157 * @return Returns the queue max concurrency. 158 * @since 12 159 * @version 1.0 160 */ 161 FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr); 162 163 /** 164 * @brief Creates a queue. 165 * 166 * @param type Indicates the queue type. 167 * @param name Indicates a pointer to the queue name. 168 * @param attr Indicates a pointer to the queue attribute. 169 * @return Returns a non-null queue handle if the queue is created; 170 returns a null pointer otherwise. 171 * @since 10 172 * @version 1.0 173 */ 174 FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr); 175 176 /** 177 * @brief Destroys a queue, the user needs to invoke this interface. 178 * 179 * @param queue Indicates a queue handle. 180 * @since 10 181 * @version 1.0 182 */ 183 FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue); 184 185 /** 186 * @brief Submits a task to a queue. 187 * 188 * @param queue Indicates a queue handle. 189 * @param f Indicates a pointer to the task executor. 190 * @param attr Indicates a pointer to the task attribute. 191 * @since 10 192 * @version 1.0 193 */ 194 FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 195 196 /** 197 * @brief Submits a task to the queue, and obtains a task handle. 198 * 199 * @param queue Indicates a queue handle. 200 * @param f Indicates a pointer to the task executor. 201 * @param attr Indicates a pointer to the task attribute. 202 * @return Returns a non-null task handle if the task is submitted; 203 returns a null pointer otherwise. 204 * @since 10 205 * @version 1.0 206 */ 207 FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h( 208 ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 209 210 /** 211 * @brief Waits until a task in the queue is complete. 212 * 213 * @param handle Indicates a task handle. 214 * @since 10 215 * @version 1.0 216 */ 217 FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle); 218 219 /** 220 * @brief Cancels a task in the queue. 221 * 222 * @param handle Indicates a task handle. 223 * @return Returns <b>0</b> if the task is canceled; 224 returns <b>-1</b> otherwise. 225 * @since 10 226 * @version 1.0 227 */ 228 FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle); 229 230 /** 231 * @brief Gets the application main thread queue. 232 * 233 * @return Returns application main thread queue. 234 * @since 12 235 * @version 1.0 236 */ 237 FFRT_C_API ffrt_queue_t ffrt_get_main_queue(void); 238 239 /** 240 * @brief Gets the application worker(ArkTs) thread queue. 241 * 242 * @return Returns application worker(ArkTs) thread queue. 243 * @deprecated since 15 244 * @since 12 245 * @version 1.0 246 */ 247 FFRT_C_API ffrt_queue_t ffrt_get_current_queue(void); 248 249 /** 250 * @brief Gets the task count of a queue. 251 * 252 * @param queue Indicates a queue handle. 253 * @return Returns the queue task count. 254 * @since 10 255 * @version 1.0 256 */ 257 FFRT_C_API uint64_t ffrt_queue_get_task_cnt(ffrt_queue_t queue); 258 259 /** 260 * @brief Submits a task to a queue, for tasks with the same delay, insert the header. 261 * 262 * @param queue Indicates a queue handle. 263 * @param f Indicates a pointer to the task executor. 264 * @param attr Indicates a pointer to the task attribute. 265 * @version 1.0 266 */ 267 FFRT_C_API void ffrt_queue_submit_head(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 268 269 /** 270 * @brief Submits a task to the queue, and obtains a task handle, for tasks with the same delay, insert the header. 271 * 272 * @param queue Indicates a queue handle. 273 * @param f Indicates a pointer to the task executor. 274 * @param attr Indicates a pointer to the task attribute. 275 * @return Returns a non-null task handle if the task is submitted; 276 returns a null pointer otherwise. 277 * @version 1.0 278 */ 279 FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_head_h( 280 ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 281 282 #endif // FFRT_API_C_QUEUE_H 283 /** @} */