1# HiCollie
2
3
4## Overview
5
6HiCollie provides APIs for detecting service thread stuck and jank events and reporting service thread stuck events.
7
8**Since**: 12
9
10
11## Summary
12
13
14### Files
15
16| Name| Description|
17| -------- | -------- |
18| [hicollie.h](hicollie_8h.md) | Defines APIs for debugging.|
19
20
21### Structs
22
23| Name| Description|
24| -------- | -------- |
25| struct  [HiCollie_DetectionParam](_hi_hicollie___detection_param.md) | Defines the parameters of the jank event detection.|
26
27
28### Types
29
30| Name| Description|
31| -------- | -------- |
32| typedef enum [HiCollie_ErrorCode](errorcode-hiviewdfx-hicollie.md) [HiCollie_ErrorCode](#hicollie_errorcode) | Defines an enum for error codes.| 
33| typedef void(\* [OH_HiCollie_Task](#oh_hicollie_task)) (void) | Defines the pointer to the user-defined callback. This callback is used to periodically check the processing event on the application service thread.| 
34| typedef void(\* [OH_HiCollie_BeginFunc](#oh_hicollie_beginfunc)) (const char \*name) | Defines the pointer to the user-defined callback. This callback is used before the service thread processes the event.| 
35| typedef void(\* [OH_HiCollie_EndFunc](#oh_hicollie_endfunc)) (const char \*name) | Defines the pointer to the user-defined callback. This callback is used after the service thread processed the event.| 
36| typedef struct [HiCollie_DetectionParam](_hi_hicollie___detection_param.md) [HiCollie_DetectionParam](#hicollie_detectionparam) | Defines a struct for the parameters of the user-defined jank event detection.| 
37
38
39## Type Description
40
41
42### HiCollie_ErrorCode
43
44```
45typedef enum HiCollie_ErrorCode HiCollie_ErrorCode
46```
47
48**Description**
49
50Defines an enum for error codes.
51
52**Since**: 12
53
54
55### OH_HiCollie_Task
56
57```
58typedef void (*OH_HiCollie_Task)(void)
59```
60
61**Description**
62
63Defines the pointer to the user-defined callback for the stuck event detection. This callback is used to periodically check whether the processing event on the service thread is stuck.
64
65**Since**: 12
66
67
68### OH_HiCollie_BeginFunc
69
70```
71typedef void (*OH_HiCollie_BeginFunc)(const char* eventName)
72```
73
74**Description**
75
76Defines the pointer to the user-defined callback for the jank event detection. This callback is used before the service thread processes the event to record the start time of the processing event.
77
78**Since**: 12
79
80
81### OH_HiCollie_EndFunc
82
83```
84typedef void (*OH_HiCollie_EndFunc)(const char* eventName)
85```
86
87**Description**
88
89Defines the pointer to the user-defined callback for the jank event detection. This callback is used after the service thread processed the event to check whether the thread is jank.
90
91**Since**: 12
92
93
94### HiCollie_DetectionParam
95
96```
97typedef struct HiCollie_DetectionParam HiCollie_DetectionParam
98```
99
100**Description**
101
102Defines the pointer to the parameters of the user-defined jank event detection, such as the threshold of the jank event.
103
104**Since**: 12
105
106
107### Functions
108
109| Name| Description| 
110| -------- | -------- |
111| HiCollie_ErrorCode [OH_HiCollie_Init_StuckDetection](_hi_hicollie.md#oh_hicollie_init_stuckdetection) (OH_HiCollie_Task task) | Registers a callback to periodically detect service thread stuck events. | 
112| HiCollie_ErrorCode [OH_HiCollie_Init_JankDetection](_hi_hicollie.md#oh_hicollie_init_jankdetection) (OH_HiCollie_BeginFunc\* beginFunc, OH_HiCollie_EndFunc\* endFunc, HiCollie_DetectionParam param) | Registers a callback to detect service thread jank events. | 
113| HiCollie_ErrorCode [OH_HiCollie_Report](_hi_hicollie.md#oh_hicollie_report) (bool\* isSixSecond) | Reports service thread stuck events and generates timeout logs to help locate application timeout events. 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. | 
114
115
116## Function Description
117
118
119### OH_HiCollie_Init_StuckDetection
120
121```
122HiCollie_ErrorCode OH_HiCollie_Init_StuckDetection(OH_HiCollie_Task task)
123```
124
125**Description**
126
127Registers a callback to periodically detect service thread stuck events.
128
129**Since**: 12
130
131**Parameters**
132
133| Name| Description|
134| -------- | -------- |
135| task | Callback used to periodically check whether the service thread is stuck. If you want to cancel the detection, pass a null pointer.|
136
137
138**Returns**
139
140 Returns **0** if the stuck event detection is successfully initialized.
141
142
143### OH_HiCollie_Init_JankDetection
144
145```
146HiCollie_ErrorCode OH_HiCollie_Init_JankDetection(OH_HiCollie_BeginFunc* beginFunc, OH_HiCollie_EndFunc* endFunc, HiCollie_DetectionParam param);
147
148```
149
150**Description**
151
152Registers a callback to detect service thread jank events. To monitor thread jank events, you can implement two callbacks as instrumentation functions, placing them before and after the service thread processes the event.  
153
154**Since**: 12
155
156**Parameters**
157
158| Name| Description|
159| -------- | -------- |
160| beginFunc | Callback used before the service thread processes the event. If you want to cancel the detection, pass a null pointer to **beginFunc** and **endFunc**.|
161| endFunc | Callback used after the service thread processed the event. If you want to cancel the detection, pass a null pointer to **beginFunc** and **endFunc**.|
162| param | Parameters of the user-defined jank event detection. Extended parameters for future development use. For details, see [HiCollie_DetectionParam](_hi_hicollie___detection_param.md).|
163
164**Returns**
165
166 Returns **0** if the jank event detection is successfully initialized.
167
168
169### OH_HiCollie_Report
170
171```
172HiCollie_ErrorCode OH_HiCollie_Report(bool* isSixSecond);
173
174```
175
176**Description**
177
178Reports service thread stuck events and generates timeout logs to help locate application timeout events. 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.
179
180**Since**: 12
181
182**Parameters**
183
184| Name| Description|
185| -------- | -------- |
186| isSixSecond | Pointer to the boolean variable, whose value is **true** when the service thread is stuck for 6s. If the service thread is stuck for 3s, the value is **false**.|
187
188
189**Returns**
190
191 Returns **0** if the stuck event reporting function is successfully initialized.
192