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 jank event detection. Note that this struct is supported since API 12. | 33| struct [HiCollie_SetTimerParam](_hi_collie___set_timer_param.md) | Defines 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 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.| 42| typedef void(\* [OH_HiCollie_BeginFunc](#oh_hicollie_beginfunc)) (const char \*eventName) | 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.| 43| typedef void(\* [OH_HiCollie_EndFunc](#oh_hicollie_endfunc)) (const char \*eventName) | 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.| 44| typedef struct [HiCollie_DetectionParam](_hi_collie___detection_param.md) [HiCollie_DetectionParam](#hicollie_detectionparam) | Defines a struct for the parameters of the jank event detection. Note that this type is supported since API 12. | 45| typedef void(\* [OH_HiCollie_Callback](#oh_hicollie_callback)) (void \*) | Defines a callback function to be executed when [OH_HiCollie_CancelTimer](#oh_hicollie_canceltimer) is not called within the custom task timeout period after [OH_HiCollie_SetTimer](#oh_hicollie_settimer)) is called. | 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, 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. | 55| [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. | 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. <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.| 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. <br>You can set the interval for the stuck event detection. The value range is [3, 15], in seconds.| 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 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.| 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 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.| 67| void [OH_HiCollie_CancelTimer](#oh_hicollie_canceltimer) (int id) | 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.| 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 jank event detection. Note that this type is supported since API 12. 80 81**Since**: 12 82 83 84### HiCollie_ErrorCode 85 86``` 87typedef enum HiCollie_ErrorCodeHiCollie_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_FlagHiCollie_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 begin time when a service thread processes an event. This function is used in the jank event detection. 124 125HiCollie checks the duration of each event. If the duration exceeds the preset threshold, a jank event is reported. 126 127This function is inserted before each event is processed. 128 129**Since**: 12 130 131**Parameters** 132 133| Name| Description| 134| -------- | -------- | 135| eventName | Name of the service thread event. | 136 137 138### OH_HiCollie_Callback 139 140``` 141typedef void(* OH_HiCollie_Callback) (void *) 142``` 143**Description** 144Defines a callback function to be executed when [OH_HiCollie_CancelTimer](#oh_hicollie_canceltimer) is not called within the custom task timeout period after [OH_HiCollie_SetTimer](#oh_hicollie_settimer)) is called. 145 146**Since**: 18 147 148 149### OH_HiCollie_EndFunc 150 151``` 152typedef void(* OH_HiCollie_EndFunc) (const char *eventName) 153``` 154**Description** 155Defines a function used to check whether a service thread is janky when processing an event. This function is used in the jank event detection. 156 157HiCollie checks the duration of each event. If the duration exceeds the preset threshold, a jank event is reported. 158 159This function is inserted after each event is processed. 160 161**Since**: 12 162 163**Parameters** 164 165| Name| Description| 166| -------- | -------- | 167| eventName | Name of the service thread event. | 168 169 170### OH_HiCollie_Task 171 172``` 173typedef void(* OH_HiCollie_Task) (void) 174``` 175**Description** 176Defines a function used to check whether a service thread is stuck. 177 178This function is called by HiCollie every 3 seconds in an independent thread. 179 180For 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. 181 182**Since**: 12 183 184 185## Enum Description 186 187 188### HiCollie_ErrorCode 189 190``` 191enum HiCollie_ErrorCode 192``` 193**Description** 194Enumerates the error codes used in the HiCollie module. 195 196**Since**: 12 197 198| Value| Description| 199| -------- | -------- | 200| HICOLLIE_SUCCESS | The operation is successful. | 201| HICOLLIE_INVALID_ARGUMENT | The parameter is invalid. | 202| HICOLLIE_WRONG_THREAD_CONTEXT | The called thread is incorrect. | 203| HICOLLIE_REMOTE_FAILED | The remote call fails. | 204| HICOLLIE_INVALID_TIMER_NAME | The timer name is invalid.<br>**Since**: 18| 205| HICOLLIE_INVALID_TIMEOUT_VALUE | The function execution timeout value is invalid.<br>**Since**: 18| 206| HICOLLIE_WRONG_PROCESS_CONTEXT | The process to be accessed is incorrect.<br>**Since**: 18| 207| HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM | The pointer used to save the returned timer ID is null.<br>**Since**: 18| 208 209 210### HiCollie_Flag 211 212``` 213enum HiCollie_Flag 214``` 215**Description** 216Enumerates the executions to be performed when a function times out. 217 218**Since**: 18 219 220| Value| Description| 221| -------- | -------- | 222| HICOLLIE_FLAG_DEFAULT | Generates logs and locates, kills, and recovers the process. This is the default value. | 223 224 225## Function Description 226 227 228### OH_HiCollie_CancelTimer() 229 230``` 231void OH_HiCollie_CancelTimer (int id) 232``` 233**Description** 234Cancels a timer based on the ID. 235 236This API is used together with the **OH_HiCollie_SetTimer** API. It must be used after the function or code block is executed. 237 238If a timer is not canceled within the custom time, a callback function is executed to generate fault logs for the specified timeout event. 239 240**Since**: 18 241 242**Parameters** 243 244| Name| Description| 245| -------- | -------- | 246| id | Timer ID updated after the [OH_HiCollie_SetTimer](#oh_hicollie_settimer) function is executed. | 247 248 249### OH_HiCollie_Init_JankDetection() 250 251``` 252HiCollie_ErrorCode OH_HiCollie_Init_JankDetection (OH_HiCollie_BeginFunc * beginFunc, OH_HiCollie_EndFunc * endFunc, HiCollie_DetectionParam param ) 253``` 254**Description** 255Registers a callback used to detect service thread jank events. 256 257To monitor service thread jank events, you can implement two callbacks as instrumentation functions, placing them before and after the service thread event. 258 259**Since**: 12 260 261**Parameters** 262 263| Name| Description| 264| -------- | -------- | 265| beginFunc | The function used before the service thread event detection. | 266| endFunc | The function used after the service thread event detection. | 267| param | The extended parameter provided for subsequent development. | 268 269**Returns** 270 271**HICOLLIE_SUCCESS 0** - The operation is successful. 272 273**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. 274 275**HICOLLIE_WRONG_THREAD_CONTEXT 29800001** - The called thread is incorrect. This function should be called in a non-main thread. 276 277For details, see [HiCollie_ErrorCode](#hicollie_errorcode). 278 279 280### OH_HiCollie_Init_StuckDetection() 281 282``` 283HiCollie_ErrorCode OH_HiCollie_Init_StuckDetection (OH_HiCollie_Task task) 284``` 285**Description** 286Registers a callback used to periodically detect service thread stuck events. 287 288By 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. 289 290**Since**: 12 291 292**Parameters** 293 294| Name| Description| 295| -------- | -------- | 296| task | A periodic detection task that is executed every 3 seconds to check whether a service thread is stuck. | 297 298**Returns** 299 300**HICOLLIE_SUCCESS 0** - The operation is successful. 301 302**HICOLLIE_WRONG_THREAD_CONTEXT 29800001** - The called thread is incorrect. This function should be called in a non-main thread. 303 304For details, see [HiCollie_ErrorCode](#hicollie_errorcode). 305 306 307### OH_HiCollie_Init_StuckDetectionWithTimeout() 308 309``` 310HiCollie_ErrorCode OH_HiCollie_Init_StuckDetectionWithTimeout (OH_HiCollie_Task task, uint32_t stuckTimeout ) 311``` 312**Description** 313Registers a callback used to periodically detect service thread stuck events. 314 315You can set the interval for the stuck event detection. The value range is [3, 15], in seconds. 316 317**Since**: 18 318 319**Parameters** 320 321| Name| Description| 322| -------- | -------- | 323| task | A periodic detection task that is executed every **stuckTimeout** time to check whether a service thread is stuck. | 324| 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**.| 325 326**Returns** 327 328**HICOLLIE_SUCCESS 0** - The operation is successful. 329 330**HICOLLIE_INVALID_ARGUMENT 401** - The threshold value is incorrect. 331 332**HICOLLIE_WRONG_THREAD_CONTEXT 29800001** - The called thread is incorrect. This function should be called in a non-main thread. 333 334For details, see [HiCollie_ErrorCode](#hicollie_errorcode). 335 336 337### OH_HiCollie_Report() 338 339``` 340HiCollie_ErrorCode OH_HiCollie_Report (bool * isSixSecond) 341``` 342**Description** 343Reports a service thread stuck event and generates logs to help locate application stuck issues. 344 345Call **OH_HiCollie_Init_StuckDetection()** or **OH_HiCollie_Init_StuckDetectionWithTimeout()** to initialize the detection task. 346 347If the task times out, call **OH_HiCollie_Report()** to report the stuck event based on the service logic. 348 349**Since**: 12 350 351**Parameters** 352 353| Name| Description| 354| -------- | -------- | 355| 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**. | 356 357**Returns** 358 359**HICOLLIE_SUCCESS 0** - The operation is successful. 360 361**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. 362 363**HICOLLIE_WRONG_THREAD_CONTEXT 29800001** - The called thread is incorrect. This function should be called in a non-main thread. 364 365**HICOLLIE_REMOTE_FAILED 29800002** - The remote call fails. The IPC remote service fails to be called. 366 367For details, see [HiCollie_ErrorCode](#hicollie_errorcode). 368 369 370### OH_HiCollie_SetTimer() 371 372``` 373HiCollie_ErrorCode OH_HiCollie_SetTimer (HiCollie_SetTimerParam param, int * id ) 374``` 375**Description** 376Registers a timer to check whether the execution time of a function or code block exceeds the custom time. 377 378This API is used together with the **OH_HiCollie_CancelTimer** API. 379 380**Since**: 18 381 382**Parameters** 383 384| Name| Description| 385| -------- | -------- | 386| param | Input parameters. For details, see [HiCollie_SetTimerParam](#hicollie_settimerparam).| 387| id | Pointer to the returned timer ID, which cannot be null. | 388 389**Returns** 390 391**HICOLLIE_SUCCESS 0** - The operation is successful. 392 393**HICOLLIE_INVALID_TIMER_NAME 29800003** - The timer name is invalid. It cannot be null or an empty string. 394 395**HICOLLIE_INVALID_TIMEOUT_VALUE 29800004** - The timeout value is invalid. 396 397**HICOLLIE_WRONG_PROCESS_CONTEXT 29800005** - The accessed detection process context is invalid. This function cannot be called in the appspawn and nativespawn processes. 398 399**HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM 29800006** - The pointer to the returned timer ID is invalid. The value cannot be null. 400 401For details, see [HiCollie_ErrorCode](#hicollie_errorcode). 402