1# hicollie.h 2 3## Overview 4 5HiCollie provides APIs for checking service thread stuck and jank events and reporting stuck events. 6 7**File to include**: <hicollie/hicollie.h> 8 9**Library**: libohhicollie.so 10 11**System capability**: SystemCapability.HiviewDFX.HiCollie 12 13**Since**: 12 14 15**Related module**: [HiCollie](capi-hicollie.md) 16 17## Summary 18 19### Structs 20 21| Name| typedef Keyword| Description| 22| -- | -- | -- | 23| [HiCollie_DetectionParam](capi-hicollie-hicollie-detectionparam.md) | HiCollie_DetectionParam | Defines the parameters of the jank event detection. Note that this struct is supported since API 12.| 24| [HiCollie_SetTimerParam](capi-hicollie-hicollie-settimerparam.md) | HiCollie_SetTimerParam | Defines the input parameters of the **OH_HiCollie_SetTimer** function.| 25 26### Enums 27 28| Name| typedef Keyword| Description| 29| -- | -- | -- | 30| [HiCollie_ErrorCode](#hicollie_errorcode) | HiCollie_ErrorCode | Enumerates the error codes used in the HiCollie module.| 31| [HiCollie_Flag](#hicollie_flag) | HiCollie_Flag | Enumerates the actions to be performed when a function times out.| 32 33### Functions 34 35| Name| typedef Keyword| Description| 36| -- | -- | -- | 37| [typedef void (\*OH_HiCollie_Task)(void)](#oh_hicollie_task) | OH_HiCollie_Task | Defines a function used to check whether a service thread is stuck.<br> This function is called by HiCollie every 3 seconds in an independent thread.<br> For example, this function can be used to send a message to a service thread and set a flag after the service thread receives the message. Then the flag is checked to determine whether the service thread is stuck.| 38| [typedef void (\*OH_HiCollie_BeginFunc)(const char* eventName)](#oh_hicollie_beginfunc) | OH_HiCollie_BeginFunc | Defines a function used to record the begin time when a service thread processes an event. This function is used in the jank event detection.<br> HiCollie checks the duration of each event. If the duration exceeds the preset threshold, a jank event is reported.<br> This function is inserted before each event is processed.| 39| [typedef void (\*OH_HiCollie_EndFunc)(const char* eventName)](#oh_hicollie_endfunc) | OH_HiCollie_EndFunc | Defines a function used to check whether a service thread is janky when processing an event. This function is used in the jank event detection.<br> HiCollie checks the duration of each event. If the duration exceeds the preset threshold, a jank event is reported.<br> This function is inserted after each event is processed.| 40| [HiCollie_ErrorCode OH_HiCollie_Init_StuckDetection(OH_HiCollie_Task task)](#oh_hicollie_init_stuckdetection) | - | Registers a callback used to periodically detect service thread stuck events. <br> By default, the **BUSSINESS_THREAD_BLOCK_3S** event is reported when the thread is blocked for 3s and the **BUSSINESS_THREAD_BLOCK_6S** event is reported when the thread is blocked for 6s.| 41| [HiCollie_ErrorCode OH_HiCollie_Init_StuckDetectionWithTimeout(OH_HiCollie_Task task, uint32_t stuckTimeout)](#oh_hicollie_init_stuckdetectionwithtimeout) | - | Registers a callback used to periodically detect service thread stuck events. <br> You can set the interval for the stuck event detection. The value range is [3, 15], in seconds.| 42| [HiCollie_ErrorCode OH_HiCollie_Init_JankDetection(OH_HiCollie_BeginFunc* beginFunc,OH_HiCollie_EndFunc* endFunc, HiCollie_DetectionParam param)](#oh_hicollie_init_jankdetection) | - | Registers a callback used to detect service thread jank events.<br> To monitor service thread jank events, you can implement two callbacks as instrumentation functions, placing them before and after the service thread event. | 43| [HiCollie_ErrorCode OH_HiCollie_Report(bool* isSixSecond)](#oh_hicollie_report) | - | Reports a service thread stuck event and generates logs to help locate application stuck issues.<br> Call **OH_HiCollie_Init_StuckDetection()** or **OH_HiCollie_Init_StuckDetectionWithTimeout()** to initialize the detection task.<br> If the task times out, call **OH_HiCollie_Report()** to report the stuck event based on the service logic.| 44| [typedef void (\*OH_HiCollie_Callback)(void*)](#oh_hicollie_callback) | OH_HiCollie_Callback | Triggered when [OH_HiCollie_CancelTimer](capi-hicollie-h.md#oh_hicollie_canceltimer) is not called within the custom task timeout period after [OH_HiCollie_SetTimer](capi-hicollie-h.md#oh_hicollie_settimer) is called.| 45| [HiCollie_ErrorCode OH_HiCollie_SetTimer(HiCollie_SetTimerParam param, int *id)](#oh_hicollie_settimer) | - | Registers a timer to check whether the execution time of a function or code block exceeds the custom time.<br> This API is used together with the **OH_HiCollie_CancelTimer** API.| 46| [void OH_HiCollie_CancelTimer(int id)](#oh_hicollie_canceltimer) | - | Cancels a timer based on the ID.<br> This API is used together with the **OH_HiCollie_SetTimer** API. It must be used after the function or code block is executed.<br> If a timer is not canceled within the custom time, a callback function is executed to generate fault logs for the specified timeout event.| 47 48## Enum Description 49 50### HiCollie_ErrorCode 51 52``` 53enum HiCollie_ErrorCode 54``` 55 56**Description** 57 58Enumerates the error codes used in the HiCollie module. 59 60**Since**: 12 61 62| Enum Item| Description | 63| -- |---------------------------------| 64| HICOLLIE_SUCCESS = 0 | The operation is successful. | 65| HICOLLIE_INVALID_ARGUMENT = 401 | The parameter is invalid. | 66| HICOLLIE_WRONG_THREAD_CONTEXT = 29800001 | The called thread is incorrect. | 67| HICOLLIE_REMOTE_FAILED = 29800002 | The remote call fails. | 68| HICOLLIE_INVALID_TIMER_NAME = 29800003 | The timer name is invalid.<br>**Since**: 18| 69| HICOLLIE_INVALID_TIMEOUT_VALUE = 29800004 | The function execution timeout value is invalid.<br>**Since**: 18 | 70| HICOLLIE_WRONG_PROCESS_CONTEXT = 29800005 | The process to be accessed is incorrect.<br>**Since**: 18 | 71| HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM = 29800006 | The pointer used to save the returned timer ID is null.<br>**Since**: 18 | 72 73### HiCollie_Flag 74 75``` 76enum HiCollie_Flag 77``` 78 79**Description** 80 81Enumerates the actions to be performed when a function times out. 82 83**Since**: 18 84 85| Enum Item| Description| 86| -- | -- | 87| HICOLLIE_FLAG_DEFAULT = (~0) | Generates logs and locates, kills, and recovers the process. This is the default value.| 88| HICOLLIE_FLAG_NOOP = (0) | Executes only the callback.| 89| HICOLLIE_FLAG_LOG = (1 << 0) | Generates logs.| 90| HICOLLIE_FLAG_RECOVERY = (1 << 1) | Terminates the process and triggers recovery.| 91 92 93## Function Description 94 95### OH_HiCollie_Task() 96 97``` 98typedef void (*OH_HiCollie_Task)(void) 99``` 100 101**Description** 102 103Defines a function used to check whether a service thread is stuck.<br> This function is called by HiCollie every 3 seconds in an independent thread.<br> For example, this function can be used to send a message to a service thread and set a flag after the service thread receives the message. Then the flag is checked to determine whether the service thread is stuck. 104 105**Since**: 12 106 107### OH_HiCollie_BeginFunc() 108 109``` 110typedef void (*OH_HiCollie_BeginFunc)(const char* eventName) 111``` 112 113**Description** 114 115Defines a function used to record the begin time when a service thread processes an event. This function is used in the jank event detection.<br> HiCollie checks the duration of each event. If the duration exceeds the preset threshold, a jank event is reported.<br> This function is inserted before each event is processed. 116 117**Since**: 12 118 119 120**Parameters** 121 122| Name| Description| 123| -- | -- | 124| const char* eventName | Name of the service thread event.| 125 126### OH_HiCollie_EndFunc() 127 128``` 129typedef void (*OH_HiCollie_EndFunc)(const char* eventName) 130``` 131 132**Description** 133 134Defines a function used to check whether a service thread is janky when processing an event. This function is used in the jank event detection.<br> HiCollie checks the duration of each event. If the duration exceeds the preset threshold, a jank event is reported.<br> This function is inserted after each event is processed. 135 136**Since**: 12 137 138 139**Parameters** 140 141| Name| Description| 142| -- | -- | 143| const char* eventName | Name of the service thread event.| 144 145### OH_HiCollie_Init_StuckDetection() 146 147``` 148HiCollie_ErrorCode OH_HiCollie_Init_StuckDetection(OH_HiCollie_Task task) 149``` 150 151**Description** 152 153Registers a callback used to periodically detect service thread stuck events. <br> By default, the **BUSSINESS_THREAD_BLOCK_3S** event is reported when the thread is blocked for 3s and the **BUSSINESS_THREAD_BLOCK_6S** event is reported when the thread is blocked for 6s. 154 155**Since**: 12 156 157 158**Parameters** 159 160| Name| Description| 161| -- | -- | 162| [OH_HiCollie_Task](capi-hicollie-h.md#oh_hicollie_task) task | A periodic detection task that is executed every 3 seconds to check whether a service thread is stuck.| 163 164**Returns** 165 166| Type| Description| 167| -- | -- | 168| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br> [HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - Incorrect calling thread. This function should be called in a non-main thread.<br> For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).| 169 170### OH_HiCollie_Init_StuckDetectionWithTimeout() 171 172``` 173HiCollie_ErrorCode OH_HiCollie_Init_StuckDetectionWithTimeout(OH_HiCollie_Task task, uint32_t stuckTimeout) 174``` 175 176**Description** 177 178Registers a callback used to periodically detect service thread stuck events. <br> You can set the interval for the stuck event detection. The value range is [3, 15], in seconds. 179 180**Since**: 18 181 182 183**Parameters** 184 185| Name| Description| 186| -- | -- | 187| [OH_HiCollie_Task](capi-hicollie-h.md#oh_hicollie_task) task | Periodic detection task that is executed every **stuckTimeout** time to check whether a service thread is stuck.| 188| uint32_t stuckTimeout | Threshold for reporting a service thread stuck event, in seconds. When the task execution time exceeds the value of **stuckTimeout**, a stuck warning event is reported. When the task execution time exceeds twice the value of **stuckTimeout**, a stuck event is reported.<br> The maximum value is **15s** and the minimum value is **3s**.| 189 190**Returns** 191 192| Type| Description| 193| -- | -- | 194| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br> [HICOLLIE_INVALID_ARGUMENT](capi-hicollie-h.md#hicollie_errorcode) 401 - Invalid detection time.<br> [HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - Incorrect calling thread. This function should be called in a non-main thread.<br> For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).| 195 196### OH_HiCollie_Init_JankDetection() 197 198``` 199HiCollie_ErrorCode OH_HiCollie_Init_JankDetection(OH_HiCollie_BeginFunc* beginFunc,OH_HiCollie_EndFunc* endFunc, HiCollie_DetectionParam param) 200``` 201 202**Description** 203 204Registers a callback used to detect service thread jank events.<br> To monitor service thread jank events, you can implement two callbacks as instrumentation functions, placing them before and after the service thread event. 205 206**Since**: 12 207 208 209**Parameters** 210 211| Name| Description| 212| -- | -- | 213| [OH_HiCollie_BeginFunc](capi-hicollie-h.md#oh_hicollie_beginfunc)* beginFunc | Function used before the service thread event detection.| 214| [OH_HiCollie_EndFunc](capi-hicollie-h.md#oh_hicollie_endfunc)* endFunc | Function used after the service thread event detection.| 215| [HiCollie_DetectionParam](capi-hicollie-hicollie-detectionparam.md) param | Extended parameter for future use.| 216 217**Returns** 218 219| Type| Description| 220| -- | -- | 221| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br> [HICOLLIE_INVALID_ARGUMENT](capi-hicollie-h.md#hicollie_errorcode) 401 - The begin and end functions are not both set or both unset; they must either both have valid values or both be empty.<br> [HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - Incorrect calling thread. This function should be called in a non-main thread.<br> For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).| 222 223### OH_HiCollie_Report() 224 225``` 226HiCollie_ErrorCode OH_HiCollie_Report(bool* isSixSecond) 227``` 228 229**Description** 230 231Reports a service thread stuck event and generates logs to help locate application stuck issues.<br> Call **OH_HiCollie_Init_StuckDetection()** or **OH_HiCollie_Init_StuckDetectionWithTimeout()** to initialize the detection task.<br> If the task times out, call **OH_HiCollie_Report()** to report the stuck event based on the service logic. 232 233**Since**: 12 234 235 236**Parameters** 237 238| Name| Description| 239| -- | -- | 240| bool* isSixSecond | Pointer to a Boolean value. If the service thread is stuck for 6s, the value is **true**. If the service thread is stuck for 3s, the value is **false**.| 241 242**Returns** 243 244| Type| Description| 245| -- | -- | 246| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br> [HICOLLIE_INVALID_ARGUMENT](capi-hicollie-h.md#hicollie_errorcode) 401 - The begin and end functions are not both set or both unset; they must either both have valid values or both be empty.<br> [HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - Incorrect calling thread. This function should be called in a non-main thread.<br> [HICOLLIE_REMOTE_FAILED](capi-hicollie-h.md#hicollie_errorcode) 29800002 - Remote call error. The IPC remote service fails to be called.<br> For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).| 247 248### OH_HiCollie_Callback() 249 250``` 251typedef void (*OH_HiCollie_Callback)(void*) 252``` 253 254**Description** 255 256Triggered when [OH_HiCollie_CancelTimer](capi-hicollie-h.md#oh_hicollie_canceltimer) is not called within the custom task timeout period after [OH_HiCollie_SetTimer](capi-hicollie-h.md#oh_hicollie_settimer) is called. 257 258**Since**: 18 259 260### OH_HiCollie_SetTimer() 261 262``` 263HiCollie_ErrorCode OH_HiCollie_SetTimer(HiCollie_SetTimerParam param, int *id) 264``` 265 266**Description** 267 268Registers a timer to check whether the execution time of a function or code block exceeds the custom time.<br> This API is used together with the **OH_HiCollie_CancelTimer** API. 269 270**Since**: 18 271 272 273**Parameters** 274 275| Name| Description| 276| -- | -- | 277| [HiCollie_SetTimerParam](capi-hicollie-hicollie-settimerparam.md) param | Input parameters.| 278| int *id | Pointer to the returned timer ID, which cannot be null.| 279 280**Returns** 281 282| Type| Description| 283| -- | -- | 284| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br> [HICOLLIE_INVALID_TIMER_NAME](capi-hicollie-h.md#hicollie_errorcode) 29800003 - Invalid timer name. The timer name cannot be NULL or an empty string.<br> [HICOLLIE_INVALID_TIMEOUT_VALUE](capi-hicollie-h.md#hicollie_errorcode) 29800004 - Invalid timeout value.<br> [HICOLLIE_WRONG_PROCESS_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800005 - Invalid process context for detection. This function cannot be called in the **appspawn** and **nativespawn** processes.<br> [HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM](capi-hicollie-h.md#hicollie_errorcode) 29800006 - The pointer used to save the returned timer ID is NULL.<br> For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).| 285 286### OH_HiCollie_CancelTimer() 287 288``` 289void OH_HiCollie_CancelTimer(int id) 290``` 291 292**Description** 293 294Cancels a timer based on the ID.<br> This API is used together with the **OH_HiCollie_SetTimer** API. It must be used after the function or code block is executed.<br> If a timer is not canceled within the custom time, a callback function is executed to generate fault logs for the specified timeout event. 295 296**Since**: 18 297 298 299**Parameters** 300 301| Name| Description| 302| -- | -- | 303| int id | Timer ID updated after the [OH_HiCollie_SetTimer](capi-hicollie-h.md#oh_hicollie_settimer) function is executed.| 304