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