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 android.tracing.perfetto;
18 
19 import android.annotation.IntDef;
20 
21 import java.lang.annotation.Retention;
22 import java.lang.annotation.RetentionPolicy;
23 
24 /**
25  * DataSource Parameters
26  *
27  * @hide
28  */
29 public class DataSourceParams {
30     /**
31      * @hide
32      */
33     @IntDef(value = {
34         PERFETTO_DS_BUFFER_EXHAUSTED_POLICY_DROP,
35         PERFETTO_DS_BUFFER_EXHAUSTED_POLICY_STALL_AND_ABORT,
36     })
37     @Retention(RetentionPolicy.SOURCE)
38     public @interface PerfettoDsBufferExhausted {}
39 
40     // If the data source runs out of space when trying to acquire a new chunk,
41     // it will drop data.
42     public static final int PERFETTO_DS_BUFFER_EXHAUSTED_POLICY_DROP = 0;
43 
44     // If the data source runs out of space when trying to acquire a new chunk,
45     // it will stall, retry and eventually abort if a free chunk is not acquired
46     // after a while.
47     public static final int PERFETTO_DS_BUFFER_EXHAUSTED_POLICY_STALL_AND_ABORT = 1;
48 
49     public static DataSourceParams DEFAULTS = new DataSourceParams.Builder().build();
50 
DataSourceParams(@erfettoDsBufferExhausted int bufferExhaustedPolicy, boolean willNotifyOnStop, boolean noFlush)51     private DataSourceParams(@PerfettoDsBufferExhausted int bufferExhaustedPolicy,
52             boolean willNotifyOnStop, boolean noFlush) {
53         this.bufferExhaustedPolicy = bufferExhaustedPolicy;
54         this.willNotifyOnStop = willNotifyOnStop;
55         this.noFlush = noFlush;
56     }
57 
58     public final @PerfettoDsBufferExhausted int bufferExhaustedPolicy;
59     public final boolean willNotifyOnStop;
60     public final boolean noFlush;
61 
62     /**
63      * DataSource Parameters builder
64      *
65      * @hide
66      */
67     public static final class Builder {
68         /**
69          * Specify behavior when running out of shared memory buffer space.
70          */
setBufferExhaustedPolicy(@erfettoDsBufferExhausted int value)71         public Builder setBufferExhaustedPolicy(@PerfettoDsBufferExhausted int value) {
72             this.mBufferExhaustedPolicy = value;
73             return this;
74         }
75 
76         /**
77          * If true, the data source is expected to ack the stop request through the
78          * NotifyDataSourceStopped() IPC. If false, the service won't wait for an ack.
79          * Set this parameter to false when dealing with potentially frozen producers
80          * that wouldn't be able to quickly ack the stop request.
81          *
82          * Default value: true
83          */
setWillNotifyOnStop(boolean value)84         public Builder setWillNotifyOnStop(boolean value) {
85             this.mWillNotifyOnStop = value;
86             return this;
87         }
88 
89         /**
90          * If true, the service won't emit flush requests for this data source. This
91          * allows the service to reduce the flush-related IPC traffic and better deal
92          * with frozen producers (see go/perfetto-frozen).
93          */
setNoFlush(boolean value)94         public Builder setNoFlush(boolean value) {
95             this.mNoFlush = value;
96             return this;
97         }
98 
99         /**
100          * Build the DataSource parameters.
101          */
build()102         public DataSourceParams build() {
103             return new DataSourceParams(
104                     this.mBufferExhaustedPolicy, this.mWillNotifyOnStop, this.mNoFlush);
105         }
106 
107         private @PerfettoDsBufferExhausted int mBufferExhaustedPolicy =
108                 PERFETTO_DS_BUFFER_EXHAUSTED_POLICY_DROP;
109         private boolean mWillNotifyOnStop = true;
110         private boolean mNoFlush = false;
111     }
112 }
113