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 #ifndef FFRT_INNER_API_C_QUEUE_EXT_H 17 #define FFRT_INNER_API_C_QUEUE_EXT_H 18 19 #include <stdbool.h> 20 #include "c/queue.h" 21 22 typedef enum { 23 ffrt_queue_eventhandler_interactive = 3, 24 ffrt_queue_eventhandler_adapter = 4, 25 ffrt_queue_inner_max, 26 } ffrt_inner_queue_type_t; 27 28 typedef enum { 29 /* highest priority, should be distributed until the tasks in the queue are completed */ 30 ffrt_inner_queue_priority_vip = 0, 31 /* should be distributed at once if possible, handle time equals to send time, prior to high level */ 32 ffrt_inner_queue_priority_immediate, 33 /* high priority, sorted by handle time, prior to low level. */ 34 ffrt_inner_queue_priority_high, 35 /* low priority, sorted by handle time, prior to idle level. */ 36 ffrt_inner_queue_priority_low, 37 /* lowest priority, sorted by handle time, only distribute when there is no other level inside queue. */ 38 ffrt_inner_queue_priority_idle, 39 } ffrt_inner_queue_priority_t; 40 41 /** 42 * @brief Submits a task to a queue, for tasks with the same delay, insert the header. 43 * 44 * @param queue Indicates a queue handle. 45 * @param f Indicates a pointer to the task executor. 46 * @param attr Indicates a pointer to the task attribute. 47 * @version 1.0 48 */ 49 FFRT_C_API void ffrt_queue_submit_head(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 50 51 /** 52 * @brief Submits a task to the queue, and obtains a task handle, for tasks with the same delay, insert the header. 53 * 54 * @param queue Indicates a queue handle. 55 * @param f Indicates a pointer to the task executor. 56 * @param attr Indicates a pointer to the task attribute. 57 * @return Returns a non-null task handle if the task is submitted; 58 returns a null pointer otherwise. 59 * @version 1.0 60 */ 61 FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_head_h( 62 ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr); 63 64 /** 65 * @brief Checks whether a task with the given name can be found in the queue. 66 * 67 * @param queue Indicates a queue handle. 68 * @param name Indicates name to be searched for, regular expressions are supported. 69 * @return Returns whether the task is found. 70 * @version 1.0 71 */ 72 FFRT_C_API bool ffrt_queue_has_task(ffrt_queue_t queue, const char* name); 73 74 /** 75 * @brief Cancels all unexecuted tasks in the queue. 76 * 77 * @param queue Indicates a queue handle. 78 * @version 1.0 79 */ 80 FFRT_C_API void ffrt_queue_cancel_all(ffrt_queue_t queue); 81 82 /** 83 * @brief Cancels all unexecuted tasks and wait for running tasks in the queue. 84 * 85 * @param queue Indicates a queue handle. 86 * @version 1.0 87 */ 88 FFRT_C_API void ffrt_queue_cancel_and_wait(ffrt_queue_t queue); 89 90 /** 91 * @brief Cancels a task with the given name in the queue. 92 * 93 * @param queue Indicates a queue handle. 94 * @param name Indicates name of the task to be canceled, regular expressions are supported. 95 * @return Returns <b>0</b> if the task is canceled; 96 returns <b>1</b> otherwise. 97 * @version 1.0 98 */ 99 FFRT_C_API int ffrt_queue_cancel_by_name(ffrt_queue_t queue, const char* name); 100 101 /** 102 * @brief Checks whether the queue is idle. 103 * 104 * @param queue Indicates a queue handle. 105 * @return Returns whether the queue is idle. 106 * @version 1.0 107 */ 108 FFRT_C_API bool ffrt_queue_is_idle(ffrt_queue_t queue); 109 110 /** 111 * @brief Dumps queue information; 112 including current execution, historical execution, and remaining unexecuted task information, etc. 113 * 114 * @param queue Indicates a queue handle. 115 * @param tag Indicates tag prefix for dump information. 116 * @param buf Indicates produce output, write to the character string buf. 117 * @param len Indicates the size of the buffer (in bytes). 118 * @param history_info Indicates whether dump history information. 119 * @return Returns the number of characters printed (not including the terminating null byte '\0'); 120 returns -1 if an error occurred, pay special attention to returning -1 when truncation occurs. 121 * @version 1.0 122 */ 123 FFRT_C_API int ffrt_queue_dump(ffrt_queue_t queue, const char* tag, char* buf, uint32_t len, bool history_info); 124 125 /** 126 * @brief Dumps queue task count with specified priority. 127 * 128 * @param queue Indicates a queue handle. 129 * @param priority Indicates the execute priority of queue task. 130 * @return Returns the count of tasks; 131 returns -1 if an error occurred. 132 * @version 1.0 133 */ 134 FFRT_C_API int ffrt_queue_size_dump(ffrt_queue_t queue, ffrt_inner_queue_priority_t priority); 135 136 /** 137 * @brief Binds an eventhandler object to the queue. 138 * 139 * @param queue Indicates a queue handle. 140 * @param eventhandler Indicates an eventhandler pointer. 141 * @version 1.0 142 */ 143 FFRT_C_API void ffrt_queue_set_eventhandler(ffrt_queue_t queue, void* eventhandler); 144 145 /** 146 * @brief Obtains the handler bound to the queue that is being executed on the current worker. 147 * 148 * @return Returns a non-null eventhandler pointer; 149 returns a null pointer if the current task is not bound to an eventhandler. 150 * @version 1.0 151 */ 152 FFRT_C_API void* ffrt_get_current_queue_eventhandler(); 153 154 #endif