1# HiCollie
2
3
4## 概述
5
6本模块对外提供检测业务线程卡死、卡顿，以及上报卡死事件的能力。
7
8**起始版本：** 12
9
10
11## 汇总
12
13
14### 文件
15
16| 名称 | 描述 |
17| -------- | -------- |
18| [hicollie.h](hicollie_8h.md) | 定义HiCollie模块的功能。 |
19
20
21### 结构体
22
23| 名称 | 描述 |
24| -------- | -------- |
25| struct  [HiCollie_DetectionParam](_hi_hicollie___detection_param.md) | 设置检测业务线程卡顿的相关参数。 |
26
27
28### 类型定义
29
30| 名称 | 描述 |
31| -------- | -------- |
32| typedef enum [HiCollie_ErrorCode](errorcode-hiviewdfx-hicollie.md) [HiCollie_ErrorCode](#hicollie_errorcode) | 错误码定义。 |
33| typedef void(\* [OH_HiCollie_Task](#oh_hicollie_task)) (void) | 函数指针, 用户自定义回调函数内容，该回调函数用于周期性检测应用业务线程任务执行情况。 |
34| typedef void(\* [OH_HiCollie_BeginFunc](#oh_hicollie_beginfunc)) (const char \*name) | 函数指针, 用户自定义回调函数内容，该回调函数放在应用业务线程处理事件之前。 |
35| typedef void(\* [OH_HiCollie_EndFunc](#oh_hicollie_endfunc)) (const char \*name) | 函数指针, 用户自定义回调函数内容，该回调函数放在应用业务线程处理事件之后。 |
36| typedef struct [HiCollie_DetectionParam](_hi_hicollie___detection_param.md) [HiCollie_DetectionParam](#hicollie_detectionparam) | 用户可以自定义检测业务线程卡顿的相关参数。 |
37
38
39## 类型定义说明
40
41
42### HiCollie_ErrorCode
43
44```
45typedef enum HiCollie_ErrorCode HiCollie_ErrorCode
46```
47
48**描述**
49
50错误码定义。
51
52**起始版本：** 12
53
54
55### OH_HiCollie_Task
56
57```
58typedef void (*OH_HiCollie_Task)(void)
59```
60
61**描述**
62
63应用业务线程卡死检测回调函数。业务线程会定时执行该回调函数，检查线程完成情况，判定已经注册的线程是否卡死。
64
65**起始版本：** 12
66
67
68### OH_HiCollie_BeginFunc
69
70```
71typedef void (*OH_HiCollie_BeginFunc)(const char* eventName)
72```
73
74**描述**
75
76应用业务线程卡顿检测回调函数。该回调函数放在应用业务线程处理事件之前，用于记录线程开始处理事件时间。
77
78**起始版本：** 12
79
80
81### OH_HiCollie_EndFunc
82
83```
84typedef void (*OH_HiCollie_EndFunc)(const char* eventName)
85```
86
87**描述**
88
89应用业务线程卡顿检测回调函数。该回调函数放在应用业务线程处理事件之后，用于检测线程处理该事件是否出现卡顿情况。
90
91**起始版本：** 12
92
93
94### HiCollie_DetectionParam
95
96```
97typedef struct HiCollie_DetectionParam HiCollie_DetectionParam
98```
99
100**描述**
101
102用户可以自定义检测业务线程卡顿的相关参数，如：设置卡顿阈值。
103
104**起始版本：** 12
105
106
107### 函数
108
109| 名称 | 描述 |
110| -------- | -------- |
111| HiCollie_ErrorCode [OH_HiCollie_Init_StuckDetection](_hi_hicollie.md#oh_hicollie_init_stuckdetection) (OH_HiCollie_Task task) | 注册应用业务线程卡死的周期性检测任务。  |
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) | 注册应用业务线程卡顿检测的回调函数。  |
113| HiCollie_ErrorCode [OH_HiCollie_Report](_hi_hicollie.md#oh_hicollie_report) (bool\* isSixSecond) | 用于上报应用业务线程卡死事件，生成超时故障日志，辅助定位应用超时问题。结合OH_HiCollie_Init_StuckDetection接口配套使用，先初始化卡死检测，出现卡死时，再上报事件。  |
114
115
116## 函数说明
117
118
119### OH_HiCollie_Init_StuckDetection
120
121```
122HiCollie_ErrorCode OH_HiCollie_Init_StuckDetection(OH_HiCollie_Task task)
123```
124
125**描述**
126
127注册应用业务线程卡死的周期性检测任务。
128
129**起始版本：** 12
130
131**参数:**
132
133| 名称 | 描述 |
134| -------- | -------- |
135| task | 用户实现的回调函数, 定时检测业务线程卡死情况。如果用户想要取消检测，可以传空指针。 |
136
137
138**返回：**
139
140返回设置回调函数结果。如果返回结果为0，代表初始化业务线程卡死检测成功。
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
151注册应用业务线程卡顿检测的回调函数。线程卡顿监控功能需要开发者实现两个卡顿检测回调函数, 分别放在业务线程处理事件的前后。作为插桩函数，监控业务线程处理事件执行情况。
152
153**起始版本：** 12
154
155**参数:**
156
157| 名称 | 描述 |
158| -------- | -------- |
159| beginFunc | 用户实现的回调函数, 调用位置：业务线程处理事件之前。如果用户想要取消检测，beginFunc和endFunc需要同时传空指针。 |
160| endFunc | 用户实现的回调函数, 调用位置：业务线程处理事件之后。如果用户想要取消检测，beginFunc和endFunc需要同时传空指针。 |
161| param | 用户自定义线程卡顿参数，扩展参数以供后续开发使用。见[HiCollie_DetectionParam](_hi_hicollie___detection_param.md) |
162
163**返回：**
164
165返回设置回调函数结果。如果返回结果为0，代表初始化业务线程卡顿检测成功。
166
167
168### OH_HiCollie_Report
169
170```
171HiCollie_ErrorCode OH_HiCollie_Report(bool* isSixSecond);
172```
173
174**描述**
175
176用于上报应用业务线程卡死事件，生成超时故障日志，辅助定位应用超时问题。结合OH_HiCollie_Init_StuckDetection接口配套使用，先初始化卡死检测，出现卡死时，再上报事件。
177
178**起始版本：** 12
179
180**参数:**
181
182| 名称 | 描述 |
183| -------- | -------- |
184| isSixSecond | bool指针，如果卡住6秒，则为true。如果卡住3秒，则为False。 |
185
186
187**返回：**
188
189返回设置回调函数上报结果。如果返回结果为0，代表初始化业务线程上报卡死事件成功。
190