1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef HIVIEWDFX_HICOLLIE_H 17 #define HIVIEWDFX_HICOLLIE_H 18 19 /** 20 * @addtogroup HiCollie 21 * @{ 22 * 23 * @brief Provides the ability to detect thread stuck or jank of your own business thread 24 * pls note it should not be the same as main thread. 25 * 26 * You can use it in these two scenario: 27 * (1)The Business thread stuck for 6 seconds; 28 * (2)The Business thread jank for a short time，usually it is less than one second. 29 * 30 * @since 12 31 */ 32 33 /** 34 * @file hicollie.h 35 * 36 * @brief Defines the interface of the HiCollie module. 37 * 38 * @library libohhicollie.so 39 * @kit PerformanceAnalysisKit 40 * @syscap SystemCapability.HiviewDFX.HiCollie 41 * @since 12 42 */ 43 44 #include <time.h> 45 #include <stdint.h> 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif // __cplusplus 50 51 /** 52 * @brief Defines error code 53 * 54 * @since 12 55 */ 56 typedef enum HiCollie_ErrorCode { 57 /** Success */ 58 HICOLLIE_SUCCESS = 0, 59 /** Invalid argument */ 60 HICOLLIE_INVALID_ARGUMENT = 401, 61 /** Wrong thread context */ 62 HICOLLIE_WRONG_THREAD_CONTEXT = 29800001, 63 /** Remote call failed */ 64 HICOLLIE_REMOTE_FAILED = 29800002, 65 } HiCollie_ErrorCode; 66 67 /** 68 * @brief In stuck scenario, you need to implement this function to detect whether your business thread is stuck. 69 * HiCollie will call this function every 3 seconds in an independent thread. 70 * A possible implementation of this function is to send a message to your business thread. 71 * After the business thread receives it, it will set a flag, 72 * by checking the flag you can know whether the business thread is stuck or not. 73 * 74 * @since 12 75 */ 76 typedef void (*OH_HiCollie_Task)(void); 77 78 /** 79 * @brief In jank scenario, you need to insert two stub functions before and after 80 * each event processing of your business thread. 81 * By checking these two function executing timestamp, HiCollie will know cosuming time for every event. 82 * If it exceeds the preset threshold, a jank event will be reported. 83 * This is the stub function inserted before each event processing. 84 * 85 * @param eventName Business thread processing event name. 86 * @since 12 87 */ 88 typedef void (*OH_HiCollie_BeginFunc)(const char* eventName); 89 90 /** 91 * @brief In jank scenario, you need to insert two stub functions before and after 92 * each event processing of your business thread. 93 * By checking these two function executing timestamp, HiCollie will know cosuming time for every event. 94 * If it exceeds the preset threshold, a jank event will be reported. 95 * This is the stub function inserted after each event processing. 96 * 97 * @param eventName Business thread processing event name. 98 * @since 12 99 */ 100 typedef void (*OH_HiCollie_EndFunc)(const char* eventName); 101 102 /** 103 * @brief Parameters used for jank detection. 104 * Pls note these parameters is not valid for API 12, it is only used for future extention. 105 * 106 * @since 12 107 */ 108 typedef struct HiCollie_DetectionParam { 109 /** In jank scenario, it's the theshold exceed which sample stack will be collected. */ 110 int sampleStackTriggerTime; 111 /** extended parameter for future use. */ 112 int reserved; 113 } HiCollie_DetectionParam; 114 115 /** 116 * @brief Set up periodic tasks for stuck detection. 117 * 118 * @param task Periodic task executed every 3 seconds. 119 * @return {@link HICOLLIE_SUCCESS} 0 - Success. 120 * {@link HICOLLIE_WRONG_THREAD_CONTEXT} 29800001 - Wrong thread context. 121 * The function can not be called from main thread. 122 * @since 12 123 */ 124 HiCollie_ErrorCode OH_HiCollie_Init_StuckDetection(OH_HiCollie_Task task); 125 126 /** 127 * @brief Set up stub functions for jank detection. 128 * 129 * @param beginFunc The stub function before each event processing. 130 * @param endFunc The stub function after each event processing. 131 * @param param The parameter for jank detection setting. 132 * @return {@link HICOLLIE_SUCCESS} 0 - Success. 133 * {@link HICOLLIE_INVALID_ARGUMENT} 401 - beginFunc and endFunc 134 * must both have values or be empty, otherwise the value will be returned. 135 * {@link HICOLLIE_WRONG_THREAD_CONTEXT} 29800001 - Wrong thread context. 136 * The function can not be called from main thread. 137 * @since 12 138 */ 139 HiCollie_ErrorCode OH_HiCollie_Init_JankDetection(OH_HiCollie_BeginFunc* beginFunc, 140 OH_HiCollie_EndFunc* endFunc, HiCollie_DetectionParam param); 141 142 /** 143 * @brief Report a stuck event. 144 * 145 * @param isSixSecond boolean pointer. 146 * The value of the boolean pointer.True if it is stuck for 6 seconds. False if it is stuck for 3 seconds. 147 * @return {@link HICOLLIE_SUCCESS} 0 - Success. 148 * {@link HICOLLIE_INVALID_ARGUMENT} 401 - if isSixSecond is nullptr. 149 * {@link HICOLLIE_WRONG_THREAD_CONTEXT} 29800001 - Wrong thread context. 150 * The function can only be called from hicollie internal monitor thread 151 * where {@link OH_HiCollie_Task} run on. 152 * {@link HICOLLIE_REMOTE_FAILED} 29800002 - Remote call failed. 153 * @since 12 154 */ 155 HiCollie_ErrorCode OH_HiCollie_Report(bool* isSixSecond); 156 157 #ifdef __cplusplus 158 } 159 #endif 160 /** @} */ 161 162 #endif // HIVIEWDFX_HICOLLIE_H 163