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 Checks whether a task with the given name can be found in the queue. 43 * 44 * @param queue Indicates a queue handle. 45 * @param name Indicates name to be searched for, regular expressions are supported. 46 * @return Returns whether the task is found. 47 * @version 1.0 48 */ 49 FFRT_C_API bool ffrt_queue_has_task(ffrt_queue_t queue, const char* name); 50 51 /** 52 * @brief Cancels all unexecuted tasks in the queue. 53 * 54 * @param queue Indicates a queue handle. 55 * @version 1.0 56 */ 57 FFRT_C_API void ffrt_queue_cancel_all(ffrt_queue_t queue); 58 59 /** 60 * @brief Cancels all unexecuted tasks and wait for running tasks in the queue. No new tasks will be accepted. 61 * 62 * @param queue Indicates a queue handle. 63 * @version 1.0 64 */ 65 FFRT_C_API void ffrt_queue_cancel_and_wait(ffrt_queue_t queue); 66 67 /** 68 * @brief Cancels a task with the given name in the queue. 69 * 70 * @param queue Indicates a queue handle. 71 * @param name Indicates name of the task to be canceled, regular expressions are supported. 72 * @return Returns <b>0</b> if the task is canceled; 73 returns <b>1</b> otherwise. 74 * @version 1.0 75 */ 76 FFRT_C_API int ffrt_queue_cancel_by_name(ffrt_queue_t queue, const char* name); 77 78 /** 79 * @brief Checks whether the queue is idle. 80 * 81 * @param queue Indicates a queue handle. 82 * @return Returns whether the queue is idle. 83 * @version 1.0 84 */ 85 FFRT_C_API bool ffrt_queue_is_idle(ffrt_queue_t queue); 86 87 /** 88 * @brief Dumps queue information; 89 including current execution, historical execution, and remaining unexecuted task information, etc. 90 * 91 * @param queue Indicates a queue handle. 92 * @param tag Indicates tag prefix for dump information. 93 * @param buf Indicates produce output, write to the character string buf. 94 * @param len Indicates the size of the buffer (in bytes). 95 * @param history_info Indicates whether dump history information. 96 * @return Returns the number of characters printed (not including the terminating null byte '\0'); 97 returns -1 if an error occurred, pay special attention to returning -1 when truncation occurs. 98 * @version 1.0 99 */ 100 FFRT_C_API int ffrt_queue_dump(ffrt_queue_t queue, const char* tag, char* buf, uint32_t len, bool history_info); 101 102 /** 103 * @brief Dumps queue task count with specified priority. 104 * 105 * @param queue Indicates a queue handle. 106 * @param priority Indicates the execute priority of queue task. 107 * @return Returns the count of tasks; 108 returns -1 if an error occurred. 109 * @version 1.0 110 */ 111 FFRT_C_API int ffrt_queue_size_dump(ffrt_queue_t queue, ffrt_inner_queue_priority_t priority); 112 113 /** 114 * @brief Binds an eventhandler object to the queue. 115 * 116 * @param queue Indicates a queue handle. 117 * @param eventhandler Indicates an eventhandler pointer. 118 * @version 1.0 119 */ 120 FFRT_C_API void ffrt_queue_set_eventhandler(ffrt_queue_t queue, void* eventhandler); 121 122 /** 123 * @brief Obtains the handler bound to the queue that is being executed on the current worker. 124 * 125 * @return Returns a non-null eventhandler pointer; 126 returns a null pointer if the current task is not bound to an eventhandler. 127 * @version 1.0 128 */ 129 FFRT_C_API void* ffrt_get_current_queue_eventhandler(); 130 131 #endif