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 // Field trials allow webrtc clients (such as Chrome) to turn on feature code
17 // in binaries out in the field and gather information with that.
18 //
19 // By default WebRTC provides an implementation of field trials that can be
20 // found in system_wrappers/source/field_trial.cc. If clients want to provide
21 // a custom version, they will have to:
22 //
23 // 1. Compile WebRTC defining the preprocessor macro
24 // WEBRTC_EXCLUDE_FIELD_TRIAL_DEFAULT (if GN is used this can be achieved
25 // by setting the GN arg rtc_exclude_field_trial_default to true).
26 // 2. Provide an implementation of:
27 // std::string webrtc::field_trial::FindFullName(const std::string& trial).
28 //
29 // They are designed to wire up directly to chrome field trials and to speed up
30 // developers by reducing the need to wire APIs to control whether a feature is
31 // on/off. E.g. to experiment with a new method that could lead to a different
32 // trade-off between CPU/bandwidth:
33 //
34 // 1 - Develop the feature with default behaviour off:
35 //
36 // if (FieldTrial::FindFullName("WebRTCExperimentMethod2") == "Enabled")
37 // method2();
38 // else
39 // method1();
40 //
41 // 2 - Once the changes are rolled to chrome, the new code path can be
42 // controlled as normal chrome field trials.
43 //
44 // 3 - Evaluate the new feature and clean the code paths.
45 //
46 // Notes:
47 // - NOT every feature is a candidate to be controlled by this mechanism as
48 // it may require negotiation between involved parties (e.g. SDP).
49 //
50 // TODO(andresp): since chrome --force-fieldtrials does not marks the trial
51 // as active it does not get propagated to the renderer process. For now one
52 // needs to push a config with start_active:true or run a local finch
53 // server.
54 //
55 // TODO(andresp): find out how to get bots to run tests with trials enabled.
56
57 namespace webrtc {
58 namespace field_trial {
59
60 // Returns the group name chosen for the named trial, or the empty string
61 // if the trial does not exists.
62 //
63 // Note: To keep things tidy append all the trial names with WebRTC.
64 std::string FindFullName(const std::string& name);
65
66 // Convenience method, returns true iff FindFullName(name) return a string that
67 // starts with "Enabled".
68 // TODO(tommi): Make sure all implementations support this.
IsEnabled(const char * name)69 inline bool IsEnabled(const char* name) {
70 return FindFullName(name).find("Enabled") == 0;
71 }
72
73 // Convenience method, returns true iff FindFullName(name) return a string that
74 // starts with "Disabled".
IsDisabled(const char * name)75 inline bool IsDisabled(const char* name) {
76 return FindFullName(name).find("Disabled") == 0;
77 }
78
79 // Optionally initialize field trial from a string.
80 // This method can be called at most once before any other call into webrtc.
81 // E.g. before the peer connection factory is constructed.
82 // Note: trials_string must never be destroyed.
83 void InitFieldTrialsFromString(const char* trials_string);
84
85 const char* GetFieldTrialString();
86
87 #ifndef WEBRTC_EXCLUDE_FIELD_TRIAL_DEFAULT
88 // Validates the given field trial string.
89 bool FieldTrialsStringIsValid(const char* trials_string);
90
91 // Merges two field trial strings.
92 //
93 // If a key (trial) exists twice with conflicting values (groups), the value
94 // in 'second' takes precedence.
95 // Shall only be called with valid FieldTrial strings.
96 std::string MergeFieldTrialsStrings(const char* first, const char* second);
97 #endif // WEBRTC_EXCLUDE_FIELD_TRIAL_DEFAULT
98
99 } // namespace field_trial
100 } // namespace webrtc
101
102 #endif // SYSTEM_WRAPPERS_INCLUDE_FIELD_TRIAL_H_
103