1# hicollie.h 2 3## 概述 4 5HiCollie模块对外提供检测业务线程卡死、卡顿，以及上报卡死事件的能力。 6 7**引用文件：** <hicollie/hicollie.h> 8 9**库：** libohhicollie.so 10 11**系统能力：** SystemCapability.HiviewDFX.HiCollie 12 13**起始版本：** 12 14 15**相关模块：** [HiCollie](capi-hicollie.md) 16 17## 汇总 18 19### 结构体 20 21| 名称 | typedef关键字 | 描述 | 22| -- | -- | -- | 23| [HiCollie_DetectionParam](capi-hicollie-hicollie-detectionparam.md) | HiCollie_DetectionParam | 检测业务线程卡顿的相关参数。请注意，API 12及以上支持。 | 24| [HiCollie_SetTimerParam](capi-hicollie-hicollie-settimerparam.md) | HiCollie_SetTimerParam | 定义OH_HiCollie_SetTimer函数的输入参数。 | 25 26### 枚举 27 28| 名称 | typedef关键字 | 描述 | 29| -- | -- | -- | 30| [HiCollie_ErrorCode](#hicollie_errorcode) | HiCollie_ErrorCode | 错误码定义。 | 31| [HiCollie_Flag](#hicollie_flag) | HiCollie_Flag | 定义函数执行超时时发生的动作。 | 32 33### 函数 34 35| 名称 | typedef关键字 | 描述 | 36| -- | -- | -- | 37| [typedef void (\*OH_HiCollie_Task)(void)](#oh_hicollie_task) | OH_HiCollie_Task | 在业务线程卡死检测中，通过实现该函数来检测业务线程是否卡住。<br> HiCollie将在独立线程中每3秒调用一次该函数。<br> 例如：该函数可实现向业务线程发送消息，在业务线程接收到消息之后，设置一个标记，检查这个标记，确定业务线程是否卡住。 | 38| [typedef void (\*OH_HiCollie_BeginFunc)(const char* eventName)](#oh_hicollie_beginfunc) | OH_HiCollie_BeginFunc | 卡顿检测中,函数用于记录业务线程处理事件的开始时间。<br> 检查处理事件的执行时间，HiCollie将检查每个事件的持续时间。如果超过预设阈值，上报jank事件。<br> 该函数是在每个事件处理之前插入的回调函数。 | 39| [typedef void (\*OH_HiCollie_EndFunc)(const char* eventName)](#oh_hicollie_endfunc) | OH_HiCollie_EndFunc | 卡顿检测中, 该函数用于检测业务线程处理事件是否卡顿。<br> 检查处理事件的执行时间，HiCollie将检查每个事件的持续时间。如果超过预设阈值，上报jank事件。<br> 该函数是在每个事件处理之后插入的回调函数。 | 40| [HiCollie_ErrorCode OH_HiCollie_Init_StuckDetection(OH_HiCollie_Task task)](#oh_hicollie_init_stuckdetection) | - | 注册应用业务线程卡死的周期性检测任务。用户实现回调函数, 用于定时检测业务线程卡死情况。<br> 默认检测时间：3s上报BUSSINESS_THREAD_BLOCK_3S告警事件，6s上报BUSSINESS_THREAD_BLOCK_6S卡死事件。 | 41| [HiCollie_ErrorCode OH_HiCollie_Init_StuckDetectionWithTimeout(OH_HiCollie_Task task, uint32_t stuckTimeout)](#oh_hicollie_init_stuckdetectionwithtimeout) | - | 注册应用业务线程卡死的周期性检测任务。用户实现回调函数, 用于定时检测业务线程卡死情况。<br> 开发者可以设置卡死检测时间，可设置的时间范围：[3, 15]，单位：秒。 | 42| [HiCollie_ErrorCode OH_HiCollie_Init_JankDetection(OH_HiCollie_BeginFunc* beginFunc,OH_HiCollie_EndFunc* endFunc, HiCollie_DetectionParam param)](#oh_hicollie_init_jankdetection) | - | 注册应用业务线程卡顿检测的回调函数。<br> 线程卡顿监控功能需要开发者实现两个卡顿检测回调函数, 分别放在业务线程处理事件的前后。作为插桩函数，监控业务线程处理事件执行情况。 | 43| [HiCollie_ErrorCode OH_HiCollie_Report(bool* isSixSecond)](#oh_hicollie_report) | - | 上报应用业务线程卡死事件，生成卡死故障日志，辅助定位应用卡死问题。<br> 先调用OH_HiCollie_Init_StuckDetection或OH_HiCollie_Init_StuckDetectionWithTimeout接口，初始化检测的task；<br> 如果task任务超时，结合业务逻辑，调用OH_HiCollie_Report接口上报卡死事件。 | 44| [typedef void (\*OH_HiCollie_Callback)(void*)](#oh_hicollie_callback) | OH_HiCollie_Callback | 当用户调用[OH_HiCollie_SetTimer](capi-hicollie-h.md#oh_hicollie_settimer)后，未在其自定义的任务超时时间阈值内调用[OH_HiCollie_CancelTimer](capi-hicollie-h.md#oh_hicollie_canceltimer)，回调函数将被执行。 | 45| [HiCollie_ErrorCode OH_HiCollie_SetTimer(HiCollie_SetTimerParam param, int *id)](#oh_hicollie_settimer) | - | 注册定时器，用于检测函数或代码块执行是否超过自定义时间。<br> 结合OH_HiCollie_CancelTimer接口配套使用，应在调用耗时的函数之前使用。 | 46| [void OH_HiCollie_CancelTimer(int id)](#oh_hicollie_canceltimer) | - | 取消定时器。<br> 结合OH_HiCollie_SetTimer接口配套使用，执行函数或代码块后使用，OH_HiCollie_CancelTimer通过id将该任务取消；<br> 若未在自定义时间内取消，则执行回调函数，在特定自定义超时动作下，生成故障日志。 | 47 48## 枚举类型说明 49 50### HiCollie_ErrorCode 51 52``` 53enum HiCollie_ErrorCode 54``` 55 56**描述** 57 58错误码定义。 59 60**起始版本：** 12 61 62| 枚举项 | 描述 | 63| -- | -- | 64| HICOLLIE_SUCCESS = 0 | 成功。 | 65| HICOLLIE_INVALID_ARGUMENT = 401 | 无效参数。 | 66| HICOLLIE_WRONG_THREAD_CONTEXT = 29800001 | 调用线程错误。 | 67| HICOLLIE_REMOTE_FAILED = 29800002 | 远程调用错误。 | 68| HICOLLIE_INVALID_TIMER_NAME = 29800003 | 无效的函数执行超时检测器名称。<br>**起始版本：** 18 | 69| HICOLLIE_INVALID_TIMEOUT_VALUE = 29800004 | 无效的函数执行超时时间阈值。<br>**起始版本：** 18 | 70| HICOLLIE_WRONG_PROCESS_CONTEXT = 29800005 | 函数执行超时检测接入进程错误。<br>**起始版本：** 18 | 71| HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM = 29800006 | 用于保存返回的计时器id的指针不应为NULL。<br>**起始版本：** 18 | 72 73### HiCollie_Flag 74 75``` 76enum HiCollie_Flag 77``` 78 79**描述** 80 81定义函数执行超时时发生的动作。 82 83**起始版本：** 18 84 85| 枚举项 | 描述 | 86| -- | -- | 87| HICOLLIE_FLAG_DEFAULT = (~0) | 默认动作，生成日志及查杀恢复。 | 88| HICOLLIE_FLAG_NOOP = (0) | 仅执行回调函数。 | 89| HICOLLIE_FLAG_LOG = (1 << 0) | 生成日志。 | 90| HICOLLIE_FLAG_RECOVERY = (1 << 1) | 执行查杀恢复。 | 91 92 93## 函数说明 94 95### OH_HiCollie_Task() 96 97``` 98typedef void (*OH_HiCollie_Task)(void) 99``` 100 101**描述** 102 103在业务线程卡死检测中，通过实现该函数来检测业务线程是否卡住。<br> HiCollie将在独立线程中每3秒调用一次该函数。<br> 例如：该函数可实现向业务线程发送消息，在业务线程接收到消息之后，设置一个标记，检查这个标记，确定业务线程是否卡住。 104 105**起始版本：** 12 106 107### OH_HiCollie_BeginFunc() 108 109``` 110typedef void (*OH_HiCollie_BeginFunc)(const char* eventName) 111``` 112 113**描述** 114 115卡顿检测中,函数用于记录业务线程处理事件的开始时间。<br> 检查处理事件的执行时间，HiCollie将检查每个事件的持续时间。如果超过预设阈值，上报jank事件。<br> 该函数是在每个事件处理之前插入的回调函数。 116 117**起始版本：** 12 118 119 120**参数：** 121 122| 参数项 | 描述 | 123| -- | -- | 124| const char* eventName | 业务线程处理事件的名字。 | 125 126### OH_HiCollie_EndFunc() 127 128``` 129typedef void (*OH_HiCollie_EndFunc)(const char* eventName) 130``` 131 132**描述** 133 134卡顿检测中, 该函数用于检测业务线程处理事件是否卡顿。<br> 检查处理事件的执行时间，HiCollie将检查每个事件的持续时间。如果超过预设阈值，上报jank事件。<br> 该函数是在每个事件处理之后插入的回调函数。 135 136**起始版本：** 12 137 138 139**参数：** 140 141| 参数项 | 描述 | 142| -- | -- | 143| const char* eventName | 业务线程处理事件的名字。 | 144 145### OH_HiCollie_Init_StuckDetection() 146 147``` 148HiCollie_ErrorCode OH_HiCollie_Init_StuckDetection(OH_HiCollie_Task task) 149``` 150 151**描述** 152 153注册应用业务线程卡死的周期性检测任务。用户实现回调函数, 用于定时检测业务线程卡死情况。<br> 默认检测时间：3s上报BUSSINESS_THREAD_BLOCK_3S告警事件，6s上报BUSSINESS_THREAD_BLOCK_6S卡死事件。 154 155**起始版本：** 12 156 157 158**参数：** 159 160| 参数项 | 描述 | 161| -- | -- | 162| [OH_HiCollie_Task](capi-hicollie-h.md#oh_hicollie_task) task | 每3秒执行一次的周期性检测任务，用于检测业务线程是否卡住。 | 163 164**返回：** 165 166| 类型 | 说明 | 167| -- | -- | 168| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - 成功。<br> [HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - 调用线程错误。在非主线程中调用该函数。<br> 具体可参考[HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode)。 | 169 170### OH_HiCollie_Init_StuckDetectionWithTimeout() 171 172``` 173HiCollie_ErrorCode OH_HiCollie_Init_StuckDetectionWithTimeout(OH_HiCollie_Task task, uint32_t stuckTimeout) 174``` 175 176**描述** 177 178注册应用业务线程卡死的周期性检测任务。用户实现回调函数, 用于定时检测业务线程卡死情况。<br> 开发者可以设置卡死检测时间，可设置的时间范围：[3, 15]，单位：秒。 179 180**起始版本：** 18 181 182 183**参数：** 184 185| 参数项 | 描述 | 186| -- | -- | 187| [OH_HiCollie_Task](capi-hicollie-h.md#oh_hicollie_task) task | 每stuckTimeout时间执行一次的周期性检测任务，用于检测业务线程是否卡住。 | 188| uint32_t stuckTimeout | 检测业务线程卡死时间。任务执行超过stuckTimeout时间上报卡死告警事件；任务超过stuckTimeout * 2时间上报卡死事件。<br> 单位：s。规定：最大值15s，最小值3s。 | 189 190**返回：** 191 192| 类型 | 说明 | 193| -- | -- | 194| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - 成功。<br> [HICOLLIE_INVALID_ARGUMENT](capi-hicollie-h.md#hicollie_errorcode) 401 - 卡死检测时间设置错误。<br> [HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - 调用线程错误。在非主线程中调用该函数。<br> 具体可参考[HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode)。 | 195 196### OH_HiCollie_Init_JankDetection() 197 198``` 199HiCollie_ErrorCode OH_HiCollie_Init_JankDetection(OH_HiCollie_BeginFunc* beginFunc,OH_HiCollie_EndFunc* endFunc, HiCollie_DetectionParam param) 200``` 201 202**描述** 203 204注册应用业务线程卡顿检测的回调函数。<br> 线程卡顿监控功能需要开发者实现两个卡顿检测回调函数, 分别放在业务线程处理事件的前后。作为插桩函数，监控业务线程处理事件执行情况。 205 206**起始版本：** 12 207 208 209**参数：** 210 211| 参数项 | 描述 | 212| -- | -- | 213| [OH_HiCollie_BeginFunc](capi-hicollie-h.md#oh_hicollie_beginfunc)* beginFunc | 检测业务线程处理事件前的函数。 | 214| [OH_HiCollie_EndFunc](capi-hicollie-h.md#oh_hicollie_endfunc)* endFunc | 检测业务线程处理事件后的函数。 | 215| [HiCollie_DetectionParam](capi-hicollie-hicollie-detectionparam.md) param | 扩展参数以供将来使用。 | 216 217**返回：** 218 219| 类型 | 说明 | 220| -- | -- | 221| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - 成功。<br> [HICOLLIE_INVALID_ARGUMENT](capi-hicollie-h.md#hicollie_errorcode) 401 - 开始函数和结束函数两者都必须有值或为空，否则将返回该错误值。<br> [HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - 调用线程错误。在非主线程中调用该函数。<br> 具体可参考[HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode)。 | 222 223### OH_HiCollie_Report() 224 225``` 226HiCollie_ErrorCode OH_HiCollie_Report(bool* isSixSecond) 227``` 228 229**描述** 230 231上报应用业务线程卡死事件，生成卡死故障日志，辅助定位应用卡死问题。<br> 先调用OH_HiCollie_Init_StuckDetection或OH_HiCollie_Init_StuckDetectionWithTimeout接口，初始化检测的task；<br> 如果task任务超时，结合业务逻辑，调用OH_HiCollie_Report接口上报卡死事件。 232 233**起始版本：** 12 234 235 236**参数：** 237 238| 参数项 | 描述 | 239| -- | -- | 240| bool* isSixSecond | 布尔指针。布尔指针的值。如果卡住6秒，则为真。如果卡住3秒，则为False。 | 241 242**返回：** 243 244| 类型 | 说明 | 245| -- | -- | 246| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - 成功。<br> [HICOLLIE_INVALID_ARGUMENT](capi-hicollie-h.md#hicollie_errorcode) 401 - 开始函数和结束函数两者都必须有值或为空，否则将返回该错误值。<br> [HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - 调用线程错误。在非主线程中调用该函数。<br> [HICOLLIE_REMOTE_FAILED](capi-hicollie-h.md#hicollie_errorcode) 29800002 - 远程调用错误。请求IPC远程服务失败。<br> 具体可参考[HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode)。 | 247 248### OH_HiCollie_Callback() 249 250``` 251typedef void (*OH_HiCollie_Callback)(void*) 252``` 253 254**描述** 255 256当用户调用[OH_HiCollie_SetTimer](capi-hicollie-h.md#oh_hicollie_settimer)后，未在其自定义的任务超时时间阈值内调用[OH_HiCollie_CancelTimer](capi-hicollie-h.md#oh_hicollie_canceltimer)，回调函数将被执行。 257 258**起始版本：** 18 259 260### OH_HiCollie_SetTimer() 261 262``` 263HiCollie_ErrorCode OH_HiCollie_SetTimer(HiCollie_SetTimerParam param, int *id) 264``` 265 266**描述** 267 268注册定时器，用于检测函数或代码块执行是否超过自定义时间。<br> 结合OH_HiCollie_CancelTimer接口配套使用，应在调用耗时的函数之前使用。 269 270**起始版本：** 18 271 272 273**参数：** 274 275| 参数项 | 描述 | 276| -- | -- | 277| [HiCollie_SetTimerParam](capi-hicollie-hicollie-settimerparam.md) param | 定义输入参数。 | 278| int *id | 用于保存返回的计时器id的指针，它不应为NULL。 | 279 280**返回：** 281 282| 类型 | 说明 | 283| -- | -- | 284| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - 成功。<br> [HICOLLIE_INVALID_TIMER_NAME](capi-hicollie-h.md#hicollie_errorcode) 29800003 - 无效的计时器名称，不应为NULL或空字符串。<br> [HICOLLIE_INVALID_TIMEOUT_VALUE](capi-hicollie-h.md#hicollie_errorcode) 29800004 - 无效的超时值。<br> [HICOLLIE_WRONG_PROCESS_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800005 - 无效的接入检测进程上下文，appspawn与nativespawn进程中不可调用。<br> [HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM](capi-hicollie-h.md#hicollie_errorcode) 29800006 - 用于保存返回的计时器id的指针，不应该为NULL。<br> 具体可参考[HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode)。 | 285 286### OH_HiCollie_CancelTimer() 287 288``` 289void OH_HiCollie_CancelTimer(int id) 290``` 291 292**描述** 293 294取消定时器。<br> 结合OH_HiCollie_SetTimer接口配套使用，执行函数或代码块后使用，OH_HiCollie_CancelTimer通过id将该任务取消；<br> 若未在自定义时间内取消，则执行回调函数，在特定自定义超时动作下，生成故障日志。 295 296**起始版本：** 18 297 298 299**参数：** 300 301| 参数项 | 描述 | 302| -- | -- | 303| int id | 执行[OH_HiCollie_SetTimer](capi-hicollie-h.md#oh_hicollie_settimer)函数后更新的计时器id。 | 304 305 306