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 /* Allows users to submit tasks to the eventhandler through this type of queue. 24 (for example, submitting tasks to the main thread and JS Worker thread) */ 25 ffrt_queue_eventhandler_interactive = 3, 26 ffrt_queue_eventhandler_adapter = 4, 27 ffrt_queue_inner_max, 28 } ffrt_inner_queue_type_t; 29 30 typedef enum { 31 /* highest priority, should be distributed until the tasks in the queue are completed */ 32 ffrt_inner_queue_priority_vip = 0, 33 /* should be distributed at once if possible, handle time equals to send time, prior to high level */ 34 ffrt_inner_queue_priority_immediate, 35 /* high priority, sorted by handle time, prior to low level. */ 36 ffrt_inner_queue_priority_high, 37 /* low priority, sorted by handle time, prior to idle level. */ 38 ffrt_inner_queue_priority_low, 39 /* lowest priority, sorted by handle time, only distribute when there is no other level inside queue. */ 40 ffrt_inner_queue_priority_idle, 41 } ffrt_inner_queue_priority_t; 42 43 /** 44 * @brief Checks whether a task with the given name can be found in the queue. 45 * 46 * @note Task names are constructed by concatenating the business-provided name with the queue name and task ID. 47 * To avoid task name conflicts, the business must ensure name uniqueness and avoid conflicts with 48 * the concatenated queue name and task ID. 49 * 50 * @param queue Indicates a queue handle. 51 * @param name Indicates name to be searched for, regular expressions are supported. 52 * @return Returns whether the task is found. 53 */ 54 FFRT_C_API bool ffrt_queue_has_task(ffrt_queue_t queue, const char* name); 55 56 /** 57 * @brief Cancels all unexecuted tasks in the queue. 58 * 59 * @param queue Indicates a queue handle. 60 */ 61 FFRT_C_API void ffrt_queue_cancel_all(ffrt_queue_t queue); 62 63 /** 64 * @brief Cancels all unexecuted tasks and wait for running tasks in the queue. No new tasks will be accepted. 65 * 66 * @param queue Indicates a queue handle. 67 */ 68 FFRT_C_API void ffrt_queue_cancel_and_wait(ffrt_queue_t queue); 69 70 /** 71 * @brief Cancels a task with the given name in the queue. 72 * 73 * @param queue Indicates a queue handle. 74 * @param name Indicates name of the task to be canceled, regular expressions are supported. 75 * @return Returns <b>0</b> if the task is canceled; 76 returns <b>1</b> otherwise. 77 */ 78 FFRT_C_API int ffrt_queue_cancel_by_name(ffrt_queue_t queue, const char* name); 79 80 /** 81 * @brief Checks whether the queue is idle. 82 * 83 * @note Task names are constructed by concatenating the business-provided name with the queue name and task ID. 84 * To avoid task name conflicts, the business must ensure name uniqueness and avoid conflicts with 85 * the concatenated queue name and task ID. 86 * 87 * @param queue Indicates a queue handle. 88 * @return Returns whether the queue is idle. 89 */ 90 FFRT_C_API bool ffrt_queue_is_idle(ffrt_queue_t queue); 91 92 /** 93 * @brief Dumps queue information; 94 including current execution, historical execution, and remaining unexecuted task information, etc. 95 * 96 * @param queue Indicates a queue handle. 97 * @param tag Indicates tag prefix for dump information. 98 * @param buf Indicates produce output, write to the character string buf. 99 * @param len Indicates the size of the buffer (in bytes). 100 * @param history_info Indicates whether dump history information. 101 * @return Returns the number of characters printed (not including the terminating null byte '\0'); 102 returns -1 if an error occurred, pay special attention to returning -1 when truncation occurs. 103 */ 104 FFRT_C_API int ffrt_queue_dump(ffrt_queue_t queue, const char* tag, char* buf, uint32_t len, bool history_info); 105 106 /** 107 * @brief Dumps queue task count with specified priority. 108 * 109 * @param queue Indicates a queue handle. 110 * @param priority Indicates the execute priority of queue task. 111 * @return Returns the count of tasks; 112 returns -1 if an error occurred. 113 */ 114 FFRT_C_API int ffrt_queue_size_dump(ffrt_queue_t queue, ffrt_inner_queue_priority_t priority); 115 116 /** 117 * @brief Binds an eventhandler object to the queue. 118 * 119 * @param queue Indicates a queue handle. 120 * @param eventhandler Indicates an eventhandler pointer. 121 */ 122 FFRT_C_API void ffrt_queue_set_eventhandler(ffrt_queue_t queue, void* eventhandler); 123 124 /** 125 * @brief Obtains the handler bound to the queue that is being executed on the current worker. 126 * 127 * @return Returns a non-null eventhandler pointer; 128 returns a null pointer if the current task is not bound to an eventhandler. 129 */ 130 FFRT_C_API void* ffrt_get_current_queue_eventhandler(void); 131 132 /** 133 * @brief Wait until all tasks in the queue are complete based on the time when this interface is invoked. 134 * 135 * This API is valid only for concurrent queue. 136 * This interface cannot be invoked by multiple threads at the same time. 137 * 138 * @param queue Indicates a queue handle. 139 * @return Returns 0 if waiting successful; 140 returns 1 if another existing thread is invoking the interface; 141 returns -1 if queue type is unsupported. 142 */ 143 FFRT_C_API int ffrt_concurrent_queue_wait_all(ffrt_queue_t queue); 144 145 #endif