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 ffrt provides APIs. 21 * 22 * 23 * @syscap SystemCapability.Resourceschedule.Ffrt.Core 24 * 25 * @since 10 26 */ 27 28 /** 29 * @file queue.h 30 * 31 * @brief Declares the queue interfaces in C. 32 * 33 * @syscap SystemCapability.Resourceschedule.Ffrt.Core 34 * @since 10 35 * @version 1.0 36 */ 37 #ifndef FFRT_API_C_QUEUE_H 38 #define FFRT_API_C_QUEUE_H 39 40 #include "type_def.h" 41 42 typedef enum { 43 ffrt_queue_serial, 44 ffrt_queue_concurrent, 45 ffrt_queue_max 46 } ffrt_queue_type_t; 47 48 typedef void* ffrt_queue_t; 49 50 /** 51 * @brief Initializes the queue attribute. 52 * 53 * @param attr Indicates a pointer to the queue attribute. 54 * @return Returns <b>0</b> if the queue attribute is initialized; 55 returns <b>-1</b> otherwise. 56 * @since 10 57 * @version 1.0 58 */ 59 FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr); 60 61 /** 62 * @brief Destroys a queue attribute. 63 * 64 * @param attr Indicates a pointer to the queue attribute. 65 * @since 10 66 * @version 1.0 67 */ 68 FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr); 69 70 /** 71 * @brief Sets the QoS for a queue attribute. 72 * 73 * @param attr Indicates a pointer to the queue attribute. 74 * @param attr Indicates the QoS. 75 * @since 10 76 * @version 1.0 77 */ 78 FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos); 79 80 /** 81 * @brief Obtains the QoS of a queue attribute. 82 * 83 * @param attr Indicates a pointer to the queue attribute. 84 * @return Returns the QoS. 85 * @since 10 86 * @version 1.0 87 */ 88 FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr); 89 90 /** 91 * @brief Set the serial queue task execution timeout. 92 * 93 * @param attr Serial Queue Property Pointer. 94 * @param timeout_us Serial queue task execution timeout. 95 * @since 10 96 * @version 1.0 97 */ 98 FFRT_C_API void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t timeout_us); 99 100 /** 101 * @brief Get the serial queue task execution timeout. 102 * 103 * @param attr Serial Queue Property Pointer. 104 * @return Returns the serial queue task execution timeout. 105 * @since 10 106 * @version 1.0 107 */ 108 FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr); 109 110 /** 111 * @brief Set the serial queue timeout callback function. 112 * 113 * @param attr Serial Queue Property Pointer. 114 * @param f Serial queue timeout callback function. 115 * @since 10 116 * @version 1.0 117 */ 118 FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_function_header_t* f); 119 120 /** 121 * @brief Get the serial queue task timeout callback function. 122 * 123 * @param attr Serial Queue Property Pointer. 124 * @return Returns the serial queue task timeout callback function. 125 * @since 10 126 * @version 1.0 127 */ 128 FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr); 129 130 /** 131 * @brief Set the queue max concurrency. 132 * 133 * @param attr Queue Property Pointer. 134 * @param max_concurrency queue max_concurrency. 135 * @since 12 136 * @version 1.0 137 */ 138 FFRT_C_API void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, const int max_concurrency); 139 140 /** 141 * @brief Get the queue max concurrency. 142 * 143 * @param attr Queue Property Pointer. 144 * @return Returns the queue max concurrency. 145 * @since 12 146 * @version 1.0 147 */ 148 FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr); 149 150 /** 151 * @brief Creates a queue. 152 * 153 * @param type Indicates the queue type. 154 * @param name Indicates a pointer to the queue name. 155 * @param attr Indicates a pointer to the queue attribute. 156 * @return Returns a non-null queue handle if the queue is created; 157 returns a null pointer otherwise. 158 * @since 10 159 * @version 1.0 160 */ 161 FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr); 162 163 /** 164 * @brief Destroys a queue. 165 * 166 * @param queue Indicates a queue handle. 167 * @since 10 168 * @version 1.0 169 */ 170 FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue); 171 172 /** 173 * @brief Submits a task to a queue. 174 * 175 * @param queue Indicates a queue handle. 176 * @param f Indicates a pointer to the task executor. 177 * @param attr Indicates a pointer to the task attribute. 178 * @since 10 179 * @version 1.0 180 */ 181 FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 182 183 /** 184 * @brief Submits a task to the queue, and obtains a task handle. 185 * 186 * @param queue Indicates a queue handle. 187 * @param f Indicates a pointer to the task executor. 188 * @param attr Indicates a pointer to the task attribute. 189 * @return Returns a non-null task handle if the task is submitted; 190 returns a null pointer otherwise. 191 * @since 10 192 * @version 1.0 193 */ 194 FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h( 195 ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 196 197 /** 198 * @brief Waits until a task in the queue is complete. 199 * 200 * @param handle Indicates a task handle. 201 * @since 10 202 * @version 1.0 203 */ 204 FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle); 205 206 /** 207 * @brief Cancels a task in the queue. 208 * 209 * @param handle Indicates a task handle. 210 * @return Returns <b>0</b> if the task is canceled; 211 returns <b>-1</b> otherwise. 212 * @since 10 213 * @version 1.0 214 */ 215 FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle); 216 217 /** 218 * @brief Get application main thread queue. 219 * 220 * @return Returns application main thread queue. 221 * @since 12 222 * @version 1.0 223 */ 224 FFRT_C_API ffrt_queue_t ffrt_get_main_queue(); 225 226 /** 227 * @brief Get application worker(ArkTs) thread queue. 228 * 229 * @return Returns application worker(ArkTs) thread queue. 230 * @since 12 231 * @version 1.0 232 */ 233 FFRT_C_API ffrt_queue_t ffrt_get_current_queue(); 234 235 /** 236 * @brief Get queue task count. 237 * 238 * @param queue Indicates a queue handle. 239 * @return Returns the queue task count. 240 * @since 10 241 * @version 1.0 242 */ 243 FFRT_C_API uint64_t ffrt_queue_get_task_cnt(ffrt_queue_t queue); 244 245 /** 246 * @brief Submits a task to a queue, for tasks with the same delay, insert the header. 247 * 248 * @param queue Indicates a queue handle. 249 * @param f Indicates a pointer to the task executor. 250 * @param attr Indicates a pointer to the task attribute. 251 * @version 1.0 252 */ 253 FFRT_C_API void ffrt_queue_submit_head(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 254 255 /** 256 * @brief Submits a task to the queue, and obtains a task handle, for tasks with the same delay, insert the header. 257 * 258 * @param queue Indicates a queue handle. 259 * @param f Indicates a pointer to the task executor. 260 * @param attr Indicates a pointer to the task attribute. 261 * @return Returns a non-null task handle if the task is submitted; 262 returns a null pointer otherwise. 263 * @version 1.0 264 */ 265 FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_head_h( 266 ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 267 268 #endif // FFRT_API_C_QUEUE_H