1# HiCollie 2 3## Overview 4 5Provides the APIs for detecting service thread jank and stuck events. Note that these APIs must be called in non-service threads. 6 7The following capabilities are supported: (1) Register a periodic detection task for application service thread stuck events; (2) Register a callback for the detection of application service thread jank events; (3) Report application service thread stuck events. 8 9**System capability**: SystemCapability.HiviewDFX.HiCollie 10 11**Since**: 12 12 13 14## Summary 15 16 17### Files 18 19| Name| Description| 20| -------- | -------- | 21| [hicollie.h](hicollie_8h.md) | HiCollie provides APIs for detecting service thread stuck and jank events and reporting stuck events. | 22 23### Structs 24 25| Name| Description| 26| -------- | -------- | 27| struct [HiCollie_DetectionParam](_hi_hicollie___detection_param.md) | Defines the parameters of the service thread jank event detection. Note that these parameters are deprecated in API version 12 and reserved for extension only. | 28| struct [HiCollie_SetTimerParam](_hi_hicollie___set_timer_param.md) | Defines the parameters of the **OH_HiCollie_SetTimer** function. | 29 30### Types 31 32| Name| Description| 33| -------- | -------- | 34| typedef enum [HiCollie_ErrorCode](#hicollie_errorcode)[HiCollie_ErrorCode](#hicollie_errorcode) | Defines an enum for the error codes used in the HiCollie module. | 35| typedef void(\* [OH_HiCollie_Task](#oh_hicollie_task)) (void) | Defines a function to check whether a stuck event occurs in a service thread. This function is called by HiCollie every 3 seconds in an independent thread. For example, this function can send messages to service threads. When a service thread receives a message, a flag is set. By checking the flag, you can determine whether a stuck event occurs in the service thread. | 36| typedef void(\* [OH_HiCollie_BeginFunc](#oh_hicollie_beginfunc)) (const char \*eventName) | Defines a function to record the start time of event processing in the service thread during jank event detection. This function is used before event processing. | 37| typedef void(\* [OH_HiCollie_EndFunc](#oh_hicollie_endfunc)) (const char \*eventName) | Defines a function to check whether a jank event occurs in a service thread during event processing. This function is used after event processing. By checking the execution duration of the processing events, HiCollie determines the duration of each event. If the execution duration is greater than 150 ms but less than 450 ms, a jank event is reported. | 38| typedef struct [HiCollie_DetectionParam](_hi_hicollie___detection_param.md)[HiCollie_DetectionParam](#hicollie_detectionparam) | Defines a struct for the parameters of the service thread jank event detection. Note that these parameters are deprecated in API version 12 and reserved for extension only. | 39| typedef void(\* [OH_HiCollie_Callback](#oh_hicollie_callback)) (void \*) | Defines a function for timeout detection. | 40| typedef enum [HiCollie_Flag](#hicollie_flag)[HiCollie_Flag](#hicollie_flag) | Defines an enum for the executions to be performed when a function times out. | 41| typedef struct [HiCollie_SetTimerParam](_hi_hicollie___set_timer_param.md)[HiCollie_SetTimerParam](#hicollie_settimerparam) | Defines a struct for the parameters of the **OH_HiCollie_SetTimer** function. | 42 43### Enums 44 45| Name| Description| 46| -------- | -------- | 47| [HiCollie_ErrorCode](#hicollie_errorcode) {<br>HICOLLIE_SUCCESS = 0, HICOLLIE_INVALID_ARGUMENT = 401, HICOLLIE_WRONG_THREAD_CONTEXT = 29800001, HICOLLIE_REMOTE_FAILED = 29800002,<br>HICOLLIE_INVALID_TIMER_NAME = 29800003, HICOLLIE_INVALID_TIMEOUT_VALUE = 29800004, HICOLLIE_WRONG_PROCESS_CONTEXT = 29800005, HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM = 29800006<br>} | Enumerates the error codes used in the HiCollie module. | 48| [HiCollie_Flag](#hicollie_flag) { HICOLLIE_FLAG_DEFAULT = (~0), **HICOLLIE_FLAG_NOOP** = (0), **HICOLLIE_FLAG_LOG** = (1 << 0), **HICOLLIE_FLAG_RECOVERY** = (1 << 1) } | Enumerates the executions to be performed when a function times out. | 49 50### Functions 51 52| Name| Description| 53| -------- | -------- | 54| [HiCollie_ErrorCode](#hicollie_errorcode)[OH_HiCollie_Init_StuckDetection](#oh_hicollie_init_stuckdetection) ([OH_HiCollie_Task](#oh_hicollie_task) task) | Registers a callback to periodically detect service thread stuck events. | 55| [HiCollie_ErrorCode](#hicollie_errorcode)[OH_HiCollie_Init_JankDetection](#oh_hicollie_init_jankdetection) ([OH_HiCollie_BeginFunc](#oh_hicollie_beginfunc) \*beginFunc, [OH_HiCollie_EndFunc](#oh_hicollie_endfunc) \*endFunc, [HiCollie_DetectionParam](_hi_hicollie___detection_param.md) param) | Registers a callback to detect service thread jank events. | 56| [HiCollie_ErrorCode](#hicollie_errorcode)[OH_HiCollie_Report](#oh_hicollie_report) (bool \*isSixSecond) | Reports an application service thread stuck event. | 57| [HiCollie_ErrorCode](#hicollie_errorcode)[OH_HiCollie_SetTimer](#oh_hicollie_settimer) ([HiCollie_SetTimerParam](_hi_hicollie___set_timer_param.md) param, int \*id) | Sets a timer before a time-consuming function is called. | 58| void [OH_HiCollie_CancelTimer](#oh_hicollie_canceltimer) (int id) | Cancels a timer based on the timer ID. | 59 60## Type Description 61 62### HiCollie_DetectionParam 63 64``` 65typedef struct HiCollie_DetectionParamHiCollie_DetectionParam 66``` 67 68**Description** 69 70Defines a struct for the parameters of the service thread jank event detection. Note that these parameters are deprecated in API version 12 and reserved for extension only. 71 72**Since**: 12 73 74### HiCollie_ErrorCode 75 76``` 77typedef enum HiCollie_ErrorCode HiCollie_ErrorCode 78``` 79 80**Description** 81 82Defines an enum for the error codes used in the HiCollie module. 83 84**Since**: 12 85 86 87### HiCollie_Flag 88 89``` 90typedef enum HiCollie_Flag HiCollie_Flag 91``` 92 93**Description** 94 95Defines an enum for the executions to be performed when a function times out. 96 97**Since**: 16 98 99### HiCollie_SetTimerParam 100 101``` 102typedef struct HiCollie_SetTimerParamHiCollie_SetTimerParam 103``` 104 105**Description** 106 107Defines a struct for the parameters of the **OH_HiCollie_SetTimer** function. 108 109**Since**: 16 110 111### OH_HiCollie_BeginFunc 112 113``` 114typedef void (*OH_HiCollie_BeginFunc)(const char* eventName) 115``` 116 117**Description** 118 119Defines a function to record the start time of event processing in the service thread during jank event detection. This function is used before event processing. 120 121**Since**: 12 122 123**Parameters** 124 125| Name| Description| 126| -------- | -------- | 127| eventName | Name of the event processed in the service thread. | 128 129### OH_HiCollie_Callback 130 131``` 132typedef void(* OH_HiCollie_Callback) (void *) 133``` 134 135**Description** 136 137Defines a function for timeout detection. 138 139**Since**: 16 140 141### OH_HiCollie_EndFunc 142 143``` 144typedef void(* OH_HiCollie_EndFunc) (const char *eventName) 145``` 146 147**Description** 148 149Defines a function to check whether a jank event occurs in a service thread during event processing. This function is used after event processing. By checking the execution duration of the processing events, HiCollie determines the duration of each event. If the execution duration is greater than 150 ms but less than 450 ms, a jank event is reported. 150 151**Since**: 12 152 153**Parameters** 154 155| Name| Description| 156| -------- | -------- | 157| eventName | Name of the processing event in a service thread. | 158 159### OH_HiCollie_Task 160 161``` 162typedef void(* OH_HiCollie_Task) (void) 163``` 164 165**Description** 166 167Defines a function to check whether a stuck event occurs in a service thread. This function is called by HiCollie every 3 seconds in an independent thread. For example, this function can send messages to service threads. When a service thread receives a message, a flag is set. By checking the flag, you can determine whether a stuck event occurs in the service thread. 168 169**Since**: 12 170 171## Enum Description 172 173### HiCollie_ErrorCode 174 175``` 176enum HiCollie_ErrorCode 177``` 178 179**Description** 180 181Enumerates the error codes used in the HiCollie module. 182 183**Since**: 12 184 185| Value| Description| 186| -------- | -------- | 187| HICOLLIE_SUCCESS | The operation is successful. | 188| HICOLLIE_INVALID_ARGUMENT | The parameter is invalid. Possible causes: 1. The parameter value is incorrect. 2. The parameter type is incorrect. | 189| HICOLLIE_WRONG_THREAD_CONTEXT | The detection is called in an incorrect thread. Possible cause: The detection is called in a service thread. | 190| HICOLLIE_REMOTE_FAILED | The remote calling fails. | 191| HICOLLIE_INVALID_TIMER_NAME | The timer name is invalid.<br>**Since**: 16| 192| HICOLLIE_INVALID_TIMEOUT_VALUE | The function execution timeout value is invalid.<br>**Since**: 16| 193| HICOLLIE_WRONG_PROCESS_CONTEXT | The process to be accessed is incorrect.<br>**Since**: 16| 194| HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM | The timer ID is incorrect.<br>**Since**: 16| 195 196### HiCollie_Flag 197 198``` 199enum HiCollie_Flag 200``` 201 202**Description** 203 204Enumerates the executions to be performed when a function times out. 205 206**Since**: 16 207 208| Value| Description| 209| -------- | -------- | 210| HICOLLIE_FLAG_DEFAULT | Generates logs, locates and kills the process, and recovers the process. This is the default value. | 211| HICOLLIE_FLAG_NOOP | Executes only the callback. | 212| HICOLLIE_FLAG_LOG | Generates logs. | 213| HICOLLIE_FLAG_RECOVERY | Locates and kills the process, and recovers it. | 214 215## Function Description 216 217### OH_HiCollie_CancelTimer() 218 219``` 220void OH_HiCollie_CancelTimer (int id) 221``` 222 223**Description** 224 225Cancels a timer based on the timer ID. 226 227**Since**: 16 228 229**Parameters** 230 231| Name| Description| 232| -------- | -------- | 233| id | Timer ID updated after the [OH_HiCollie_SetTimer](#oh_hicollie_settimer) function is executed. You can cancel a timer task based on this ID. | 234 235### OH_HiCollie_Init_JankDetection() 236 237``` 238HiCollie_ErrorCode OH_HiCollie_Init_JankDetection (OH_HiCollie_BeginFunc * beginFunc, OH_HiCollie_EndFunc * endFunc, HiCollie_DetectionParam param ) 239``` 240 241**Description** 242 243Registers a callback to detect service thread jank events. 244 245**Since**: 12 246 247**Parameters** 248 249| Name| Description| 250| -------- | -------- | 251| beginFunc | The function used before the service thread event detection. | 252| endFunc | The function used after the service thread event detection. | 253| param | The extended parameter provided for subsequent development. | 254 255**Returns** 256 257**HICOLLIE_SUCCESS 0** - The operation is successful. **HICOLLIE_INVALID_ARGUMENT 401** - The parameter is invalid. Both the begin and end functions must have values or be empty. Otherwise, this error code is returned. **HICOLLIE_WRONG_THREAD_CONTEXT 29800001** - The calling thread is incorrect. This function cannot be called from the main thread. 258 259### OH_HiCollie_Init_StuckDetection() 260 261``` 262HiCollie_ErrorCode OH_HiCollie_Init_StuckDetection (OH_HiCollie_Task task) 263``` 264 265**Description** 266 267Registers a callback to periodically detect service thread stuck events. 268 269**Since**: 12 270 271**Parameters** 272 273| Name| Description| 274| -------- | -------- | 275| task | A periodic detection task that is executed every 3 seconds to check whether a stuck event occurs in a service thread. | 276 277**Returns** 278 279**HICOLLIE_SUCCESS 0** - The operation is successful. **HICOLLIE_WRONG_THREAD_CONTEXT 29800001** - The calling thread is incorrect. This function cannot be called from the main thread. 280 281### OH_HiCollie_Report() 282 283``` 284HiCollie_ErrorCode OH_HiCollie_Report (bool * isSixSecond) 285``` 286 287**Description** 288 289Reports an application service thread stuck event. 290 291**Since**: 12 292 293**Parameters** 294 295| Name| Description| 296| -------- | -------- | 297| 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**. | 298 299**Returns** 300 301**HICOLLIE_SUCCESS 0** - The operation is successful. **HICOLLIE_INVALID_ARGUMENT 401** - The parameter is invalid. Both the begin and end functions must have values or be empty. Otherwise, this error code is returned. **HICOLLIE_WRONG_THREAD_CONTEXT 29800001** - The calling thread is incorrect. This function cannot be called from the main thread. **HICOLLIE_REMOTE_FAILED 29800002** - The remote call fails. 302 303### OH_HiCollie_SetTimer() 304 305``` 306HiCollie_ErrorCode OH_HiCollie_SetTimer (HiCollie_SetTimerParam param, int * id ) 307``` 308 309**Description** 310 311Sets a timer before a time-consuming function is called. 312 313**Since**: 16 314 315**Parameters** 316 317| Name| Description| 318| -------- | -------- | 319| param | Input parameters. | 320| id | Pointer to the returned timer ID, which cannot be null. | 321 322**Returns** 323 324**HICOLLIE_SUCCESS 0** - The operation is successful. **HICOLLIE_INVALID_TIMER_NAME 29800003** - The timer name is invalid. It cannot be null or an empty string. **HICOLLIE_INVALID_TIMEOUT_VALUE 29800004** - The timeout value is invalid. **HICOLLIE_WRONG_PROCESS_CONTEXT 29800005** - The accessed detection process context is invalid. This function cannot be called in the appspawn and nativespawn processes. **HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM 29800006** - The pointer to the returned timer ID is invalid. The value cannot be null. 325