Feature to disable field trials in old versions of Chromium. Field trials...

base/metrics/field_trial.h

 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // FieldTrial is a class for handling details of statistical experiments
 // performed by actual users in the field (i.e., in a shipped or beta product).
 // All code is called exclusively on the UI thread currently.
 //
 // The simplest example is an experiment to see whether one of two options
 // produces "better" results across our user population.  In that scenario, UMA
@@ skipping 48 matching lines @@
 
 //------------------------------------------------------------------------------
 
 #ifndef BASE_METRICS_FIELD_TRIAL_H_
 #define BASE_METRICS_FIELD_TRIAL_H_
 #pragma once
 
 #include <map>
 #include <string>
 
+#include "base/gtest_prod_util.h"
 #include "base/lock.h"
 #include "base/ref_counted.h"
 #include "base/time.h"
 
 namespace base {
 
 class FieldTrial : public RefCounted<FieldTrial> {
  public:
   typedef int Probability;  // Probability type for being selected in a trial.
 
   // A return value to indicate that a given instance has not yet had a group
   // assignment (and hence is not yet participating in the trial).
-  static const int kNotParticipating;
+  static const int kNotFinalized;
 
-  // Provide an easy way to assign all remaining probability to a group.  Note
-  // that this will force an instance to participate, and make it illegal to
-  // attempt to probabalistically add any other groups to the trial.  When doing
-  // A/B tests with timings, it is often best to define all groups, so that
-  // histograms will get unique names via the MakeName() methods.
-  static const Probability kAllRemainingProbability;
+  // This is the group number of the 'default' group. This provides an easy way
+  // to assign all the remaining probability to a group ('default').
+  static const int kDefaultGroupNumber;
 
   // The name is used to register the instance with the FieldTrialList class,
   // and can be used to find the trial (only one trial can be present for each
   // name).
   // Group probabilities that are later supplied must sum to less than or equal
-  // to the total_probability.
-  FieldTrial(const std::string& name, Probability total_probability);
+  // to the total_probability. Arguments year, month and day_of_month specify
+  // the expiration time. If the build time is after the expiration time then
+  // the field trial reverts to the 'default' group.
+  FieldTrial(const std::string& name, Probability total_probability,
+             const std::string& default_group_name, const int year,
+             const int month, const int day_of_month);
 
   // Establish the name and probability of the next group in this trial.
   // Sometimes, based on construction randomization, this call may causes the
   // provided group to be *THE* group selected for use in this instance.
   int AppendGroup(const std::string& name, Probability group_probability);
 
   // Return the name of the FieldTrial (excluding the group name).
   std::string name() const { return name_; }
 
   // Return the randomly selected group number that was assigned.
-  // Return kNotParticipating if the instance is not participating in the
-  // experiment.
-  int group() const { return group_; }
+  // Return kDefaultGroupNumber if the instance is in the 'default' group.
+  // Note that this will force an instance to participate, and make it illegal
+  // to attempt to probabalistically add any other groups to the trial. When
+  // doing A/B tests with timings, it is often best to define all groups, so
+  // that histograms will get unique names via the MakeName() methods.

[jar (doing other things), 2011/01/15 20:52:47]

Comment looks great up to the last sentence. 

The last sentence about "defin all groupss" should be moved to the AddGroup()
method.  I think you mean to say something about each group name should be
unique, rather than define all groups, as every group is "defined" when you add
it.  Perhaps you wanted to say the group name should not be an empty string...
and that might better be enforced as a DCHECK.

+  int group();
 
   // If the field trial is not in an experiment, this returns the empty string.
   // if the group's name is empty, a name of "_" concatenated with the group
   // number is used as the group name.
   std::string group_name() const { return group_name_; }
 
   // Helper function for the most common use: as an argument to specifiy the
   // name of a HISTOGRAM.  Use the original histogram name as the name_prefix.
   static std::string MakeName(const std::string& name_prefix,
                               const std::string& trial_name);
 
   // Enable benchmarking sets field trials to a common setting.
   static void EnableBenchmarking();
 
  private:
+  // Allow tests to access our innards for testing purposes.
+  FRIEND_TEST(FieldTrialTest, Registration);
+  FRIEND_TEST(FieldTrialTest, AbsoluteProbabilities);
+  FRIEND_TEST(FieldTrialTest, RemainingProbability);
+  FRIEND_TEST(FieldTrialTest, FiftyFiftyProbability);
+  FRIEND_TEST(FieldTrialTest, MiddleProbabilities);
+  FRIEND_TEST(FieldTrialTest, OneWinner);
+  FRIEND_TEST(FieldTrialTest, DisableProbability);
+  FRIEND_TEST(FieldTrialTest, Save);
+  FRIEND_TEST(FieldTrialTest, DuplicateRestore);
+  FRIEND_TEST(FieldTrialTest, MakeName);
+
   friend class RefCounted<FieldTrial>;
 
   virtual ~FieldTrial();
 
+  // Get build time.
+  static Time GetBuildTime();
+
   // The name of the field trial, as can be found via the FieldTrialList.
   // This is empty of the trial is not in the experiment.
   const std::string name_;
 
   // The maximum sum of all probabilities supplied, which corresponds to 100%.
   // This is the scaling factor used to adjust supplied probabilities.
   Probability divisor_;
 
+  // The name of the default group.
+  const std::string default_group_name_;
+
   // The randomly selected probability that is used to select a group (or have
   // the instance not participate).  It is the product of divisor_ and a random
   // number between [0, 1).
   Probability random_;
 
   // Sum of the probabilities of all appended groups.
   Probability accumulated_group_probability_;
 
   int next_group_number_;
 
   // The pseudo-randomly assigned group number.
-  // This is kNotParticipating if no group has been assigned.
+  // This is kNotFinalized if no group has been assigned.
   int group_;
 
   // A textual name for the randomly selected group, including the Trial name.
   // If this Trial is not a member of an group, this string is empty.
   std::string group_name_;
 
+  // The expiration_year_, expiration_month_ and expiration_day_of_month_ are
+  // used to compute expiration time. If expiration time is after the build time
+  // of the module, then field trial reverts to the 'default' group.
+  int expiration_year_;
+  int expiration_month_;
+  int expiration_day_of_month_;
+
+  // When disable_field_trial_ is true, field trial reverts to the 'default'
+  // group.
+  bool disable_field_trial_;
+
   // When benchmarking is enabled, field trials all revert to the 'default'
-  // bucket.
+  // group.
   static bool enable_benchmarking_;
 
   DISALLOW_COPY_AND_ASSIGN(FieldTrial);
 };
 
 //------------------------------------------------------------------------------
 // Class with a list of all active field trials.  A trial is active if it has
 // been registered, which includes evaluating its state based on its probaility.
 // Only one instance of this class exists.
 class FieldTrialList {
@@ skipping 73 matching lines @@
   Lock lock_;
   RegistrationList registered_;
 
   DISALLOW_COPY_AND_ASSIGN(FieldTrialList);
 };
 
 }  // namespace base
 
 #endif  // BASE_METRICS_FIELD_TRIAL_H_