Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "[WebView Tracing API] documentation fixes." into pi-dev

Browse Source
This commit is contained in:
TreeHugger Robot
2018-04-11 14:38:02 +00:00
committed by Android (Google) Code Review
parent 90d388aebd 90980b4208
commit 4800d9a9e7
2 changed files with 74 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

97
core/java/android/webkit/TracingConfig.java
View File

@@ -54,37 +54,37 @@ public class TracingConfig {
/**
* Predefined set of categories typically useful for analyzing WebViews.
* Typically includes android_webview and Java.
* Typically includes "android_webview" and "Java" categories.
*/
public static final int CATEGORIES_ANDROID_WEBVIEW = 1 << 1;
/**
* Predefined set of categories typically useful for web developers.
* Typically includes blink, compositor, renderer.scheduler and v8 categories.
* Typically includes "blink", "compositor", "renderer.scheduler" and "v8" categories.
*/
public static final int CATEGORIES_WEB_DEVELOPER = 1 << 2;
/**
* Predefined set of categories for analyzing input latency issues.
* Typically includes input, renderer.scheduler categories.
* Typically includes "input", "renderer.scheduler" categories.
*/
public static final int CATEGORIES_INPUT_LATENCY = 1 << 3;
/**
* Predefined set of categories for analyzing rendering issues.
* Typically includes blink, compositor and gpu categories.
* Typically includes "blink", "compositor" and "gpu" categories.
*/
public static final int CATEGORIES_RENDERING = 1 << 4;
/**
* Predefined set of categories for analyzing javascript and rendering issues.
* Typically includes blink, compositor, gpu, renderer.scheduler and v8 categories.
* Typically includes "blink", "compositor", "gpu", "renderer.scheduler" and "v8" categories.
*/
public static final int CATEGORIES_JAVASCRIPT_AND_RENDERING = 1 << 5;
/**
* Predefined set of categories for studying difficult rendering performance problems.
* Typically includes blink, compositor, gpu, renderer.scheduler, v8 and
* Typically includes "blink", "compositor", "gpu", "renderer.scheduler", "v8" and
* some other compositor categories which are disabled by default.
*/
public static final int CATEGORIES_FRAME_VIEWER = 1 << 6;
@@ -123,7 +123,9 @@ public class TracingConfig {
}
/**
* Returns a bitmask of the predefined categories values of this configuration.
* Returns a bitmask of the predefined category sets of this configuration.
*
* @return Bitmask of predefined category sets.
*/
@PredefinedCategories
public int getPredefinedCategories() {
@@ -133,7 +135,7 @@ public class TracingConfig {
/**
* Returns the list of included custom category patterns for this configuration.
*
* @return empty list if no custom category patterns are specified.
* @return Empty list if no custom category patterns are specified.
*/
@NonNull
public List<String> getCustomIncludedCategories() {
@@ -142,6 +144,8 @@ public class TracingConfig {
/**
* Returns the tracing mode of this configuration.
*
* @return The tracing mode of this configuration.
*/
@TracingMode
public int getTracingMode() {
@@ -150,28 +154,37 @@ public class TracingConfig {
/**
* Builder used to create {@link TracingConfig} objects.
*
* <p>
* Examples:
* new TracingConfig.Builder().build()
* -- creates a configuration with default options: {@link #CATEGORIES_NONE},
* {@link #RECORD_UNTIL_FULL}.
* new TracingConfig.Builder().addCategories(CATEGORIES_WEB_DEVELOPER).build()
* -- records trace events from the "web developer" predefined category sets.
* new TracingConfig.Builder().addCategories(CATEGORIES_RENDERING,
* CATEGORIES_INPUT_LATENCY).build()
* -- records trace events from the "rendering" and "input latency" predefined
* category sets.
* new TracingConfig.Builder().addCategories("browser").build()
* -- records only the trace events from the "browser" category.
* new TracingConfig.Builder().addCategories("blink*","renderer*").build()
* -- records only the trace events matching the "blink*" and "renderer*" patterns
* (e.g. "blink.animations", "renderer_host" and "renderer.scheduler" categories).
* new TracingConfig.Builder().addCategories(CATEGORIES_WEB_DEVELOPER)
* <pre class="prettyprint">
* // Create a configuration with default options: {@link #CATEGORIES_NONE},
* // {@link #RECORD_CONTINUOUSLY}.
* <code>new TracingConfig.Builder().build()</code>
*
* // Record trace events from the "web developer" predefined category sets.
* // Uses a ring buffer (the default {@link #RECORD_CONTINUOUSLY} mode) for
* // internal storage during tracing.
* <code>new TracingConfig.Builder().addCategories(CATEGORIES_WEB_DEVELOPER).build()</code>
*
* // Record trace events from the "rendering" and "input latency" predefined
* // category sets.
* <code>new TracingConfig.Builder().addCategories(CATEGORIES_RENDERING,
* CATEGORIES_INPUT_LATENCY).build()</code>
*
* // Record only the trace events from the "browser" category.
* <code>new TracingConfig.Builder().addCategories("browser").build()</code>
*
* // Record only the trace events matching the "blink*" and "renderer*" patterns
* // (e.g. "blink.animations", "renderer_host" and "renderer.scheduler" categories).
* <code>new TracingConfig.Builder().addCategories("blink*","renderer*").build()</code>
*
* // Record events from the "web developer" predefined category set and events from
* // the "disabled-by-default-v8.gc" category to understand where garbage collection
* // is being triggered. Uses a limited size buffer for internal storage during tracing.
* <code>new TracingConfig.Builder().addCategories(CATEGORIES_WEB_DEVELOPER)
* .addCategories("disabled-by-default-v8.gc")
* .setTracingMode(RECORD_CONTINUOUSLY).build()
* -- records events from the "web developer" predefined category set and events from
* the "disabled-by-default-v8.gc" category to understand where garbage collection
* is being triggered. Uses a ring buffer for internal storage during tracing.
* .setTracingMode(RECORD_UNTIL_FULL).build()</code>
* </pre>
*/
public static class Builder {
private @PredefinedCategories int mPredefinedCategories = CATEGORIES_NONE;
@@ -185,6 +198,8 @@ public class TracingConfig {
/**
* Build {@link TracingConfig} using the current settings.
*
* @return The {@link TracingConfig} with the current settings.
*/
public TracingConfig build() {
return new TracingConfig(mPredefinedCategories, mCustomIncludedCategories,
@@ -192,16 +207,15 @@ public class TracingConfig {
}
/**
* Adds categories from a predefined set of categories to be included in the trace output.
* Adds predefined sets of categories to be included in the trace output.
*
* @param predefinedCategories list or bitmask of predefined category sets to use:
* {@link #CATEGORIES_NONE}, {@link #CATEGORIES_ALL},
* {@link #CATEGORIES_ANDROID_WEBVIEW},
* {@link #CATEGORIES_WEB_DEVELOPER},
* {@link #CATEGORIES_INPUT_LATENCY},
* {@link #CATEGORIES_RENDERING},
* {@link #CATEGORIES_JAVASCRIPT_AND_RENDERING} or
* {@link #CATEGORIES_FRAME_VIEWER}.
* A predefined category set can be one of {@link #CATEGORIES_NONE},
* {@link #CATEGORIES_ALL}, {@link #CATEGORIES_ANDROID_WEBVIEW},
* {@link #CATEGORIES_WEB_DEVELOPER}, {@link #CATEGORIES_INPUT_LATENCY},
* {@link #CATEGORIES_RENDERING}, {@link #CATEGORIES_JAVASCRIPT_AND_RENDERING} or
* {@link #CATEGORIES_FRAME_VIEWER}.
*
* @param predefinedCategories A list or bitmask of predefined category sets.
* @return The builder to facilitate chaining.
*/
public Builder addCategories(@PredefinedCategories int... predefinedCategories) {
@@ -215,11 +229,11 @@ public class TracingConfig {
* Adds custom categories to be included in trace output.
*
* Note that the categories are defined by the currently-in-use version of WebView. They
* live in chromium code and are not part of the Android API. See
* live in chromium code and are not part of the Android API.
* See <a href="https://www.chromium.org/developers/how-tos/trace-event-profiling-tool">
* chromium documentation on tracing</a> for more details.
*
* @param categories a list of category patterns. A category pattern can contain wilcards,
* @param categories A list of category patterns. A category pattern can contain wildcards,
* e.g. "blink*" or full category name e.g. "renderer.scheduler".
* @return The builder to facilitate chaining.
*/
@@ -235,7 +249,7 @@ public class TracingConfig {
*
* Same as {@link #addCategories(String...)} but allows to pass a Collection as a parameter.
*
* @param categories a list of category patters.
* @param categories A list of category patterns.
* @return The builder to facilitate chaining.
*/
public Builder addCategories(Collection<String> categories) {
@@ -245,8 +259,9 @@ public class TracingConfig {
/**
* Sets the tracing mode for this configuration.
* When tracingMode is not set explicitly, the default is {@link #RECORD_CONTINUOUSLY}.
*
* @param tracingMode tracing mode to use, one of {@link #RECORD_UNTIL_FULL} or
* @param tracingMode The tracing mode to use, one of {@link #RECORD_UNTIL_FULL} or
* {@link #RECORD_CONTINUOUSLY}.
* @return The builder to facilitate chaining.
*/

29
core/java/android/webkit/TracingController.java
View File

@@ -35,9 +35,9 @@ import java.util.concurrent.Executor;
* Example usage:
* <pre class="prettyprint">
* TracingController tracingController = TracingController.getInstance();
* tracingController.start(new TraceConfig.Builder()
* tracingController.start(new TracingConfig.Builder()
* .addCategories(CATEGORIES_WEB_DEVELOPER).build());
* [..]
* ...
* tracingController.stop(new FileOutputStream("trace.json"),
* Executors.newSingleThreadExecutor());
* </pre></p>
@@ -49,7 +49,7 @@ public abstract class TracingController {
* only one TracingController instance for all WebView instances,
* however this restriction may be relaxed in a future Android release.
*
* @return the default TracingController instance
* @return The default TracingController instance.
*/
@NonNull
public static TracingController getInstance() {
@@ -65,8 +65,10 @@ public abstract class TracingController {
* using an internal buffer and flushed to the outputStream when
* {@link #stop(OutputStream, Executor)} is called.
*
* @param tracingConfig configuration options to use for tracing
* @throws IllegalStateException if the system is already tracing.
* @param tracingConfig Configuration options to use for tracing.
* @throws IllegalStateException If the system is already tracing.
* @throws IllegalArgumentException If the configuration is invalid (e.g.
* invalid category pattern or invalid tracing mode).
*/
public abstract void start(@NonNull TracingConfig tracingConfig);
@@ -77,17 +79,22 @@ public abstract class TracingController {
* in chunks by invoking {@link java.io.OutputStream#write(byte[])}. On completion
* the {@link java.io.OutputStream#close()} method is called.
*
* @param outputStream the output steam the tracing data will be sent to. If null
* @param outputStream The output stream the tracing data will be sent to. If null
* the tracing data will be discarded.
* @param executor the {@link java.util.concurrent.Executor} on which the
* outputStream #write and #close methods will be invoked.
* @return false if the system was not tracing at the time of the call, true
* otherwise.
* @param executor The {@link java.util.concurrent.Executor} on which the
* outputStream {@link java.io.OutputStream#write(byte[])} and
* {@link java.io.OutputStream#close()} methods will be invoked.
* @return False if the WebView framework was not tracing at the time of the call,
* true otherwise.
*/
public abstract boolean stop(@Nullable OutputStream outputStream,
@NonNull @CallbackExecutor Executor executor);
/** True if the system is tracing */
/**
* Returns whether the WebView framework is tracing.
*
* @return True if tracing is enabled.
*/
public abstract boolean isTracing();
}