• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# HiCollie
2
3
4## 概述
5
6提供检测业务线程卡死或卡顿的能力。请注意：要在非业务线程中调用。
7
8本模块函数可用于：
9
10（1）注册应用业务线程卡死的周期性检测任务；
11
12（2）注册应用业务线程卡顿检测的回调函数；
13
14（3）上报应用业务线程卡死事件。
15
16**起始版本：** 12
17
18
19## 汇总
20
21
22### 文件
23
24| 名称 | 描述 |
25| -------- | -------- |
26| [hicollie.h](hicollie_8h.md) | HiCollie模块对外提供检测业务线程卡死、卡顿，以及上报卡死事件的能力。 |
27
28
29### 结构体
30
31| 名称 | 描述 |
32| -------- | -------- |
33| struct  [HiCollie_DetectionParam](_hi_collie___detection_param.md) | 用于检测业务线程卡顿的参数。请注意，这些参数对API 12无效，仅用于扩展。  |
34
35
36### 类型定义
37
38| 名称 | 描述 |
39| -------- | -------- |
40| typedef enum [HiCollie_ErrorCode](#hicollie_errorcode) [HiCollie_ErrorCode](#hicollie_errorcode) | 错误码定义。  |
41| typedef void(\* [OH_HiCollie_Task](#oh_hicollie_task)) (void) | 在业务线程卡死检测中，通过实现该函数来检测业务线程是否卡住。<br/>HiCollie将在独立线程中每3秒调用一次该函数。<br/>例如：该函数可实现向业务线程发送消息。在业务线程接收到消息之后，设置一个标记，通过检查这个标记，可以知道业务线程是否卡住。 |
42| typedef void(\* [OH_HiCollie_BeginFunc](#oh_hicollie_beginfunc)) (const char \*eventName) | 事件处理前调用该函数。在卡顿检测中, 通过实现该函数来记录业务线程处理事件的开始时间。  |
43| typedef void(\* [OH_HiCollie_EndFunc](#oh_hicollie_endfunc)) (const char \*eventName) | 事件处理后调用该函数。在卡顿检测中, 通过实现该函数来检测业务线程处理事件是否卡顿。<br/>通过检查处理事件的执行时间，HiCollie将知道每个事件的持续时间。如果超过预设阈值(150ms~450ms)，将上报卡顿事件。 |
44| typedef struct [HiCollie_DetectionParam](_hi_collie___detection_param.md) [HiCollie_DetectionParam](#hicollie_detectionparam) | 用于检测业务线程卡顿的参数。请注意，这些参数对API 12无效，仅用于扩展。  |
45
46
47### 枚举
48
49| 名称 | 描述 |
50| -------- | -------- |
51| [HiCollie_ErrorCode](#hicollie_errorcode) { HICOLLIE_SUCCESS = 0, HICOLLIE_INVALID_ARGUMENT = 401, HICOLLIE_WRONG_THREAD_CONTEXT = 29800001, HICOLLIE_REMOTE_FAILED = 29800002 } | 错误码定义。  |
52
53
54### 函数
55
56| 名称 | 描述 |
57| -------- | -------- |
58| [HiCollie_ErrorCode](#hicollie_errorcode) [OH_HiCollie_Init_StuckDetection](#oh_hicollie_init_stuckdetection) ([OH_HiCollie_Task](#oh_hicollie_task) task) | 注册应用业务线程卡死的周期性检测任务。用户实现回调函数, 用于定时检测业务线程卡死情况。  |
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) | 注册应用业务线程卡顿检测的回调函数。<br/>线程卡顿监控功能需要开发者实现两个卡顿检测回调函数, 分别放在业务线程处理事件的前后。作为插桩函数，监控业务线程处理事件执行情况。 |
60| [HiCollie_ErrorCode](#hicollie_errorcode) [OH_HiCollie_Report](#oh_hicollie_report) (bool \*isSixSecond) | 用于上报应用业务线程卡死事件，生成超时故障日志，辅助定位应用超时问题。<br/>结合OH_HiCollie_Init_StuckDetection接口配套使用，先初始化卡死检测，出现卡死时，再上报事件。 |
61
62
63## 类型定义说明
64
65
66### HiCollie_DetectionParam
67
68```
69typedef struct HiCollie_DetectionParamHiCollie_DetectionParam
70```
71**描述**
72用于检测业务线程卡顿的参数。请注意，这些参数对API 12无效，仅用于扩展。
73
74**起始版本：** 12
75
76
77### HiCollie_ErrorCode
78
79```
80typedef enum HiCollie_ErrorCodeHiCollie_ErrorCode
81```
82**描述**
83错误码定义。
84
85**起始版本：** 12
86
87
88### OH_HiCollie_BeginFunc
89
90```
91typedef void(* OH_HiCollie_BeginFunc) (const char *eventName)
92```
93**描述**
94事件处理前调用该函数。在卡顿检测中, 通过实现该函数来记录业务线程处理事件的开始时间。
95
96**起始版本：** 12
97
98**参数:**
99
100| 名称 | 描述 |
101| -------- | -------- |
102| eventName | 业务线程处理事件的名字。  |
103
104
105### OH_HiCollie_EndFunc
106
107```
108typedef void(* OH_HiCollie_EndFunc) (const char *eventName)
109```
110**描述**
111事件处理后调用该函数。在卡顿检测中, 通过实现该函数来检测业务线程处理事件是否卡顿。
112
113通过检查处理事件的执行时间，HiCollie将知道每个事件的持续时间。如果超过预设阈值(150ms~450ms)，将上报卡顿事件。
114
115**起始版本：** 12
116
117**参数:**
118
119| 名称 | 描述 |
120| -------- | -------- |
121| eventName | 业务线程处理事件的名字。  |
122
123
124### OH_HiCollie_Task
125
126```
127typedef void(* OH_HiCollie_Task) (void)
128```
129**描述**
130在业务线程卡死检测中，通过实现该函数来检测业务线程是否卡住。
131
132HiCollie将在独立线程中每3秒调用一次该函数。
133
134例如：该函数可实现向业务线程发送消息。在业务线程接收到消息之后，设置一个标记，通过检查这个标记，可以知道业务线程是否卡住。
135
136**起始版本：** 12
137
138
139## 枚举类型说明
140
141
142### HiCollie_ErrorCode
143
144```
145enum HiCollie_ErrorCode
146```
147**描述**
148错误码定义。
149
150**起始版本：** 12
151
152| 枚举值 | 描述 |
153| -------- | -------- |
154| HICOLLIE_SUCCESS  | 成功。&nbsp;&nbsp; |
155| HICOLLIE_INVALID_ARGUMENT  | 无效参数。可能的原因：1. 参数传值问题；2. 参数类型问题。&nbsp;&nbsp; |
156| HICOLLIE_WRONG_THREAD_CONTEXT  | 检测的线程错误：在业务线程中调用。&nbsp;&nbsp; |
157| HICOLLIE_REMOTE_FAILED  | 远程调用错误。&nbsp;&nbsp; |
158
159
160## 函数说明
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**描述**
169注册应用业务线程卡顿检测的回调函数。
170
171线程卡顿监控功能需要开发者实现两个卡顿检测回调函数, 分别放在业务线程处理事件的前后。作为插桩函数，监控业务线程处理事件执行情况。
172
173**起始版本：** 12
174
175**参数:**
176
177| 名称 | 描述 |
178| -------- | -------- |
179| beginFunc | 检测业务线程处理事件前的函数。  |
180| endFunc | 检测业务线程处理事件后的函数。  |
181| param | 扩展参数以供将来使用。  |
182
183**返回：**
184
185HICOLLIE_SUCCESS 0 - 成功。
186
187HICOLLIE_INVALID_ARGUMENT 401 - 开始函数和结束函数两者都必须有值或为空，否则将返回该错误值。
188
189HICOLLIE_WRONG_THREAD_CONTEXT 29800001 - 调用线程错误。无法从主线程调用该函数。
190
191
192### OH_HiCollie_Init_StuckDetection()
193
194```
195HiCollie_ErrorCode OH_HiCollie_Init_StuckDetection (OH_HiCollie_Task task)
196```
197**描述**
198注册应用业务线程卡死的周期性检测任务。用户实现回调函数, 用于定时检测业务线程卡死情况。
199
200**起始版本：** 12
201
202**参数:**
203
204| 名称 | 描述 |
205| -------- | -------- |
206| task | 每3秒执行一次的周期性检测任务，用于检测业务线程是否卡住。  |
207
208**返回：**
209
210HICOLLIE_SUCCESS 0 - 成功。
211
212HICOLLIE_WRONG_THREAD_CONTEXT 29800001 - 调用线程错误。无法从主线程调用该函数。
213
214
215### OH_HiCollie_Report()
216
217```
218HiCollie_ErrorCode OH_HiCollie_Report (bool * isSixSecond)
219```
220**描述**
221用于上报应用业务线程卡死事件，生成超时故障日志，辅助定位应用超时问题。
222
223结合OH_HiCollie_Init_StuckDetection接口配套使用，先初始化卡死检测，出现卡死时，再上报事件。
224
225**起始版本：** 12
226
227**参数:**
228
229| 名称 | 描述 |
230| -------- | -------- |
231| isSixSecond | 布尔指针。布尔指针的值。如果卡住6秒，则为真。如果卡住3秒，则为False。  |
232
233**返回：**
234
235HICOLLIE_SUCCESS 0 - 成功。
236
237HICOLLIE_INVALID_ARGUMENT 401 - 开始函数和结束函数两者都必须有值或为空，否则将返回该错误值。
238
239HICOLLIE_WRONG_THREAD_CONTEXT 29800001 - 调用线程错误。无法从主线程调用该函数。
240
241HICOLLIE_REMOTE_FAILED 29800002 - 远程调用错误。
242