1 /* 2 * Copyright (c) 2024 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 HiCollie 18 * @{ 19 * 20 * @brief Provides the ability to detect thread stuck or jank of your own business thread 21 * pls note it should not be the same as main thread. 22 * 23 * You can use it in these two scenario: 24 * (1)The Business thread stuck for 6 seconds; 25 * (2)The Business thread jank for a short time，usually it is less than one second. 26 * 27 * @since 12 28 */ 29 30 /** 31 * @file hicollie.h 32 * 33 * @brief Defines the interface of the HiCollie module. 34 * 35 * @library libohhicollie.so 36 * @kit PerformanceAnalysisKit 37 * @syscap SystemCapability.HiviewDFX.HiCollie 38 * @since 12 39 */ 40 41 #ifndef HIVIEWDFX_HICOLLIE_H 42 #define HIVIEWDFX_HICOLLIE_H 43 44 #include <time.h> 45 #include <stdint.h> 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif // __cplusplus 50 51 /** 52 * @brief Defines error code 53 * 54 * @since 12 55 */ 56 typedef enum HiCollie_ErrorCode { 57 /** Success */ 58 HICOLLIE_SUCCESS = 0, 59 /** Invalid argument */ 60 HICOLLIE_INVALID_ARGUMENT = 401, 61 /** Wrong thread context */ 62 HICOLLIE_WRONG_THREAD_CONTEXT = 29800001, 63 /** Remote call failed */ 64 HICOLLIE_REMOTE_FAILED = 29800002, 65 /** 66 * Invalid timer name 67 * @since 18 68 */ 69 HICOLLIE_INVALID_TIMER_NAME = 29800003, 70 /** 71 * Invalid timeout value 72 * @since 18 73 */ 74 HICOLLIE_INVALID_TIMEOUT_VALUE = 29800004, 75 /** 76 * Wrong process context 77 * @since 18 78 */ 79 HICOLLIE_WRONG_PROCESS_CONTEXT = 29800005, 80 /** 81 * The pointer used to save returned timer id should not be NULL 82 * @since 18 83 */ 84 HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM = 29800006, 85 } HiCollie_ErrorCode; 86 87 /** 88 * @brief In stuck scenario, you need to implement this function to detect whether your business thread is stuck. 89 * HiCollie will call this function every 3 seconds in an independent thread. 90 * A possible implementation of this function is to send a message to your business thread. 91 * After the business thread receives it, it will set a flag, 92 * by checking the flag you can know whether the business thread is stuck or not. 93 * 94 * @since 12 95 */ 96 typedef void (*OH_HiCollie_Task)(void); 97 98 /** 99 * @brief In jank scenario, you need to insert two stub functions before and after 100 * each event processing of your business thread. 101 * By checking these two function executing timestamp, HiCollie will know cosuming time for every event. 102 * If it exceeds the preset threshold, a jank event will be reported. 103 * This is the stub function inserted before each event processing. 104 * 105 * @param eventName Business thread processing event name. 106 * @since 12 107 */ 108 typedef void (*OH_HiCollie_BeginFunc)(const char* eventName); 109 110 /** 111 * @brief In jank scenario, you need to insert two stub functions before and after 112 * each event processing of your business thread. 113 * By checking these two function executing timestamp, HiCollie will know cosuming time for every event. 114 * If it exceeds the preset threshold, a jank event will be reported. 115 * This is the stub function inserted after each event processing. 116 * 117 * @param eventName Business thread processing event name. 118 * @since 12 119 */ 120 typedef void (*OH_HiCollie_EndFunc)(const char* eventName); 121 122 /** 123 * @brief Parameters used for jank detection. 124 * Pls note these parameters is not valid for API 12, it is only used for future extention. 125 * 126 * @since 12 127 */ 128 typedef struct HiCollie_DetectionParam { 129 /** In jank scenario, it's the theshold exceed which sample stack will be collected. */ 130 int sampleStackTriggerTime; 131 /** extended parameter for future use. */ 132 int reserved; 133 } HiCollie_DetectionParam; 134 135 /** 136 * @brief Set up periodic tasks for stuck detection. 137 * 138 * @param task Periodic task executed every 3 seconds. 139 * @return {@link HICOLLIE_SUCCESS} 0 - Success. 140 * {@link HICOLLIE_WRONG_THREAD_CONTEXT} 29800001 - Wrong thread context. 141 * The function can not be called from main thread. 142 * @since 12 143 */ 144 HiCollie_ErrorCode OH_HiCollie_Init_StuckDetection(OH_HiCollie_Task task); 145 146 /** 147 * @brief Set up periodic tasks for stuck detection. 148 * 149 * @param task Periodic task executed every stuckTimeout seconds. 150 * @param stuckTimeout Stuck detection interval. 151 * @return {@link HICOLLIE_SUCCESS} 0 - Success. 152 * {@link HICOLLIE_INVALID_ARGUMENT} 401 - stuckTimeout is less than 3 seconds and greater than 15 seconds. 153 * {@link HICOLLIE_WRONG_THREAD_CONTEXT} 29800001 - Wrong thread context 154 * The function can not be called from main thread. 155 * @since 18 156 */ 157 HiCollie_ErrorCode OH_HiCollie_Init_StuckDetectionWithTimeout(OH_HiCollie_Task task, uint32_t stuckTimeout); 158 159 /** 160 * @brief Set up stub functions for jank detection. 161 * 162 * @param beginFunc The stub function before each event processing. 163 * @param endFunc The stub function after each event processing. 164 * @param param The parameter for jank detection setting. 165 * @return {@link HICOLLIE_SUCCESS} 0 - Success. 166 * {@link HICOLLIE_INVALID_ARGUMENT} 401 - beginFunc and endFunc 167 * must both have values or be empty, otherwise the value will be returned. 168 * {@link HICOLLIE_WRONG_THREAD_CONTEXT} 29800001 - Wrong thread context. 169 * The function can not be called from main thread. 170 * @since 12 171 */ 172 HiCollie_ErrorCode OH_HiCollie_Init_JankDetection(OH_HiCollie_BeginFunc* beginFunc, 173 OH_HiCollie_EndFunc* endFunc, HiCollie_DetectionParam param); 174 175 /** 176 * @brief Report a stuck event. 177 * 178 * @param isSixSecond boolean pointer. 179 * The value of the boolean pointer.True if it is stuck for 6 seconds. False if it is stuck for 3 seconds. 180 * @return {@link HICOLLIE_SUCCESS} 0 - Success. 181 * {@link HICOLLIE_INVALID_ARGUMENT} 401 - if isSixSecond is nullptr. 182 * {@link HICOLLIE_WRONG_THREAD_CONTEXT} 29800001 - Wrong thread context. 183 * The function can only be called from hicollie internal monitor thread 184 * where {@link OH_HiCollie_Task} run on. 185 * {@link HICOLLIE_REMOTE_FAILED} 29800002 - Remote call failed. 186 * @since 12 187 */ 188 HiCollie_ErrorCode OH_HiCollie_Report(bool* isSixSecond); 189 190 /** 191 * @brief When user call {@link OH_HiCollie_SetTimer} and do not call {@link OH_HiCollie_CancelTimer} 192 * in specific time, the callback function will be executed. 193 * 194 * @since 18 195 */ 196 typedef void (*OH_HiCollie_Callback)(void*); 197 198 /** 199 * @brief Defines the actions that will be executed when timeout happens. 200 * 201 * @since 18 202 */ 203 typedef enum HiCollie_Flag { 204 /** Default action is generate log file and do recovery */ 205 HICOLLIE_FLAG_DEFAULT = (~0), 206 /* Do nothing except call the callback function */ 207 HICOLLIE_FLAG_NOOP = (0), 208 /* Generate log file */ 209 HICOLLIE_FLAG_LOG = (1 << 0), 210 /* Do recovery by call the exit syscall */ 211 HICOLLIE_FLAG_RECOVERY = (1 << 1) 212 } HiCollie_Flag; 213 214 /** 215 * @brief Defines the input parameter for {@link OH_HiCollie_SetTimer} 216 * 217 * @since 18 218 */ 219 typedef struct HiCollie_SetTimerParam { 220 /** The timer name */ 221 const char *name; 222 /** The timeout threshold in seconds */ 223 unsigned int timeout; 224 /** The callback function which is excuted when timeout happen */ 225 OH_HiCollie_Callback func; 226 /** The callback function's parameter */ 227 void *arg; 228 /** The action when timeout happens. Please refer to {@link HiCollie_Flag} */ 229 HiCollie_Flag flag; 230 } HiCollie_SetTimerParam; 231 232 /** 233 * @brief This function should be used before calling a time-consuming function 234 * 235 * @param param Define the input parameter. 236 * @param id The pointer used to save returned timer id, it should not be NULL. 237 * @return {@link HICOLLIE_SUCCESS} 0 - Success. 238 * {@link HICOLLIE_INVALID_TIMER_NAME} 29800003 - Invalid timer name, it should not be NULL or empty string. 239 * {@link HICOLLIE_INVALID_TIMEOUT_VALUE} 29800004 - Invalid timeout value. 240 * {@link HICOLLIE_WRONG_PROCESS_CONTEXT} 29800005 - Invalid process context, you should not call it 241 * from appspawn and native process. 242 * {@link HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM} 29800006 - The pointer used to save returned timer id 243 * should not be NULL. 244 * @since 18 245 */ 246 HiCollie_ErrorCode OH_HiCollie_SetTimer(HiCollie_SetTimerParam param, int *id); 247 248 /** 249 * @brief Cancel the timer right after calling the time-consuming function. 250 * 251 * @param id The timer id that is return from {@link OH_HiCollie_SetTimer}. 252 * @since 18 253 */ 254 void OH_HiCollie_CancelTimer(int id); 255 256 #ifdef __cplusplus 257 } 258 #endif 259 /** @} */ 260 261 #endif // HIVIEWDFX_HICOLLIE_H 262