| /* |
| * Copyright 2017 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.webkit; |
| |
| import android.annotation.NonNull; |
| import android.annotation.Nullable; |
| import android.os.Handler; |
| |
| /** |
| * Manages tracing of WebViews. In particular provides functionality for the app |
| * to enable/disable tracing of parts of code and to collect tracing data. |
| * This is useful for profiling performance issues, debugging and memory usage |
| * analysis in production and real life scenarios. |
| * <p> |
| * The resulting trace data is sent back as a byte sequence in json format. This |
| * file can be loaded in "chrome://tracing" for further analysis. |
| * <p> |
| * Note: All methods in this class must be called on the UI thread. All callbacks |
| * are also called on the UI thread. |
| * <p> |
| * Example usage: |
| * <pre class="prettyprint"> |
| * TracingController tracingController = TracingController.getInstance(); |
| * tracingController.start(new TraceConfig(CATEGORIES_WEB_DEVELOPER)); |
| * [..] |
| * tracingController.stopAndFlush(new TraceFileOutput("trace.json"), null); |
| * </pre></p> |
| */ |
| public abstract class TracingController { |
| |
| /** |
| * Interface for capturing tracing data. |
| */ |
| public interface TracingOutputStream { |
| /** |
| * Will be called to return tracing data in chunks. |
| * Tracing data is returned in json format an array of bytes. |
| */ |
| void write(byte[] chunk); |
| |
| /** |
| * Called when tracing is finished and the data collection is over. |
| * There will be no calls to #write after #complete is called. |
| */ |
| void complete(); |
| } |
| |
| /** |
| * Returns the default TracingController instance. At present there is |
| * only one TracingController instance for all WebView instances, |
| * however this restriction may be relaxed in the future. |
| * |
| * @return the default TracingController instance |
| */ |
| @NonNull |
| public static TracingController getInstance() { |
| return WebViewFactory.getProvider().getTracingController(); |
| } |
| |
| /** |
| * Starts tracing all webviews. Depeding on the trace mode in traceConfig |
| * specifies how the trace events are recorded. |
| * |
| * For tracing modes {@link TracingConfig#RECORD_UNTIL_FULL}, |
| * {@link TracingConfig#RECORD_CONTINUOUSLY} and |
| * {@link TracingConfig#RECORD_UNTIL_FULL_LARGE_BUFFER} the events are recorded |
| * using an internal buffer and flushed to the outputStream when |
| * {@link #stopAndFlush(TracingOutputStream, Handler)} is called. |
| * |
| * @param tracingConfig configuration options to use for tracing |
| * @return false if the system is already tracing, true otherwise. |
| */ |
| public abstract boolean start(TracingConfig tracingConfig); |
| |
| /** |
| * Stops tracing and discards all tracing data. |
| * |
| * This method is particularly useful in conjunction with the |
| * {@link TracingConfig#RECORD_TO_CONSOLE} tracing mode because tracing data is logged to |
| * console and not sent to an outputStream as with |
| * {@link #stopAndFlush(TracingOutputStream, Handler)}. |
| * |
| * @return false if the system was not tracing at the time of the call, true |
| * otherwise. |
| */ |
| public abstract boolean stop(); |
| |
| /** |
| * Stops tracing and flushes tracing data to the specifid outputStream. |
| * |
| * Note that if the {@link TracingConfig#RECORD_TO_CONSOLE} tracing mode is used |
| * nothing will be sent to the outputStream and no TracingOuputStream methods will be |
| * called. In that case it is more convenient to just use {@link #stop()} instead. |
| * |
| * @param outputStream the output steam the tracing data will be sent to. |
| * @param handler the {@link android.os.Handler} on which the outputStream callbacks |
| * will be invoked. If the handler is null the current thread's Looper |
| * will be used. |
| * @return false if the system was not tracing at the time of the call, true |
| * otherwise. |
| */ |
| public abstract boolean stopAndFlush(TracingOutputStream outputStream, |
| @Nullable Handler handler); |
| |
| /** True if the system is tracing */ |
| public abstract boolean isTracing(); |
| |
| // TODO: consider adding getTraceBufferUsage, percentage and approx event count. |
| // TODO: consider adding String getCategories(), for obtaining the actual list |
| // of categories used (given that presets are ints). |
| |
| } |