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 { ffrt_queue_serial, ffrt_queue_max } ffrt_queue_type_t; 43 typedef void* ffrt_queue_t; 44 45 /** 46 * @brief Initializes the queue attribute. 47 * 48 * @param attr Indicates a pointer to the queue attribute. 49 * @return Returns <b>0</b> if the queue attribute is initialized; 50 returns <b>-1</b> otherwise. 51 * @since 10 52 * @version 1.0 53 */ 54 FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr); 55 56 /** 57 * @brief Destroys a queue attribute. 58 * 59 * @param attr Indicates a pointer to the queue attribute. 60 * @since 10 61 * @version 1.0 62 */ 63 FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr); 64 65 /** 66 * @brief Sets the QoS for a queue attribute. 67 * 68 * @param attr Indicates a pointer to the queue attribute. 69 * @param attr Indicates the QoS. 70 * @since 10 71 * @version 1.0 72 */ 73 FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos); 74 75 /** 76 * @brief Obtains the QoS of a queue attribute. 77 * 78 * @param attr Indicates a pointer to the queue attribute. 79 * @return Returns the QoS. 80 * @since 10 81 * @version 1.0 82 */ 83 FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr); 84 85 /** 86 * @brief Set the serial queue task execution timeout. 87 * 88 * @param attr Serial Queue Property Pointer. 89 * @param timeout_us Serial queue task execution timeout. 90 * @since 10 91 * @version 1.0 92 */ 93 FFRT_C_API void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t timeout_us); 94 95 /** 96 * @brief Get the serial queue task execution timeout. 97 * 98 * @param attr Serial Queue Property Pointer. 99 * @return Returns the serial queue task execution timeout. 100 * @since 10 101 * @version 1.0 102 */ 103 FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr); 104 105 /** 106 * @brief Set the serial queue timeout callback function. 107 * 108 * @param attr Serial Queue Property Pointer. 109 * @param f Serial queue timeout callback function. 110 * @since 10 111 * @version 1.0 112 */ 113 FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_function_header_t* f); 114 115 /** 116 * @brief Get the serial queue task timeout callback function. 117 * 118 * @param attr Serial Queue Property Pointer. 119 * @return Returns the serial queue task timeout callback function. 120 * @since 10 121 * @version 1.0 122 */ 123 FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr); 124 125 /** 126 * @brief Creates a queue. 127 * 128 * @param type Indicates the queue type. 129 * @param name Indicates a pointer to the queue name. 130 * @param attr Indicates a pointer to the queue attribute. 131 * @return Returns a non-null queue handle if the queue is created; 132 returns a null pointer otherwise. 133 * @since 10 134 * @version 1.0 135 */ 136 FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr); 137 138 /** 139 * @brief Destroys a queue. 140 * 141 * @param queue Indicates a queue handle. 142 * @since 10 143 * @version 1.0 144 */ 145 FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue); 146 147 /** 148 * @brief Submits a task to a queue. 149 * 150 * @param queue Indicates a queue handle. 151 * @param f Indicates a pointer to the task executor. 152 * @param attr Indicates a pointer to the task attribute. 153 * @since 10 154 * @version 1.0 155 */ 156 FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 157 158 /** 159 * @brief Submits a task to the queue, and obtains a task handle. 160 * 161 * @param queue Indicates a queue handle. 162 * @param f Indicates a pointer to the task executor. 163 * @param attr Indicates a pointer to the task attribute. 164 * @return Returns a non-null task handle if the task is submitted; 165 returns a null pointer otherwise. 166 * @since 10 167 * @version 1.0 168 */ 169 FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h( 170 ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 171 172 /** 173 * @brief Waits until a task in the queue is complete. 174 * 175 * @param handle Indicates a task handle. 176 * @since 10 177 * @version 1.0 178 */ 179 FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle); 180 181 /** 182 * @brief Cancels a task in the queue. 183 * 184 * @param handle Indicates a task handle. 185 * @return Returns <b>0</b> if the task is canceled; 186 returns <b>-1</b> otherwise. 187 * @since 10 188 * @version 1.0 189 */ 190 FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle); 191 192 #endif // FFRT_API_C_QUEUE_H