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 * @param attr Serial queue attribute pointer. 122 * @param f Serial queue timeout callback function. 123 * @since 10 124 */ 125 FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_function_header_t* f); 126 127 /** 128 * @brief Gets the timeout callback function of a serial queue attribute. 129 * 130 * @param attr Serial queue attribute pointer. 131 * @return Returns the serial queue task timeout callback function. 132 * @since 10 133 */ 134 FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr); 135 136 /** 137 * @brief Sets the queue max concurrency of a queue attribute. 138 * 139 * @param attr Queue attribute pointer. 140 * @param max_concurrency queue max_concurrency. 141 * @since 12 142 */ 143 FFRT_C_API void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, const int max_concurrency); 144 145 /** 146 * @brief Gets the queue max concurrency of a queue attribute. 147 * 148 * @param attr Queue attribute pointer. 149 * @return Returns the queue max concurrency. 150 * @since 12 151 */ 152 FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr); 153 154 /** 155 * @brief Creates a queue. 156 * 157 * @param type Indicates the queue type. 158 * @param name Indicates a pointer to the queue name. 159 * @param attr Indicates a pointer to the queue attribute. 160 * @return Returns a non-null queue handle if the queue is created; 161 returns a null pointer otherwise. 162 * @since 10 163 */ 164 FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr); 165 166 /** 167 * @brief Destroys a queue, the user needs to invoke this interface. 168 * 169 * @param queue Indicates a queue handle. 170 * @since 10 171 */ 172 FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue); 173 174 /** 175 * @brief Submits a task to a queue. 176 * 177 * @param queue Indicates a queue handle. 178 * @param f Indicates a pointer to the task executor. 179 * @param attr Indicates a pointer to the task attribute. 180 * @since 10 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 */ 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 */ 203 FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle); 204 205 /** 206 * @brief Cancels a task in the queue. 207 * 208 * @param handle Indicates a task handle. 209 * @return Returns <b>0</b> if the task is canceled; 210 returns <b>-1</b> otherwise. 211 * @since 10 212 */ 213 FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle); 214 215 /** 216 * @brief Gets the application main thread queue. 217 * 218 * @return Returns application main thread queue. 219 * @since 12 220 */ 221 FFRT_C_API ffrt_queue_t ffrt_get_main_queue(void); 222 223 /** 224 * @brief Gets the application worker(ArkTs) thread queue. 225 * 226 * @return Returns application worker(ArkTs) thread queue. 227 * @deprecated since 18 228 * @since 12 229 */ 230 FFRT_C_API ffrt_queue_t ffrt_get_current_queue(void); 231 232 #endif // FFRT_API_C_QUEUE_H 233 /** @} */