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