15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// FieldTrial is a class for handling details of statistical experiments 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// performed by actual users in the field (i.e., in a shipped or beta product). 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// All code is called exclusively on the UI thread currently. 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The simplest example is an experiment to see whether one of two options 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// produces "better" results across our user population. In that scenario, UMA 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// data is uploaded to aggregate the test results, and this FieldTrial class 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// manages the state of each such experiment (state == which option was 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// pseudo-randomly selected). 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// States are typically generated randomly, either based on a one time 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// randomization (which will yield the same results, in terms of selecting 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// the client for a field trial or not, for every run of the program on a 18d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch// given machine), or by a session randomization (generated each time the 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// application starts up, but held constant during the duration of the 20d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch// process). 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//------------------------------------------------------------------------------ 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Example: Suppose we have an experiment involving memory, such as determining 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// the impact of some pruning algorithm. 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// We assume that we already have a histogram of memory usage, such as: 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 271320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// UMA_HISTOGRAM_COUNTS("Memory.RendererTotal", count); 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Somewhere in main thread initialization code, we'd probably define an 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// instance of a FieldTrial, with code such as: 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // FieldTrials are reference counted, and persist automagically until 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // process teardown, courtesy of their automatic registration in 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // FieldTrialList. 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // Note: This field trial will run in Chrome instances compiled through 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // 8 July, 2015, and after that all instances will be in "StandardMem". 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// scoped_refptr<base::FieldTrial> trial( 38d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch// base::FieldTrialList::FactoryGetFieldTrial( 39d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch// "MemoryExperiment", 1000, "StandardMem", 2015, 7, 8, 40d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch// base::FieldTrial::ONE_TIME_RANDOMIZED, NULL)); 41d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch// 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// const int high_mem_group = 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// trial->AppendGroup("HighMem", 20); // 2% in HighMem group. 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// const int low_mem_group = 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// trial->AppendGroup("LowMem", 20); // 2% in LowMem group. 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // Take action depending of which group we randomly land in. 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// if (trial->group() == high_mem_group) 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// SetPruningAlgorithm(kType1); // Sample setting of browser state. 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// else if (trial->group() == low_mem_group) 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// SetPruningAlgorithm(kType2); // Sample alternate setting. 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//------------------------------------------------------------------------------ 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef BASE_METRICS_FIELD_TRIAL_H_ 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define BASE_METRICS_FIELD_TRIAL_H_ 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <map> 585d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles)#include <set> 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <string> 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <vector> 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/base_export.h" 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/gtest_prod_util.h" 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/memory/ref_counted.h" 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/observer_list_threadsafe.h" 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/synchronization/lock.h" 67eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch#include "base/time/time.h" 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace base { 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class FieldTrialList; 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class BASE_EXPORT FieldTrial : public RefCounted<FieldTrial> { 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) typedef int Probability; // Probability type for being selected in a trial. 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 77d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // Specifies the persistence of the field trial group choice. 78d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch enum RandomizationType { 79d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // One time randomized trials will persist the group choice between 80d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // restarts, which is recommended for most trials, especially those that 81d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // change user visible behavior. 82d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch ONE_TIME_RANDOMIZED, 83d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // Session randomized trials will roll the dice to select a group on every 84d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // process restart. 85d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch SESSION_RANDOMIZED, 86d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch }; 87d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // EntropyProvider is an interface for providing entropy for one-time 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // randomized (persistent) field trials. 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) class BASE_EXPORT EntropyProvider { 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual ~EntropyProvider(); 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 94c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns a double in the range of [0, 1) to be used for the dice roll for 95c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // the specified field trial. If |randomization_seed| is not 0, it will be 96c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // used in preference to |trial_name| for generating the entropy by entropy 97c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // providers that support it. A given instance should always return the same 98c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // value given the same input |trial_name| and |randomization_seed| values. 99c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) virtual double GetEntropyForTrial(const std::string& trial_name, 100c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) uint32 randomization_seed) const = 0; 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // A pair representing a Field Trial and its selected group. 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) struct ActiveGroup { 1052a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) std::string trial_name; 1062a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) std::string group_name; 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) typedef std::vector<ActiveGroup> ActiveGroups; 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // A return value to indicate that a given instance has not yet had a group 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // assignment (and hence is not yet participating in the trial). 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static const int kNotFinalized; 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Disables this trial, meaning it always determines the default group 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // has been selected. May be called immediately after construction, or 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // at any time after initialization (should not be interleaved with 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // AppendGroup calls). Once disabled, there is no way to re-enable a 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // trial. 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // TODO(mad): http://code.google.com/p/chromium/issues/detail?id=121446 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This doesn't properly reset to Default when a group was forced. 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void Disable(); 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Establish the name and probability of the next group in this trial. 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Sometimes, based on construction randomization, this call may cause the 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // provided group to be *THE* group selected for use in this instance. 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The return value is the group number of the new group. 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int AppendGroup(const std::string& name, Probability group_probability); 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Return the name of the FieldTrial (excluding the group name). 1312a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) const std::string& trial_name() const { return trial_name_; } 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Return the randomly selected group number that was assigned, and notify 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // any/all observers that this finalized group number has presumably been used 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // (queried), and will never change. Note that this will force an instance to 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // participate, and make it illegal to attempt to probabilistically add any 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // other groups to the trial. 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int group(); 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // If the group's name is empty, a string version containing the group number 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // is used as the group name. This causes a winner to be chosen if none was. 1422a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) const std::string& group_name(); 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Set the field trial as forced, meaning that it was setup earlier than 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the hard coded registration of the field trial to override it. 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This allows the code that was hard coded to register the field trial to 1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // still succeed even though the field trial has already been registered. 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This must be called after appending all the groups, since we will make 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the group choice here. Note that this is a NOOP for already forced trials. 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // And, as the rest of the FieldTrial code, this is not thread safe and must 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // be done from the UI thread. 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void SetForced(); 1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1541e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // Enable benchmarking sets field trials to a common setting. 1551e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) static void EnableBenchmarking(); 1561e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) 1571e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // Creates a FieldTrial object with the specified parameters, to be used for 1581e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // simulation of group assignment without actually affecting global field 1591e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // trial state in the running process. Group assignment will be done based on 1601e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // |entropy_value|, which must have a range of [0, 1). 1611e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // 1621e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // Note: Using this function will not register the field trial globally in the 1631e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // running process - for that, use FieldTrialList::FactoryGetFieldTrial(). 1641e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // 1651e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // The ownership of the returned FieldTrial is transfered to the caller which 1661e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // is responsible for deref'ing it (e.g. by using scoped_refptr<FieldTrial>). 1671e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) static FieldTrial* CreateSimulatedFieldTrial( 1681e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) const std::string& trial_name, 1691e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) Probability total_probability, 1701e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) const std::string& default_group_name, 1711e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) double entropy_value); 1721e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) 1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private: 1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Allow tests to access our innards for testing purposes. 1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, Registration); 1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, AbsoluteProbabilities); 1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, RemainingProbability); 1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, FiftyFiftyProbability); 1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, MiddleProbabilities); 1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, OneWinner); 1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, DisableProbability); 1825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, ActiveGroups); 1835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, ActiveGroupsNotFinalized); 1845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, Save); 1855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, DuplicateRestore); 1862a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, SetForcedTurnFeatureOff); 1872a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, SetForcedTurnFeatureOn); 1882a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, SetForcedChangeDefault_Default); 1892a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, SetForcedChangeDefault_NonDefault); 190d0247b1b59f9c528cb6df88b4f2b9afaf80d181eTorne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, FloatBoundariesGiveEqualGroupSizes); 191d0247b1b59f9c528cb6df88b4f2b9afaf80d181eTorne (Richard Coles) FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, DoesNotSurpassTotalProbability); 1925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) friend class base::FieldTrialList; 1945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) friend class RefCounted<FieldTrial>; 1965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This is the group number of the 'default' group when a choice wasn't forced 1985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // by a call to FieldTrialList::CreateFieldTrial. It is kept private so that 1995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // consumers don't use it by mistake in cases where the group was forced. 2005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static const int kDefaultGroupNumber; 2015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 202d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // Creates a field trial with the specified parameters. Group assignment will 203d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // be done based on |entropy_value|, which must have a range of [0, 1). 2041e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) FieldTrial(const std::string& trial_name, 2055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Probability total_probability, 206d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch const std::string& default_group_name, 207d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch double entropy_value); 2085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual ~FieldTrial(); 2095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Return the default group name of the FieldTrial. 2115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) std::string default_group_name() const { return default_group_name_; } 2125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2131e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // Marks this trial as having been registered with the FieldTrialList. Must be 2141e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // called no more than once and before any |group()| calls have occurred. 2151e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) void SetTrialRegistered(); 2161e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) 2172a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // Sets the chosen group name and number. 2182a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) void SetGroupChoice(const std::string& group_name, int number); 2195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Ensures that a group is chosen, if it hasn't yet been. The field trial 2215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // might yet be disabled, so this call will *not* notify observers of the 2225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // status. 2235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void FinalizeGroupChoice(); 2245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the trial name and selected group name for this field trial via 2265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the output parameter |active_group|, but only if the group has already 2275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // been chosen and has been externally observed via |group()| and the trial 2285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // has not been disabled. In that case, true is returned and |active_group| 2295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // is filled in; otherwise, the result is false and |active_group| is left 2305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // untouched. 2315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool GetActiveGroup(ActiveGroup* active_group) const; 2325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the group_name. A winner need not have been chosen. 2345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) std::string group_name_internal() const { return group_name_; } 2355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The name of the field trial, as can be found via the FieldTrialList. 2372a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) const std::string trial_name_; 2385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The maximum sum of all probabilities supplied, which corresponds to 100%. 2405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This is the scaling factor used to adjust supplied probabilities. 2415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const Probability divisor_; 2425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The name of the default group. 2445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const std::string default_group_name_; 2455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The randomly selected probability that is used to select a group (or have 2475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the instance not participate). It is the product of divisor_ and a random 2485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // number between [0, 1). 2495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Probability random_; 2505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Sum of the probabilities of all appended groups. 2525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Probability accumulated_group_probability_; 2535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2541e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // The number that will be returned by the next AppendGroup() call. 2555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int next_group_number_; 2565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The pseudo-randomly assigned group number. 2585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This is kNotFinalized if no group has been assigned. 2595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int group_; 2605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // A textual name for the randomly selected group. Valid after |group()| 2625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // has been called. 2635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) std::string group_name_; 2645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // When enable_field_trial_ is false, field trial reverts to the 'default' 2665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // group. 2675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool enable_field_trial_; 2685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // When forced_ is true, we return the chosen group from AppendGroup when 2705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // appropriate. 2715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool forced_; 2725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Specifies whether the group choice has been reported to observers. 2745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool group_reported_; 2755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2761e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // Whether this trial is registered with the global FieldTrialList and thus 2771e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) // should notify it when its group is queried. 2781e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) bool trial_registered_; 2791e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) 2805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // When benchmarking is enabled, field trials all revert to the 'default' 2815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // group. 2825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static bool enable_benchmarking_; 2835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) DISALLOW_COPY_AND_ASSIGN(FieldTrial); 2855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 2865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//------------------------------------------------------------------------------ 2885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Class with a list of all active field trials. A trial is active if it has 2895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// been registered, which includes evaluating its state based on its probaility. 2905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Only one instance of this class exists. 2915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class BASE_EXPORT FieldTrialList { 2925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 293eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch // Specifies whether field trials should be activated (marked as "used"), when 294eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch // created using |CreateTrialsFromString()|. 295eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch enum FieldTrialActivationMode { 296eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch DONT_ACTIVATE_TRIALS, 297eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch ACTIVATE_TRIALS, 298eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch }; 299eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 3005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Define a separator character to use when creating a persistent form of an 3015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // instance. This is intended for use as a command line argument, passed to a 3025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // second process to mimic our state (i.e., provide the same group name). 3035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static const char kPersistentStringSeparator; // Currently a slash. 3045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3052a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // Year that is guaranteed to not be expired when instantiating a field trial 3062a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // via |FactoryGetFieldTrial()|. Set to two years from the build date. 3072a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) static int kNoExpirationYear; 3085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Observer is notified when a FieldTrial's group is selected. 3105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) class BASE_EXPORT Observer { 3115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 3125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Notify observers when FieldTrials's group is selected. 3135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void OnFieldTrialGroupFinalized(const std::string& trial_name, 3145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const std::string& group_name) = 0; 3155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) protected: 3175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual ~Observer(); 3185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 3195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This singleton holds the global list of registered FieldTrials. 3215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 3225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // To support one-time randomized field trials, specify a non-NULL 3235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |entropy_provider| which should be a source of uniformly distributed 3245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // entropy values. Takes ownership of |entropy_provider|. If one time 3255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // randomization is not desired, pass in NULL for |entropy_provider|. 3265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) explicit FieldTrialList(const FieldTrial::EntropyProvider* entropy_provider); 3275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Destructor Release()'s references to all registered FieldTrial instances. 3295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ~FieldTrialList(); 3305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Get a FieldTrial instance from the factory. 3325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 3335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |name| is used to register the instance with the FieldTrialList class, 3345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // and can be used to find the trial (only one trial can be present for each 3355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // name). |default_group_name| is the name of the default group which will 3365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // be chosen if none of the subsequent appended groups get to be chosen. 3375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |default_group_number| can receive the group number of the default group as 3382a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // AppendGroup returns the number of the subsequence groups. |trial_name| and 3395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |default_group_name| may not be empty but |default_group_number| can be 3405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // NULL if the value is not needed. 3415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 3425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Group probabilities that are later supplied must sum to less than or equal 3435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // to the |total_probability|. Arguments |year|, |month| and |day_of_month| 3445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // specify the expiration time. If the build time is after the expiration time 3455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // then the field trial reverts to the 'default' group. 3465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 3475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Use this static method to get a startup-randomized FieldTrial or a 348d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // previously created forced FieldTrial. 3495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static FieldTrial* FactoryGetFieldTrial( 3502a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) const std::string& trial_name, 3515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FieldTrial::Probability total_probability, 3525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const std::string& default_group_name, 3535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const int year, 3545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const int month, 3555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const int day_of_month, 356d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch FieldTrial::RandomizationType randomization_type, 357d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch int* default_group_number); 358d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch 359d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // Same as FactoryGetFieldTrial(), but allows specifying a custom seed to be 360d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // used on one-time randomized field trials (instead of a hash of the trial 361d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // name, which is used otherwise or if |randomization_seed| has value 0). The 362d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // |randomization_seed| value (other than 0) should never be the same for two 363d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // trials, else this would result in correlated group assignments. 364d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // Note: Using a custom randomization seed is only supported by the 365d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // PermutedEntropyProvider (which is used when UMA is not enabled). 366d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch static FieldTrial* FactoryGetFieldTrialWithRandomizationSeed( 367d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch const std::string& trial_name, 368d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch FieldTrial::Probability total_probability, 369d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch const std::string& default_group_name, 370d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch const int year, 371d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch const int month, 372d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch const int day_of_month, 373d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch FieldTrial::RandomizationType randomization_type, 374d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch uint32 randomization_seed, 3755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int* default_group_number); 3765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The Find() method can be used to test to see if a named Trial was already 3785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // registered, or to retrieve a pointer to it from the global map. 3795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static FieldTrial* Find(const std::string& name); 3805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the group number chosen for the named trial, or 3825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // FieldTrial::kNotFinalized if the trial does not exist. 3835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static int FindValue(const std::string& name); 3845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the group name chosen for the named trial, or the 3865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // empty string if the trial does not exist. 3875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static std::string FindFullName(const std::string& name); 3885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns true if the named trial has been registered. 3905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static bool TrialExists(const std::string& name); 3915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Creates a persistent representation of active FieldTrial instances for 3935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // resurrection in another process. This allows randomization to be done in 3945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // one process, and secondary processes can be synchronized on the result. 3955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The resulting string contains the name and group name pairs of all 3965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // registered FieldTrials for which the group has been chosen and externally 3975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // observed (via |group()|) and which have not been disabled, with "/" used 3985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // to separate all names and to terminate the string. This string is parsed 3995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // by |CreateTrialsFromString()|. 4005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static void StatesToString(std::string* output); 4015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Fills in the supplied vector |active_groups| (which must be empty when 4035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // called) with a snapshot of all registered FieldTrials for which the group 4045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // has been chosen and externally observed (via |group()|) and which have 4055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // not been disabled. 4065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static void GetActiveFieldTrialGroups( 4075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FieldTrial::ActiveGroups* active_groups); 4085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Use a state string (re: StatesToString()) to augment the current list of 4102a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // field trials to include the supplied trials, and using a 100% probability 4112a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // for each trial, force them to have the same group string. This is commonly 4122a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // used in a non-browser process, to carry randomly selected state in a 4132a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // browser process into this non-browser process, but could also be invoked 4142a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // through a command line argument to the browser process. The created field 415eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch // trials are marked as "used" for the purposes of active trial reporting if 4165d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) // |mode| is ACTIVATE_TRIALS. Trial names in |ignored_trial_names| are ignored 4175d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) // when parsing |prior_trials|. 4185d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) static bool CreateTrialsFromString( 4195d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) const std::string& prior_trials, 4205d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) FieldTrialActivationMode mode, 4215d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) const std::set<std::string>& ignored_trial_names); 4225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Create a FieldTrial with the given |name| and using 100% probability for 4245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the FieldTrial, force FieldTrial to have the same group string as 4255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |group_name|. This is commonly used in a non-browser process, to carry 4265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // randomly selected state in a browser process into this non-browser process. 4275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // It returns NULL if there is a FieldTrial that is already registered with 4285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the same |name| but has different finalized group string (|group_name|). 4295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static FieldTrial* CreateFieldTrial(const std::string& name, 4305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const std::string& group_name); 4315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Add an observer to be notified when a field trial is irrevocably committed 4335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // to being part of some specific field_group (and hence the group_name is 4345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // also finalized for that field_trial). 4355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static void AddObserver(Observer* observer); 4365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Remove an observer. 4385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static void RemoveObserver(Observer* observer); 4395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4402a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // Notify all observers that a group has been finalized for |field_trial|. 4412a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) static void NotifyFieldTrialGroupSelection(FieldTrial* field_trial); 4425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Return the number of active field trials. 4445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static size_t GetFieldTrialCount(); 4455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 446d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch private: 447d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch // A map from FieldTrial names to the actual instances. 4485d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) typedef std::map<std::string, FieldTrial*> RegistrationMap; 449d3868032626d59662ff73b372b5d584c1d144c53Ben Murdoch 4505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // If one-time randomization is enabled, returns a weak pointer to the 4515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // corresponding EntropyProvider. Otherwise, returns NULL. 4525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static const FieldTrial::EntropyProvider* 4535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) GetEntropyProviderForOneTimeRandomization(); 4545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Helper function should be called only while holding lock_. 4565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FieldTrial* PreLockedFind(const std::string& name); 4575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Register() stores a pointer to the given trial in a global map. 4595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This method also AddRef's the indicated trial. 4605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This should always be called after creating a new FieldTrial instance. 4615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static void Register(FieldTrial* trial); 4625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static FieldTrialList* global_; // The singleton of this class. 4645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This will tell us if there is an attempt to register a field 4665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // trial or check if one-time randomization is enabled without 4675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // creating the FieldTrialList. This is not an error, unless a 4685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // FieldTrialList is created after that. 4695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static bool used_without_global_; 4705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Lock for access to registered_. 4725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) base::Lock lock_; 4735d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) RegistrationMap registered_; 4745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Entropy provider to be used for one-time randomized field trials. If NULL, 4765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // one-time randomization is not supported. 4775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) scoped_ptr<const FieldTrial::EntropyProvider> entropy_provider_; 4785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // List of observers to be notified when a group is selected for a FieldTrial. 4805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) scoped_refptr<ObserverListThreadSafe<Observer> > observer_list_; 4815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) DISALLOW_COPY_AND_ASSIGN(FieldTrialList); 4835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 4845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace base 4865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // BASE_METRICS_FIELD_TRIAL_H_ 488