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**Description**
150
151Registers 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.
152
153**Since**: 12
154
155**Parameters**
156
157| Name| Description|
158| -------- | -------- |
159| 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**.|
160| 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**.|
161| param | Custom extended parameter used in the jank detection, which is provided for future development. See [HiCollie_DetectionParam](_hi_hicollie___detection_param.md).|
162
163**Returns**
164
165 Returns **0** if the jank event detection is successfully initialized.
166
167
168### OH_HiCollie_Report
169
170```
171HiCollie_ErrorCode OH_HiCollie_Report(bool* isSixSecond);
172```
173
174**Description**
175
176Reports 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.
177
178**Since**: 12
179
180**Parameters**
181
182| Name| Description|
183| -------- | -------- |
184| 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**.|
185
186
187**Returns**
188
189 Returns **0** if the stuck event reporting function is successfully initialized.
190