1 //
2 // Copyright (c) 2014 The WebRTC project authors. All Rights Reserved.
3 //
4 // Use of this source code is governed by a BSD-style license
5 // that can be found in the LICENSE file in the root of the source
6 // tree. An additional intellectual property rights grant can be found
7 // in the file PATENTS. All contributing project authors may
8 // be found in the AUTHORS file in the root of the source tree.
9 //
10
11 #ifndef SYSTEM_WRAPPERS_INCLUDE_FIELD_TRIAL_H_
12 #define SYSTEM_WRAPPERS_INCLUDE_FIELD_TRIAL_H_
13
14 #include <string>
15
16 #include "absl/strings/string_view.h"
17 #include "rtc_base/containers/flat_set.h"
18
19 // Field trials allow webrtc clients (such as Chrome) to turn on feature code
20 // in binaries out in the field and gather information with that.
21 //
22 // By default WebRTC provides an implementation of field trials that can be
23 // found in system_wrappers/source/field_trial.cc. If clients want to provide
24 // a custom version, they will have to:
25 //
26 // 1. Compile WebRTC defining the preprocessor macro
27 // WEBRTC_EXCLUDE_FIELD_TRIAL_DEFAULT (if GN is used this can be achieved
28 // by setting the GN arg rtc_exclude_field_trial_default to true).
29 // 2. Provide an implementation of:
30 // std::string webrtc::field_trial::FindFullName(absl::string_view trial).
31 //
32 // They are designed to wire up directly to chrome field trials and to speed up
33 // developers by reducing the need to wire APIs to control whether a feature is
34 // on/off. E.g. to experiment with a new method that could lead to a different
35 // trade-off between CPU/bandwidth:
36 //
37 // 1 - Develop the feature with default behaviour off:
38 //
39 // if (FieldTrial::FindFullName("WebRTCExperimentMethod2") == "Enabled")
40 // method2();
41 // else
42 // method1();
43 //
44 // 2 - Once the changes are rolled to chrome, the new code path can be
45 // controlled as normal chrome field trials.
46 //
47 // 3 - Evaluate the new feature and clean the code paths.
48 //
49 // Notes:
50 // - NOT every feature is a candidate to be controlled by this mechanism as
51 // it may require negotiation between involved parties (e.g. SDP).
52 //
53 // TODO(andresp): since chrome --force-fieldtrials does not marks the trial
54 // as active it does not get propagated to the renderer process. For now one
55 // needs to push a config with start_active:true or run a local finch
56 // server.
57 //
58 // TODO(andresp): find out how to get bots to run tests with trials enabled.
59
60 namespace webrtc {
61 namespace field_trial {
62
63 // Returns the group name chosen for the named trial, or the empty string
64 // if the trial does not exists.
65 //
66 // Note: To keep things tidy append all the trial names with WebRTC.
67 std::string FindFullName(absl::string_view name);
68
69 // Convenience method, returns true iff FindFullName(name) return a string that
70 // starts with "Enabled".
71 // TODO(tommi): Make sure all implementations support this.
IsEnabled(absl::string_view name)72 inline bool IsEnabled(absl::string_view name) {
73 return FindFullName(name).find("Enabled") == 0;
74 }
75
76 // Convenience method, returns true iff FindFullName(name) return a string that
77 // starts with "Disabled".
IsDisabled(absl::string_view name)78 inline bool IsDisabled(absl::string_view name) {
79 return FindFullName(name).find("Disabled") == 0;
80 }
81
82 // Optionally initialize field trial from a string.
83 // This method can be called at most once before any other call into webrtc.
84 // E.g. before the peer connection factory is constructed.
85 // Note: trials_string must never be destroyed.
86 void InitFieldTrialsFromString(const char* trials_string);
87
88 const char* GetFieldTrialString();
89
90 // Validates the given field trial string.
91 bool FieldTrialsStringIsValid(absl::string_view trials_string);
92
93 // Merges two field trial strings.
94 //
95 // If a key (trial) exists twice with conflicting values (groups), the value
96 // in 'second' takes precedence.
97 // Shall only be called with valid FieldTrial strings.
98 std::string MergeFieldTrialsStrings(absl::string_view first,
99 absl::string_view second);
100
101 // This helper allows to temporary "register" a field trial within the current
102 // scope. This is only useful for tests that use the global field trial string,
103 // otherwise you can use `webrtc::FieldTrialsRegistry`.
104 //
105 // If you want to isolate changes to the global field trial string itself within
106 // the current scope you should use `webrtc::test::ScopedFieldTrials`.
107 class FieldTrialsAllowedInScopeForTesting {
108 public:
109 explicit FieldTrialsAllowedInScopeForTesting(flat_set<std::string> keys);
110 ~FieldTrialsAllowedInScopeForTesting();
111 };
112
113 } // namespace field_trial
114 } // namespace webrtc
115
116 #endif // SYSTEM_WRAPPERS_INCLUDE_FIELD_TRIAL_H_
117