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| struct [HiCollie_DetectionParam](_hi_collie___detection_param.md) | 检测业务线程卡顿的相关参数。请注意，API 12及以上支持。 | 33| struct [HiCollie_SetTimerParam](_hi_collie___set_timer_param.md) | 定义OH_HiCollie_SetTimer函数的输入参数。 | 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) | 卡顿检测中,函数用于记录业务线程处理事件的开始时间。<br/>检查处理事件的执行时间，HiCollie将检查每个事件的持续时间。如果超过预设阈值，上报jank事件。<br/>该函数是在每个事件处理之前插入的回调函数。 | 43| typedef void(\* [OH_HiCollie_EndFunc](#oh_hicollie_endfunc)) (const char \*eventName) | 卡顿检测中, 该函数用于检测业务线程处理事件是否卡顿。<br/>检查处理事件的执行时间，HiCollie将检查每个事件的持续时间。如果超过预设阈值，上报jank事件。<br/>该函数是在每个事件处理之后插入的回调函数。 | 44| typedef struct [HiCollie_DetectionParam](_hi_collie___detection_param.md) [HiCollie_DetectionParam](#hicollie_detectionparam) | 检测业务线程卡顿的相关参数。请注意，API 12及以上支持。 | 45| typedef void(\* [OH_HiCollie_Callback](#oh_hicollie_callback)) (void \*) | 当用户调用[OH_HiCollie_SetTimer](#oh_hicollie_settimer)后，未在其自定义的任务超时时间阈值内调用[OH_HiCollie_CancelTimer](#oh_hicollie_canceltimer)，回调函数将被执行。 | 46| typedef enum [HiCollie_Flag](#hicollie_flag) [HiCollie_Flag](#hicollie_flag) | 定义函数执行超时时发生的动作。 | 47| typedef struct [HiCollie_SetTimerParam](_hi_collie___set_timer_param.md)[HiCollie_SetTimerParam](#hicollie_settimerparam) | 定义OH_HiCollie_SetTimer函数的输入参数。 | 48 49 50### 枚举 51 52| 名称 | 描述 | 53| -------- | -------- | 54| [HiCollie_ErrorCode](#hicollie_errorcode) {<br/>HICOLLIE_SUCCESS = 0, <br/>HICOLLIE_INVALID_ARGUMENT = 401, <br/>HICOLLIE_WRONG_THREAD_CONTEXT = 29800001, <br/>HICOLLIE_REMOTE_FAILED = 29800002, <br/>HICOLLIE_INVALID_TIMER_NAME = 29800003, <br/>HICOLLIE_INVALID_TIMEOUT_VALUE = 29800004, <br/>HICOLLIE_WRONG_PROCESS_CONTEXT = 29800005, <br/>HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM = 29800006<br/>} | 错误码定义。 | 55| [HiCollie_Flag](#hicollie_flag) {<br/>HICOLLIE_FLAG_DEFAULT = (~0), <br/>HICOLLIE_FLAG_NOOP = (0), <br/>HICOLLIE_FLAG_LOG = (1 << 0), <br/>HICOLLIE_FLAG_RECOVERY = (1 << 1)<br/>} | 定义函数执行超时时发生的动作。 | 56 57 58### 函数 59 60| 名称 | 描述 | 61| -------- | -------- | 62| [HiCollie_ErrorCode](#hicollie_errorcode) [OH_HiCollie_Init_StuckDetection](#oh_hicollie_init_stuckdetection) ([OH_HiCollie_Task](#oh_hicollie_task) task) | 注册应用业务线程卡死的周期性检测任务。用户实现回调函数, 用于定时检测业务线程卡死情况。<br/>默认检测时间：3s上报BUSSINESS_THREAD_BLOCK_3S告警事件，6s上报BUSSINESS_THREAD_BLOCK_6S卡死事件。 | 63| [HiCollie_ErrorCode](#hicollie_errorcode) [OH_HiCollie_Init_StuckDetectionWithTimeout](#oh_hicollie_init_stuckdetectionwithtimeout) ([OH_HiCollie_Task](#oh_hicollie_task) task, uint32_t stuckTimeout) | 注册应用业务线程卡死的周期性检测任务。用户实现回调函数, 用于定时检测业务线程卡死情况。<br/>开发者可以设置卡死检测时间，可设置的时间范围：[3, 15]，单位：秒。 | 64| [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/>线程卡顿监控功能需要开发者实现两个卡顿检测回调函数, 分别放在业务线程处理事件的前后。作为插桩函数，监控业务线程处理事件执行情况。 | 65| [HiCollie_ErrorCode](#hicollie_errorcode) [OH_HiCollie_Report](#oh_hicollie_report) (bool \*isSixSecond) | 上报应用业务线程卡死事件，生成卡死故障日志，辅助定位应用卡死问题。<br/>先调用OH_HiCollie_Init_StuckDetection或OH_HiCollie_Init_StuckDetectionWithTimeout接口，初始化检测的task；<br/>如果task任务超时，结合业务逻辑，调用OH_HiCollie_Report接口上报卡死事件。 | 66| [HiCollie_ErrorCode](#hicollie_errorcode) [OH_HiCollie_SetTimer](#oh_hicollie_settimer) ([HiCollie_SetTimerParam](_hi_collie___set_timer_param.md) param, int \*id) | 注册定时器，用于检测函数或代码块执行是否超过自定义时间。<br/>结合OH_HiCollie_CancelTimer接口配套使用，应在调用耗时的函数之前使用。 | 67| void [OH_HiCollie_CancelTimer](#oh_hicollie_canceltimer) (int id) | 取消定时器。<br/>结合OH_HiCollie_SetTimer接口配套使用，执行函数或代码块后使用，OH_HiCollie_CancelTimer通过id将该任务取消；<br/>若未在自定义时间内取消，则执行回调函数，在特定自定义超时动作下，生成故障日志。 | 68 69 70## 类型定义说明 71 72 73### HiCollie_DetectionParam 74 75``` 76typedef struct HiCollie_DetectionParam HiCollie_DetectionParam 77``` 78**描述** 79检测业务线程卡顿的相关参数。请注意，API 12及以上支持。 80 81**起始版本：** 12 82 83 84### HiCollie_ErrorCode 85 86``` 87typedef enum HiCollie_ErrorCode HiCollie_ErrorCode 88``` 89**描述** 90错误码定义。 91 92**起始版本：** 12 93 94 95### HiCollie_Flag 96 97``` 98typedef enum HiCollie_Flag HiCollie_Flag 99``` 100**描述** 101定义函数执行超时时发生的动作。 102 103**起始版本：** 18 104 105 106### HiCollie_SetTimerParam 107 108``` 109typedef struct HiCollie_SetTimerParam HiCollie_SetTimerParam 110``` 111**描述** 112定义OH_HiCollie_SetTimer函数的输入参数。 113 114**起始版本：** 18 115 116 117### OH_HiCollie_BeginFunc 118 119``` 120typedef void (*OH_HiCollie_BeginFunc)(const char* eventName) 121``` 122**描述** 123卡顿检测中,函数用于记录业务线程处理事件的开始时间。 124 125检查处理事件的执行时间，HiCollie将检查每个事件的持续时间。如果超过预设阈值，上报jank事件。 126 127该函数是在每个事件处理之前插入的回调函数。 128 129**起始版本：** 12 130 131**参数：** 132 133| 名称 | 描述 | 134| -------- | -------- | 135| eventName | 业务线程处理事件的名字。 | 136 137 138### OH_HiCollie_Callback 139 140``` 141typedef void(* OH_HiCollie_Callback) (void *) 142``` 143**描述** 144当用户调用[OH_HiCollie_SetTimer](#oh_hicollie_settimer)后，未在其自定义的任务超时时间阈值内调用[OH_HiCollie_CancelTimer](#oh_hicollie_canceltimer)，回调函数将被执行。 145 146**起始版本：** 18 147 148 149### OH_HiCollie_EndFunc 150 151``` 152typedef void(* OH_HiCollie_EndFunc) (const char *eventName) 153``` 154**描述** 155卡顿检测中, 该函数用于检测业务线程处理事件是否卡顿。 156 157检查处理事件的执行时间，HiCollie将检查每个事件的持续时间。如果超过预设阈值，上报jank事件。 158 159该函数是在每个事件处理之后插入的回调函数。 160 161**起始版本：** 12 162 163**参数：** 164 165| 名称 | 描述 | 166| -------- | -------- | 167| eventName | 业务线程处理事件的名字。 | 168 169 170### OH_HiCollie_Task 171 172``` 173typedef void(* OH_HiCollie_Task) (void) 174``` 175**描述** 176在业务线程卡死检测中，通过实现该函数来检测业务线程是否卡住。 177 178HiCollie将在独立线程中每3秒调用一次该函数。 179 180例如：该函数可实现向业务线程发送消息，在业务线程接收到消息之后，设置一个标记，检查这个标记，确定业务线程是否卡住。 181 182**起始版本：** 12 183 184 185## 枚举类型说明 186 187 188### HiCollie_ErrorCode 189 190``` 191enum HiCollie_ErrorCode 192``` 193**描述** 194错误码定义。 195 196**起始版本：** 12 197 198| 枚举值 | 描述 | 199| -------- | -------- | 200| HICOLLIE_SUCCESS | 成功。| 201| HICOLLIE_INVALID_ARGUMENT | 无效参数。可能的原因：1. 参数传值问题；2. 参数类型问题。| 202| HICOLLIE_WRONG_THREAD_CONTEXT | 检测的线程错误：在业务线程中调用。| 203| HICOLLIE_REMOTE_FAILED | 远程调用错误。 | 204| HICOLLIE_INVALID_TIMER_NAME | 无效的函数执行超时检测器名称。<br/>**起始版本：** 18 | 205| HICOLLIE_INVALID_TIMEOUT_VALUE | 无效的函数执行超时时间阈值。<br/>**起始版本：** 18 | 206| HICOLLIE_WRONG_PROCESS_CONTEXT | 函数执行超时检测接入进程错误。<br/>**起始版本：** 18 | 207| HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM | 用于保存返回的计时器id的指针不应为NULL。<br/>**起始版本：** 18 | 208 209### HiCollie_Flag 210 211``` 212enum HiCollie_Flag 213``` 214**描述** 215定义函数执行超时时发生的动作。 216 217**起始版本：** 18 218 219| 枚举值 | 描述 | 220| -------- | -------- | 221| HICOLLIE_FLAG_DEFAULT | 默认动作，生成日志及查杀恢复。 | 222| HICOLLIE_FLAG_NOOP | 仅执行回调函数。 | 223| HICOLLIE_FLAG_LOG | 生成日志。 | 224| HICOLLIE_FLAG_RECOVERY | 执行查杀恢复。 | 225 226 227## 函数说明 228 229 230### OH_HiCollie_CancelTimer() 231 232``` 233void OH_HiCollie_CancelTimer(int id) 234``` 235**描述** 236取消定时器。 237 238结合OH_HiCollie_SetTimer接口配套使用，执行函数或代码块后使用，OH_HiCollie_CancelTimer通过id将该任务取消； 239 240若未在自定义时间内取消，则执行回调函数，在特定自定义超时动作下，生成故障日志。 241 242**起始版本：** 18 243 244**参数：** 245 246| 名称 | 描述 | 247| -------- | -------- | 248| id | 执行[OH_HiCollie_SetTimer](#oh_hicollie_settimer)函数后更新的计时器id。 | 249 250 251### OH_HiCollie_Init_JankDetection() 252 253``` 254HiCollie_ErrorCode OH_HiCollie_Init_JankDetection (OH_HiCollie_BeginFunc * beginFunc, OH_HiCollie_EndFunc * endFunc, HiCollie_DetectionParam param ) 255``` 256**描述** 257注册应用业务线程卡顿检测的回调函数。 258 259线程卡顿监控功能需要开发者实现两个卡顿检测回调函数, 分别放在业务线程处理事件的前后。作为插桩函数，监控业务线程处理事件执行情况。 260 261**起始版本：** 12 262 263**参数：** 264 265| 名称 | 描述 | 266| -------- | -------- | 267| beginFunc | 检测业务线程处理事件前的函数。 | 268| endFunc | 检测业务线程处理事件后的函数。 | 269| param | 扩展参数以供将来使用。 | 270 271**返回：** 272 273HICOLLIE_SUCCESS 0 - 成功。 274 275HICOLLIE_INVALID_ARGUMENT 401 - 开始函数和结束函数两者都必须有值或为空，否则将返回该错误值。 276 277HICOLLIE_WRONG_THREAD_CONTEXT 29800001 - 调用线程错误。在非主线程中调用该函数。 278 279具体可参考[HiCollie_ErrorCode](#hicollie_errorcode)。 280 281 282### OH_HiCollie_Init_StuckDetection() 283 284``` 285HiCollie_ErrorCode OH_HiCollie_Init_StuckDetection (OH_HiCollie_Task task) 286``` 287**描述** 288注册应用业务线程卡死的周期性检测任务。用户实现回调函数, 用于定时检测业务线程卡死情况。 289 290默认检测时间：3s上报BUSSINESS_THREAD_BLOCK_3S告警事件，6s上报BUSSINESS_THREAD_BLOCK_6S卡死事件。 291 292**起始版本：** 12 293 294**参数：** 295 296| 名称 | 描述 | 297| -------- | -------- | 298| task | 每3秒执行一次的周期性检测任务，用于检测业务线程是否卡住。 | 299 300**返回：** 301 302HICOLLIE_SUCCESS 0 - 成功。 303 304HICOLLIE_WRONG_THREAD_CONTEXT 29800001 - 调用线程错误。在非主线程中调用该函数。 305 306具体可参考[HiCollie_ErrorCode](#hicollie_errorcode)。 307 308 309### OH_HiCollie_Init_StuckDetectionWithTimeout() 310 311``` 312HiCollie_ErrorCode OH_HiCollie_Init_StuckDetectionWithTimeout (OH_HiCollie_Task task, uint32_t stuckTimeout ) 313``` 314**描述** 315注册应用业务线程卡死的周期性检测任务。用户实现回调函数, 用于定时检测业务线程卡死情况。 316 317开发者可以设置卡死检测时间，可设置的时间范围：[3, 15]，单位：秒。 318 319**起始版本：** 18 320 321**参数：** 322 323| 名称 | 描述 | 324| -------- | -------- | 325| task | 每stuckTimeout时间执行一次的周期性检测任务，用于检测业务线程是否卡住。 | 326| stuckTimeout | 检测业务线程卡死时间。任务执行超过stuckTimeout时间上报卡死告警事件；任务超过stuckTimeout \* 2时间上报卡死事件。<br/>单位：s。规定：最大值15s，最小值3s。 | 327 328**返回：** 329 330HICOLLIE_SUCCESS 0 - 成功。 331 332HICOLLIE_INVALID_ARGUMENT 401 - 卡死检测时间设置错误。 333 334HICOLLIE_WRONG_THREAD_CONTEXT 29800001 - 调用线程错误。在非主线程中调用该函数。 335 336具体可参考[HiCollie_ErrorCode](#hicollie_errorcode)。 337 338 339### OH_HiCollie_Report() 340 341``` 342HiCollie_ErrorCode OH_HiCollie_Report (bool * isSixSecond) 343``` 344**描述** 345上报应用业务线程卡死事件，生成卡死故障日志，辅助定位应用卡死问题。 346 347先调用OH_HiCollie_Init_StuckDetection或OH_HiCollie_Init_StuckDetectionWithTimeout接口，初始化检测的task； 348 349如果task任务超时，结合业务逻辑，调用OH_HiCollie_Report接口上报卡死事件。 350 351**起始版本：** 12 352 353**参数：** 354 355| 名称 | 描述 | 356| -------- | -------- | 357| isSixSecond | 布尔指针。布尔指针的值。如果卡住6秒，则为真。如果卡住3秒，则为False。 | 358 359**返回：** 360 361HICOLLIE_SUCCESS 0 - 成功。 362 363HICOLLIE_INVALID_ARGUMENT 401 - 开始函数和结束函数两者都必须有值或为空，否则将返回该错误值。 364 365HICOLLIE_WRONG_THREAD_CONTEXT 29800001 - 调用线程错误。在非主线程中调用该函数。 366 367HICOLLIE_REMOTE_FAILED 29800002 - 远程调用错误。请求IPC远程服务失败。 368 369具体可参考[HiCollie_ErrorCode](#hicollie_errorcode)。 370 371 372### OH_HiCollie_SetTimer() 373 374``` 375HiCollie_ErrorCode OH_HiCollie_SetTimer (HiCollie_SetTimerParam param, int * id ) 376``` 377**描述** 378注册定时器，用于检测函数或代码块执行是否超过自定义时间。 379 380结合OH_HiCollie_CancelTimer接口配套使用，应在调用耗时的函数之前使用。 381 382**起始版本：** 18 383 384**参数：** 385 386| 名称 | 描述 | 387| -------- | -------- | 388| param | 定义输入参数，参考[HiCollie_SetTimerParam](#hicollie_settimerparam) | 389| id | 用于保存返回的计时器id的指针，它不应为NULL。 | 390 391**返回：** 392 393HICOLLIE_SUCCESS 0 - 成功。 394 395HICOLLIE_INVALID_TIMER_NAME 29800003 - 无效的计时器名称，不应为NULL或空字符串。 396 397HICOLLIE_INVALID_TIMEOUT_VALUE 29800004 - 无效的超时值。 398 399HICOLLIE_WRONG_PROCESS_CONTEXT 29800005 - 无效的接入检测进程上下文，appspawn与nativespawn进程中不可调用。 400 401HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM 29800006 - 用于保存返回的计时器id的指针，不应该为NULL。 402 403具体可参考[HiCollie_ErrorCode](#hicollie_errorcode)。 404