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