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 // WebRTC clients MUST provide an implementation of:
20 //
21 // std::string webrtc::field_trial::FindFullName(const std::string& trial).
22 //
23 // Or link with a default one provided in:
24 //
25 // system_wrappers/system_wrappers.gyp:field_trial_default
26 //
27 //
28 // They are designed to wire up directly to chrome field trials and to speed up
29 // developers by reducing the need to wire APIs to control whether a feature is
30 // on/off. E.g. to experiment with a new method that could lead to a different
31 // trade-off between CPU/bandwidth:
32 //
33 // 1 - Develop the feature with default behaviour off:
34 //
35 // if (FieldTrial::FindFullName("WebRTCExperimenMethod2") == "Enabled")
36 // method2();
37 // else
38 // method1();
39 //
40 // 2 - Once the changes are rolled to chrome, the new code path can be
41 // controlled as normal chrome field trials.
42 //
43 // 3 - Evaluate the new feature and clean the code paths.
44 //
45 // Notes:
46 // - NOT every feature is a candidate to be controlled by this mechanism as
47 // it may require negotation between involved parties (e.g. SDP).
48 //
49 // TODO(andresp): since chrome --force-fieldtrials does not marks the trial
50 // as active it does not gets propaged to renderer process. For now one
51 // needs to push a config with start_active:true or run a local finch
52 // server.
53 //
54 // TODO(andresp): find out how to get bots to run tests with trials enabled.
55
56 namespace webrtc {
57 namespace field_trial {
58
59 // Returns the group name chosen for the named trial, or the empty string
60 // if the trial does not exists.
61 //
62 // Note: To keep things tidy append all the trial names with WebRTC.
63 std::string FindFullName(const std::string& name);
64
65 // Convenience method, returns true iff FindFullName(name) return a string that
66 // starts with "Enabled".
67 // TODO(tommi): Make sure all implementations support this.
IsEnabled(const char * name)68 inline bool IsEnabled(const char* name) {
69 return FindFullName(name).find("Enabled") == 0;
70 }
71
72 } // namespace field_trial
73 } // namespace webrtc
74
75 #endif // SYSTEM_WRAPPERS_INCLUDE_FIELD_TRIAL_H_
76