1 /* 2 * Copyright (C) 2015 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * @addtogroup Tracing 19 * @{ 20 */ 21 22 /** 23 * @file trace.h 24 * @brief Writes trace events to the system trace buffer. 25 * 26 * These trace events can be collected and visualized using the Systrace tool. 27 * For information about using the Systrace tool, read <a href="https://developer.android.com/studio/profile/systrace.html">Analyzing UI Performance with Systrace</a>. 28 * 29 * Available since API level 23. 30 */ 31 32 #ifndef ANDROID_NATIVE_TRACE_H 33 #define ANDROID_NATIVE_TRACE_H 34 35 #include <stdbool.h> 36 #include <stdint.h> 37 #include <sys/cdefs.h> 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 #if __ANDROID_API__ >= 23 44 45 /** 46 * Returns true if tracing is enabled. Use this to avoid expensive computation only necessary 47 * when tracing is enabled. 48 * 49 * Available since API level 23. 50 */ 51 bool ATrace_isEnabled() __INTRODUCED_IN(23); 52 53 /** 54 * Writes a tracing message to indicate that the given section of code has begun. This call must be 55 * followed by a corresponding call to {@link ATrace_endSection} on the same thread. 56 * 57 * Note: At this time the vertical bar character '|' and newline character '\\n' are used internally 58 * by the tracing mechanism. If \p sectionName contains these characters they will be replaced with a 59 * space character in the trace. 60 * 61 * Available since API level 23. 62 */ 63 void ATrace_beginSection(const char* sectionName) __INTRODUCED_IN(23); 64 65 /** 66 * Writes a tracing message to indicate that a given section of code has ended. This call must be 67 * preceeded by a corresponding call to {@link ATrace_beginSection} on the same thread. Calling this method 68 * will mark the end of the most recently begun section of code, so care must be taken to ensure 69 * that {@link ATrace_beginSection}/{@link ATrace_endSection} pairs are properly nested and called from the same thread. 70 * 71 * Available since API level 23. 72 */ 73 void ATrace_endSection() __INTRODUCED_IN(23); 74 75 #endif /* __ANDROID_API__ >= 23 */ 76 77 #if __ANDROID_API__ >= __ANDROID_API_Q__ 78 79 /** 80 * Writes a trace message to indicate that a given section of code has 81 * begun. Must be followed by a call to {@link ATrace_endAsyncSection} with the same 82 * methodName and cookie. Unlike {@link ATrace_beginSection} and {@link ATrace_endSection}, 83 * asynchronous events do not need to be nested. The name and cookie used to 84 * begin an event must be used to end it. 85 * 86 * \param sectionName The method name to appear in the trace. 87 * \param cookie Unique identifier for distinguishing simultaneous events 88 */ 89 void ATrace_beginAsyncSection(const char* sectionName, int32_t cookie) __INTRODUCED_IN(29); 90 91 /** 92 * Writes a trace message to indicate that the current method has ended. 93 * Must be called exactly once for each call to {@link ATrace_beginAsyncSection} 94 * using the same name and cookie. 95 * 96 * \param methodName The method name to appear in the trace. 97 * \param cookie Unique identifier for distinguishing simultaneous events 98 */ 99 void ATrace_endAsyncSection(const char* sectionName, int32_t cookie) __INTRODUCED_IN(29); 100 101 /** 102 * Writes trace message to indicate the value of a given counter. 103 * 104 * \param counterName The counter name to appear in the trace. 105 * \param counterValue The counter value. 106 */ 107 void ATrace_setCounter(const char* counterName, int64_t counterValue) __INTRODUCED_IN(29); 108 109 #endif /* __ANDROID_API__ >= 29 */ 110 111 #ifdef __cplusplus 112 }; 113 #endif 114 115 #endif // ANDROID_NATIVE_TRACE_H 116 117 /** @} */ 118
