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
17package com.android.messaging.util;
18
19
20import android.annotation.TargetApi;
21import android.os.Build;
22
23/**
24 * Helper class for systrace (see http://developer.android.com/tools/help/systrace.html).<p>
25 * To enable, set log.tag.Bugle_Trace (defined by {@link #TAG} to VERBOSE before
26 * the process starts.<p>
27 * Note that this will run only on JBMR2 or later; on earlier platforms or if the log
28 * tag isn't set, calls to {@link #beginSection(String)} or {@link #endSection()} are no-ops. <p>
29 * Internally, calls dispatch to either a class that actually does work or a class that doesn't.
30 * This avoids Dalvik complaining when it loads the class on earlier platforms that the
31 * opcodes aren't available, and, according to the Dalvik team, using vtable dispatching for
32 * something like this should be faster than if (OsUtil.isAtLeast...()) on each call.
33 */
34public final class Trace {
35    private static final String TAG = "Bugle_Trace";
36    private abstract static class AbstractTrace {
37        abstract void beginSection(String sectionName);
38        abstract void endSection();
39    }
40
41    private static final AbstractTrace sTrace;
42
43    // Static initializer to pick the correct trace class to handle tracing.
44    static {
45        // Use android.util.Log instead of LogUtil here to avoid pulling in Gservices
46        // too early in app startup.
47        if (OsUtil.isAtLeastJB_MR2() &&
48                android.util.Log.isLoggable(TAG, android.util.Log.VERBOSE)) {
49            sTrace = new TraceJBMR2();
50        } else {
51            sTrace = new TraceShim();
52        }
53    }
54
55    /**
56     * Writes a trace message to indicate that a given section of code has begun. This call must
57     * be followed by a corresponding call to {@link #endSection()} on the same thread.
58     *
59     * <p class="note"> At this time the vertical bar character '|', newline character '\n', and
60     * null character '\0' are used internally by the tracing mechanism.  If sectionName contains
61     * these characters they will be replaced with a space character in the trace.
62     *
63     * @param sectionName The name of the code section to appear in the trace.  This may be at
64     * most 127 Unicode code units long.
65     */
66    public static void beginSection(String sectionName) {
67        if (LogUtil.isLoggable(TAG, LogUtil.VERBOSE)) {
68            LogUtil.v(TAG, "beginSection() " + sectionName);
69        }
70        sTrace.beginSection(sectionName);
71    }
72
73    /**
74     * Writes a trace message to indicate that a given section of code has ended. This call must
75     * be preceeded by a corresponding call to {@link #beginSection(String)}. Calling this method
76     * will mark the end of the most recently begun section of code, so care must be taken to
77     * ensure that beginSection / endSection pairs are properly nested and called from the same
78     * thread.
79     */
80    public static void endSection() {
81        sTrace.endSection();
82        if (LogUtil.isLoggable(TAG, LogUtil.VERBOSE)) {
83            LogUtil.v(TAG, "endSection()");
84        }
85    }
86
87    /**
88     * Internal class that we use if we really did enable tracing.
89     */
90    @TargetApi(Build.VERSION_CODES.JELLY_BEAN_MR2)
91    private static final class TraceJBMR2 extends AbstractTrace {
92        @Override
93        void beginSection(String sectionName) {
94            android.os.Trace.beginSection(sectionName);
95        }
96
97        @Override
98        void endSection() {
99            android.os.Trace.endSection();
100        }
101    }
102
103    /**
104     * Dummy class that we use if we aren't really tracing.
105     */
106    private static final class TraceShim extends AbstractTrace {
107        @Override
108        void beginSection(String sectionName) {
109        }
110
111        @Override
112        void endSection() {
113        }
114    }
115}
116