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 29### Structs 30 31| Name| Description| 32| -------- | -------- | 33| 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. | 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 46 47### Enums 48 49| Name| Description| 50| -------- | -------- | 51| [HiCollie_ErrorCode](#hicollie_errorcode) { HICOLLIE_SUCCESS = 0, HICOLLIE_INVALID_ARGUMENT = 401, HICOLLIE_WRONG_THREAD_CONTEXT = 29800001, HICOLLIE_REMOTE_FAILED = 29800002 } | Enumerates the error codes used in the HiCollie module. | 52 53 54### Functions 55 56| Name| Description| 57| -------- | -------- | 58| [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. | 59| [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. | 60| [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.| 61 62 63## Type Description 64 65 66### HiCollie_DetectionParam 67 68``` 69typedef struct HiCollie_DetectionParamHiCollie_DetectionParam 70``` 71**Description** 72Defines 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. 73 74**Since**: 12 75 76 77### HiCollie_ErrorCode 78 79``` 80typedef enum HiCollie_ErrorCode HiCollie_ErrorCode 81``` 82**Description** 83Defines an enum for the error codes used in the HiCollie module. 84 85**Since**: 12 86 87 88### OH_HiCollie_BeginFunc 89 90``` 91typedef void (*OH_HiCollie_BeginFunc)(const char* eventName) 92``` 93**Description** 94Defines a function used to record the start time of the service thread event during jank event detection. This function is used before event processing. 95 96**Since**: 12 97 98**Parameters** 99 100| Name| Description| 101| -------- | -------- | 102| eventName | Name of the service thread event. | 103 104 105### OH_HiCollie_EndFunc 106 107``` 108typedef void(* OH_HiCollie_EndFunc) (const char *eventName) 109``` 110**Description** 111Defines a function used to check whether a service thread is janky during event processing. This function is used after event processing. 112 113By 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. 114 115**Since**: 12 116 117**Parameters** 118 119| Name| Description| 120| -------- | -------- | 121| eventName | Name of the service thread event. | 122 123 124### OH_HiCollie_Task 125 126``` 127typedef void(* OH_HiCollie_Task) (void) 128``` 129**Description** 130Defines a function used to check whether a service thread is stuck. 131 132This function is called by HiCollie every 3 seconds in an independent thread. 133 134For 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. 135 136**Since**: 12 137 138 139## Enum Description 140 141 142### HiCollie_ErrorCode 143 144``` 145enum HiCollie_ErrorCode 146``` 147**Description** 148Enumerates the error codes used in the HiCollie module. 149 150**Since**: 12 151 152| Value| Description| 153| -------- | -------- | 154| HICOLLIE_SUCCESS | The operation is successful. | 155| HICOLLIE_INVALID_ARGUMENT | The parameter is invalid. Possible causes: 1. The parameter value is incorrect. 2. The parameter type is incorrect. | 156| HICOLLIE_WRONG_THREAD_CONTEXT | This function is not called in a service thread. | 157| HICOLLIE_REMOTE_FAILED | The remote call fails. | 158 159 160## Function Description 161 162 163### OH_HiCollie_Init_JankDetection() 164 165``` 166HiCollie_ErrorCode OH_HiCollie_Init_JankDetection (OH_HiCollie_BeginFunc * beginFunc, OH_HiCollie_EndFunc * endFunc, HiCollie_DetectionParam param ) 167``` 168**Description** 169Registers a callback used to detect service thread jank events. 170 171To monitor service thread jank events, you can implement two callbacks as instrumentation functions, placing them before and after the service thread event. 172 173**Since**: 12 174 175**Parameters** 176 177| Name| Description| 178| -------- | -------- | 179| beginFunc | The function used before the service thread event detection. | 180| endFunc | The function used after the service thread event detection. | 181| param | The extended parameter provided for subsequent development. | 182 183**Returns** 184 185**HICOLLIE_SUCCESS 0** - The operation is successful. 186 187**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. 188 189**HICOLLIE_WRONG_THREAD_CONTEXT 29800001** - The called thread is incorrect. This function cannot be called from the main thread. 190 191 192### OH_HiCollie_Init_StuckDetection() 193 194``` 195HiCollie_ErrorCode OH_HiCollie_Init_StuckDetection (OH_HiCollie_Task task) 196``` 197**Description** 198Registers a callback used to periodically detect service thread stuck events. 199 200**Since**: 12 201 202**Parameters** 203 204| Name| Description| 205| -------- | -------- | 206| task | A periodic detection task that is executed every 3 seconds to check whether a service thread is stuck. | 207 208**Returns** 209 210**HICOLLIE_SUCCESS 0** - The operation is successful. 211 212**HICOLLIE_WRONG_THREAD_CONTEXT 29800001** - The called thread is incorrect. This function cannot be called from the main thread. 213 214 215### OH_HiCollie_Report() 216 217``` 218HiCollie_ErrorCode OH_HiCollie_Report (bool * isSixSecond) 219``` 220**Description** 221Reports a service thread stuck event and generates timeout logs to help locate application timeout events. 222 223This 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. 224 225**Since**: 12 226 227**Parameters** 228 229| Name| Description| 230| -------- | -------- | 231| 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**. | 232 233**Returns** 234 235**HICOLLIE_SUCCESS 0** - The operation is successful. 236 237**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. 238 239**HICOLLIE_WRONG_THREAD_CONTEXT 29800001** - The called thread is incorrect. This function cannot be called from the main thread. 240 241**HICOLLIE_REMOTE_FAILED 29800002** - The remote call fails. 242