1 /*
2  * Copyright (C) 2023 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 package androidx.benchmark
18 
19 /**
20  * Experimental config object for microbenchmarks for defining custom metrics, tracing behavior, and
21  * profiling, which overrides options set in
22  * [instrumentation arguments](https://developer.android.com/topic/performance/benchmarking/microbenchmark-instrumentation-args).
23  */
24 @ExperimentalBenchmarkConfigApi
25 class MicrobenchmarkConfig
26 @JvmOverloads
27 constructor(
28     /**
29      * Timing metrics for primary phase, post-warmup
30      *
31      * Defaults to [TimeCapture].
32      */
33     val metrics: List<MetricCapture> =
34         if (Arguments.cpuEventCounterMask != 0) {
35             listOf(
36                 TimeCapture(),
37                 CpuEventCounterCapture(
38                     MicrobenchmarkPhase.cpuEventCounter,
39                     Arguments.cpuEventCounterMask
40                 )
41             )
42         } else {
43             listOf(TimeCapture())
44         },
45 
46     /**
47      * Set to true to enable capture of `trace("foo") {}` blocks in the output Perfetto trace.
48      *
49      * Defaults to false to minimize interference.
50      */
51     @get:Suppress("GetterSetterNames") // enabled is more idiomatic for config constructor
52     @get:JvmName("isTraceAppTagEnabled")
53     val traceAppTagEnabled: Boolean = false,
54 
55     /**
56      * Set to true to enable capture of tracing-perfetto trace events, such as in Compose
57      * composition tracing.
58      *
59      * Defaults to false to minimize interference.
60      */
61     @get:Suppress("GetterSetterNames") // enabled is more idiomatic for config constructor
62     @get:JvmName("isPerfettoSdkTracingEnabled")
63     val perfettoSdkTracingEnabled: Boolean = false,
64 
65     /** Optional profiler to be used after the primary timing phase. */
66     val profiler: ProfilerConfig? = null,
67 
68     /**
69      * Number of non-measured warmup iterations to perform, leave `null` to determine automatically.
70      */
71     @Suppress("AutoBoxing") // null is distinct, and boxing cost is trivial (off critical path)
72     @get:Suppress("AutoBoxing") // null is distinct, and boxing cost is trivial (off critical path)
73     val warmupCount: Int? = null,
74 
75     /** Number of measurements to perform, leave `null` for default behavior. */
76     @Suppress("AutoBoxing") // null is distinct, and boxing cost is trivial (off critical path)
77     @get:Suppress("AutoBoxing") // null is distinct, and boxing cost is trivial (off critical path)
78     val measurementCount: Int? = null
79 )
80