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