1
    2
    3
    4
    5
    6
    7
    8
    9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98


content / public / android / java / src / org / chromium / content_public / browser / TracingControllerAndroid.java [blame]

// Copyright 2018 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

package org.chromium.content_public.browser;

import android.content.Context;
import android.util.Pair;

import org.chromium.base.Callback;
import org.chromium.content.browser.TracingControllerAndroidImpl;

/**
 * Controller for Chrome's tracing feature. The embedder may use this class to implement a UI for
 * recording and sharing Chrome performance traces.
 */
public interface TracingControllerAndroid {
    /**
     * Creates a new TracingControllerAndroid instance.
     *
     * @param context the Context in which to create the controller.
     * @return the controller.
     */
    public static TracingControllerAndroid create(Context context) {
        return new TracingControllerAndroidImpl(context);
    }

    /**
     * @return true if a trace is being recorded.
     */
    boolean isTracing();

    /**
     * @return the path of the current output file. Null if isTracing() false.
     */
    String getOutputPath();

    /**
     * Start recording a trace to the specified file (if not null) or to a new file in the Downloads
     * directory.
     *
     * Only one TracingControllerAndroid can be running at the same time. If another profiler is
     * running when this method is called, it will be cancelled. If this profiler is already
     * running, this method does nothing and returns false.
     *
     * @param filename The name of the file to output the profile data to, or null.
     * @param showToasts Whether or not we want to show toasts during this profiling session.
     * When we are timing the profile run we might not want to incur extra draw overhead of showing
     * notifications about the profiling system, or the embedder may want to show such notifications
     * themselves.
     * @param categories Which categories to trace. See TracingController::StartTracing()
     * (in content/public/browser/tracing_controller.h) for the format.
     * @param traceOptions Which trace options to use. See
     * TraceOptions::TraceOptions(const std::string& options_string)
     * (in base/trace_event/trace_event_impl.h) for the format.
     * @param compressFile Whether the trace file should be compressed (gzip).
     * @param useProtobuf Whether to generate a binary protobuf trace or use
     * the legacy JSON format.
     * @return Whether tracing was started successfully.
     */
    boolean startTracing(
            String filename,
            boolean showToasts,
            String categories,
            String traceOptions,
            boolean compressFile,
            boolean useProtobuf);

    /**
     * Stop recording and run |callback| when stopped.
     *
     * @param callback the Callback executed when tracing has stopped.
     */
    void stopTracing(Callback<Void> callback);

    /**
     * Get known tracing categories and run |callback| with the set of known categories.
     *
     * @param callback the callback that receives the result.
     * @return whether initiating the request was successful.
     */
    boolean getKnownCategories(Callback<String[]> callback);

    /**
     * Get the current estimated trace buffer usage and approximate total event count in the buffer.
     *
     * @param callback the callback that receives the result as a Pair of (percentage_full,
     * approximate_event_count).
     * @return whether initiating the request was successful.
     */
    boolean getTraceBufferUsage(Callback<Pair<Float, Long>> callback);

    /**
     * Clean any native dependencies of the controller. After the call, this class instance
     * shouldn't be used.
     */
    void destroy();
}