OLD | NEW |
1 // Copyright (c) 2011 The Chromium Authors. All rights reserved. | 1 // Copyright (c) 2011 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 // FieldTrial is a class for handling details of statistical experiments | 5 // FieldTrial is a class for handling details of statistical experiments |
6 // performed by actual users in the field (i.e., in a shipped or beta product). | 6 // performed by actual users in the field (i.e., in a shipped or beta product). |
7 // All code is called exclusively on the UI thread currently. | 7 // All code is called exclusively on the UI thread currently. |
8 // | 8 // |
9 // The simplest example is an experiment to see whether one of two options | 9 // The simplest example is an experiment to see whether one of two options |
10 // produces "better" results across our user population. In that scenario, UMA | 10 // produces "better" results across our user population. In that scenario, UMA |
(...skipping 74 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
85 #include "base/synchronization/lock.h" | 85 #include "base/synchronization/lock.h" |
86 #include "base/time.h" | 86 #include "base/time.h" |
87 | 87 |
88 namespace base { | 88 namespace base { |
89 | 89 |
90 class FieldTrialList; | 90 class FieldTrialList; |
91 | 91 |
92 class BASE_EXPORT FieldTrial : public RefCounted<FieldTrial> { | 92 class BASE_EXPORT FieldTrial : public RefCounted<FieldTrial> { |
93 public: | 93 public: |
94 typedef int Probability; // Probability type for being selected in a trial. | 94 typedef int Probability; // Probability type for being selected in a trial. |
| 95 // The Unique ID of a trial, where the name and group identifiers are |
| 96 // hashes of the trial and group name strings. |
| 97 struct NameGroupId { |
| 98 uint32 name; |
| 99 uint32 group; |
| 100 }; |
95 | 101 |
96 // A return value to indicate that a given instance has not yet had a group | 102 // A return value to indicate that a given instance has not yet had a group |
97 // assignment (and hence is not yet participating in the trial). | 103 // assignment (and hence is not yet participating in the trial). |
98 static const int kNotFinalized; | 104 static const int kNotFinalized; |
99 | 105 |
100 // This is the group number of the 'default' group. This provides an easy way | 106 // This is the group number of the 'default' group. This provides an easy way |
101 // to assign all the remaining probability to a group ('default'). | 107 // to assign all the remaining probability to a group ('default'). |
102 static const int kDefaultGroupNumber; | 108 static const int kDefaultGroupNumber; |
103 | 109 |
104 // The name is used to register the instance with the FieldTrialList class, | 110 // The name is used to register the instance with the FieldTrialList class, |
(...skipping 36 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
141 // Return the randomly selected group number that was assigned. | 147 // Return the randomly selected group number that was assigned. |
142 // Return kDefaultGroupNumber if the instance is in the 'default' group. | 148 // Return kDefaultGroupNumber if the instance is in the 'default' group. |
143 // Note that this will force an instance to participate, and make it illegal | 149 // Note that this will force an instance to participate, and make it illegal |
144 // to attempt to probabilistically add any other groups to the trial. | 150 // to attempt to probabilistically add any other groups to the trial. |
145 int group(); | 151 int group(); |
146 | 152 |
147 // If the group's name is empty, a string version containing the group | 153 // If the group's name is empty, a string version containing the group |
148 // number is used as the group name. | 154 // number is used as the group name. |
149 std::string group_name(); | 155 std::string group_name(); |
150 | 156 |
| 157 // Gets the unique identifier of the Field Trial, but only if a group was |
| 158 // officially chosen, otherwise name_group_id is left untouched and false |
| 159 // is returned. When true is returned, the name and group ids were successfuly |
| 160 // set in name_group_id. |
| 161 bool GetNameGroupId(NameGroupId* name_group_id); |
| 162 |
151 // Return the default group name of the FieldTrial. | 163 // Return the default group name of the FieldTrial. |
152 std::string default_group_name() const { return default_group_name_; } | 164 std::string default_group_name() const { return default_group_name_; } |
153 | 165 |
154 // Helper function for the most common use: as an argument to specify the | 166 // Helper function for the most common use: as an argument to specify the |
155 // name of a HISTOGRAM. Use the original histogram name as the name_prefix. | 167 // name of a HISTOGRAM. Use the original histogram name as the name_prefix. |
156 static std::string MakeName(const std::string& name_prefix, | 168 static std::string MakeName(const std::string& name_prefix, |
157 const std::string& trial_name); | 169 const std::string& trial_name); |
158 | 170 |
159 // Enable benchmarking sets field trials to a common setting. | 171 // Enable benchmarking sets field trials to a common setting. |
160 static void EnableBenchmarking(); | 172 static void EnableBenchmarking(); |
161 | 173 |
162 private: | 174 private: |
163 // Allow tests to access our innards for testing purposes. | 175 // Allow tests to access our innards for testing purposes. |
164 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, Registration); | 176 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, Registration); |
165 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, AbsoluteProbabilities); | 177 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, AbsoluteProbabilities); |
166 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, RemainingProbability); | 178 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, RemainingProbability); |
167 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, FiftyFiftyProbability); | 179 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, FiftyFiftyProbability); |
168 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, MiddleProbabilities); | 180 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, MiddleProbabilities); |
169 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, OneWinner); | 181 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, OneWinner); |
170 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, DisableProbability); | 182 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, DisableProbability); |
171 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, Save); | 183 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, Save); |
172 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, DuplicateRestore); | 184 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, DuplicateRestore); |
173 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, MakeName); | 185 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, MakeName); |
174 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, HashClientId); | 186 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, HashClientId); |
175 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, HashClientIdIsUniform); | 187 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, HashClientIdIsUniform); |
| 188 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, HashName); |
| 189 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, NameGroupIds); |
176 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, UseOneTimeRandomization); | 190 FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, UseOneTimeRandomization); |
177 | 191 |
178 friend class base::FieldTrialList; | 192 friend class base::FieldTrialList; |
179 | 193 |
180 friend class RefCounted<FieldTrial>; | 194 friend class RefCounted<FieldTrial>; |
181 | 195 |
182 virtual ~FieldTrial(); | 196 virtual ~FieldTrial(); |
183 | 197 |
184 // Returns the group_name. A winner need not have been chosen. | 198 // Returns the group_name. A winner need not have been chosen. |
185 std::string group_name_internal() const { return group_name_; } | 199 std::string group_name_internal() const { return group_name_; } |
186 | 200 |
187 // Calculates a uniformly-distributed double between [0.0, 1.0) given | 201 // Calculates a uniformly-distributed double between [0.0, 1.0) given |
188 // a |client_id| and a |trial_name| (the latter is used as salt to avoid | 202 // a |client_id| and a |trial_name| (the latter is used as salt to avoid |
189 // separate one-time randomized trials from all having the same results). | 203 // separate one-time randomized trials from all having the same results). |
190 static double HashClientId(const std::string& client_id, | 204 static double HashClientId(const std::string& client_id, |
191 const std::string& trial_name); | 205 const std::string& trial_name); |
192 | 206 |
| 207 // Creates unique identifier for the trial by hashing a name string, whether |
| 208 // it's for the field trial or the group name. |
| 209 static uint32 HashName(const std::string& name); |
| 210 |
193 // The name of the field trial, as can be found via the FieldTrialList. | 211 // The name of the field trial, as can be found via the FieldTrialList. |
194 const std::string name_; | 212 const std::string name_; |
195 | 213 |
| 214 // The hashed name of the field trial to be sent as a unique identifier. |
| 215 const uint32 name_hash_; |
| 216 |
196 // The maximum sum of all probabilities supplied, which corresponds to 100%. | 217 // The maximum sum of all probabilities supplied, which corresponds to 100%. |
197 // This is the scaling factor used to adjust supplied probabilities. | 218 // This is the scaling factor used to adjust supplied probabilities. |
198 const Probability divisor_; | 219 const Probability divisor_; |
199 | 220 |
200 // The name of the default group. | 221 // The name of the default group. |
201 const std::string default_group_name_; | 222 const std::string default_group_name_; |
202 | 223 |
203 // The randomly selected probability that is used to select a group (or have | 224 // The randomly selected probability that is used to select a group (or have |
204 // the instance not participate). It is the product of divisor_ and a random | 225 // the instance not participate). It is the product of divisor_ and a random |
205 // number between [0, 1). | 226 // number between [0, 1). |
206 Probability random_; | 227 Probability random_; |
207 | 228 |
208 // Sum of the probabilities of all appended groups. | 229 // Sum of the probabilities of all appended groups. |
209 Probability accumulated_group_probability_; | 230 Probability accumulated_group_probability_; |
210 | 231 |
211 int next_group_number_; | 232 int next_group_number_; |
212 | 233 |
213 // The pseudo-randomly assigned group number. | 234 // The pseudo-randomly assigned group number. |
214 // This is kNotFinalized if no group has been assigned. | 235 // This is kNotFinalized if no group has been assigned. |
215 int group_; | 236 int group_; |
216 | 237 |
217 // A textual name for the randomly selected group. Valid after |group()| | 238 // A textual name for the randomly selected group. Valid after |group()| |
218 // has been called. | 239 // has been called. |
219 std::string group_name_; | 240 std::string group_name_; |
220 | 241 |
| 242 // The hashed name of the group to be sent as a unique identifier. |
| 243 // Is not valid while group_ is equal to kNotFinalized. |
| 244 uint32 group_name_hash_; |
| 245 |
221 // When enable_field_trial_ is false, field trial reverts to the 'default' | 246 // When enable_field_trial_ is false, field trial reverts to the 'default' |
222 // group. | 247 // group. |
223 bool enable_field_trial_; | 248 bool enable_field_trial_; |
224 | 249 |
225 // When benchmarking is enabled, field trials all revert to the 'default' | 250 // When benchmarking is enabled, field trials all revert to the 'default' |
226 // group. | 251 // group. |
227 static bool enable_benchmarking_; | 252 static bool enable_benchmarking_; |
228 | 253 |
| 254 // This value is reserved for an uninitialized hash value. |
| 255 static const uint32 kReservedHashValue; |
| 256 |
229 DISALLOW_COPY_AND_ASSIGN(FieldTrial); | 257 DISALLOW_COPY_AND_ASSIGN(FieldTrial); |
230 }; | 258 }; |
231 | 259 |
232 //------------------------------------------------------------------------------ | 260 //------------------------------------------------------------------------------ |
233 // Class with a list of all active field trials. A trial is active if it has | 261 // Class with a list of all active field trials. A trial is active if it has |
234 // been registered, which includes evaluating its state based on its probaility. | 262 // been registered, which includes evaluating its state based on its probaility. |
235 // Only one instance of this class exists. | 263 // Only one instance of this class exists. |
236 class BASE_EXPORT FieldTrialList { | 264 class BASE_EXPORT FieldTrialList { |
237 public: | 265 public: |
238 // Define a separator charactor to use when creating a persistent form of an | 266 // Define a separator charactor to use when creating a persistent form of an |
(...skipping 39 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
278 | 306 |
279 // Returns the group name chosen for the named trial, or the | 307 // Returns the group name chosen for the named trial, or the |
280 // empty string if the trial does not exist. | 308 // empty string if the trial does not exist. |
281 static std::string FindFullName(const std::string& name); | 309 static std::string FindFullName(const std::string& name); |
282 | 310 |
283 // Returns true if the named trial has been registered. | 311 // Returns true if the named trial has been registered. |
284 static bool TrialExists(const std::string& name); | 312 static bool TrialExists(const std::string& name); |
285 | 313 |
286 // Create a persistent representation of all FieldTrial instances and the | 314 // Create a persistent representation of all FieldTrial instances and the |
287 // |client_id()| state for resurrection in another process. This allows | 315 // |client_id()| state for resurrection in another process. This allows |
288 // randomization to be done in one process, and secondary processes can by | 316 // randomization to be done in one process, and secondary processes can be |
289 // synchronized on the result. The resulting string contains the | 317 // synchronized on the result. The resulting string contains the |
290 // |client_id()|, the names, the trial name, and a "/" separator. | 318 // |client_id()|, the names, the trial name, and a "/" separator. |
291 static void StatesToString(std::string* output); | 319 static void StatesToString(std::string* output); |
292 | 320 |
| 321 // Returns an array of Unique IDs for each Field Trial that has a chosen |
| 322 // group. Field Trials for which a group has not been chosen yet are NOT |
| 323 // returned in this list. |
| 324 static void GetFieldTrialNameGroupIds( |
| 325 std::vector<FieldTrial::NameGroupId>* name_group_ids); |
| 326 |
293 // Use a previously generated state string (re: StatesToString()) augment the | 327 // Use a previously generated state string (re: StatesToString()) augment the |
294 // current list of field tests to include the supplied tests, and using a 100% | 328 // current list of field tests to include the supplied tests, and using a 100% |
295 // probability for each test, force them to have the same group string. This | 329 // probability for each test, force them to have the same group string. This |
296 // is commonly used in a non-browser process, to carry randomly selected state | 330 // is commonly used in a non-browser process, to carry randomly selected state |
297 // in a browser process into this non-browser process. This method calls | 331 // in a browser process into this non-browser process. This method calls |
298 // CreateFieldTrial to create the FieldTrial in the non-browser process. | 332 // CreateFieldTrial to create the FieldTrial in the non-browser process. |
299 // Currently only the group_name_ and name_ are restored, as well as the | 333 // Currently only the group_name_ and name_ are restored, as well as the |
300 // |client_id()| state, that could be used for one-time randomized trials | 334 // |client_id()| state, that could be used for one-time randomized trials |
301 // set up only in child processes. | 335 // set up only in child processes. |
302 static bool CreateTrialsInChildProcess(const std::string& prior_trials); | 336 static bool CreateTrialsInChildProcess(const std::string& prior_trials); |
(...skipping 76 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
379 | 413 |
380 // List of observers to be notified when a group is selected for a FieldTrial. | 414 // List of observers to be notified when a group is selected for a FieldTrial. |
381 ObserverList<Observer> observer_list_; | 415 ObserverList<Observer> observer_list_; |
382 | 416 |
383 DISALLOW_COPY_AND_ASSIGN(FieldTrialList); | 417 DISALLOW_COPY_AND_ASSIGN(FieldTrialList); |
384 }; | 418 }; |
385 | 419 |
386 } // namespace base | 420 } // namespace base |
387 | 421 |
388 #endif // BASE_METRICS_FIELD_TRIAL_H_ | 422 #endif // BASE_METRICS_FIELD_TRIAL_H_ |
OLD | NEW |