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 /** 44 * Returns true if tracing is enabled. Use this to avoid expensive computation only necessary 45 * when tracing is enabled. 46 * 47 * Available since API level 23. 48 */ 49 bool ATrace_isEnabled() __INTRODUCED_IN(23); 50 51 /** 52 * Writes a tracing message to indicate that the given section of code has begun. This call must be 53 * followed by a corresponding call to {@link ATrace_endSection} on the same thread. 54 * 55 * Note: At this time the vertical bar character '|' and newline character '\\n' are used internally 56 * by the tracing mechanism. If \p sectionName contains these characters they will be replaced with a 57 * space character in the trace. 58 * 59 * Available since API level 23. 60 */ 61 void ATrace_beginSection(const char* sectionName) __INTRODUCED_IN(23); 62 63 /** 64 * Writes a tracing message to indicate that a given section of code has ended. This call must be 65 * preceeded by a corresponding call to {@link ATrace_beginSection} on the same thread. Calling this method 66 * will mark the end of the most recently begun section of code, so care must be taken to ensure 67 * that {@link ATrace_beginSection}/{@link ATrace_endSection} pairs are properly nested and called from the same thread. 68 * 69 * Available since API level 23. 70 */ 71 void ATrace_endSection() __INTRODUCED_IN(23); 72 73 /** 74 * Writes a trace message to indicate that a given section of code has 75 * begun. Must be followed by a call to {@link ATrace_endAsyncSection} with the same 76 * methodName and cookie. Unlike {@link ATrace_beginSection} and {@link ATrace_endSection}, 77 * asynchronous events do not need to be nested. The name and cookie used to 78 * begin an event must be used to end it. 79 * 80 * Available since API level 29. 81 * 82 * \param sectionName The method name to appear in the trace. 83 * \param cookie Unique identifier for distinguishing simultaneous events 84 */ 85 void ATrace_beginAsyncSection(const char* sectionName, int32_t cookie) __INTRODUCED_IN(29); 86 87 /** 88 * Writes a trace message to indicate that the current method has ended. 89 * Must be called exactly once for each call to {@link ATrace_beginAsyncSection} 90 * using the same name and cookie. 91 * 92 * Available since API level 29. 93 * 94 * \param sectionName The method name to appear in the trace. 95 * \param cookie Unique identifier for distinguishing simultaneous events 96 */ 97 void ATrace_endAsyncSection(const char* sectionName, int32_t cookie) __INTRODUCED_IN(29); 98 99 /** 100 * Writes trace message to indicate the value of a given counter. 101 * 102 * Available since API level 29. 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 #ifdef __cplusplus 110 } 111 #endif 112 113 #endif // ANDROID_NATIVE_TRACE_H 114 115 /** @} */ 116