Add one-time randomization support for FieldTrial, and the ability to

base/metrics/field_trial.h

Index: base/metrics/field_trial.h
diff --git a/base/metrics/field_trial.h b/base/metrics/field_trial.h
index dcfd39173a3ade9f4e9f4e0ff56caedfbd4d7738..3724907a880c5f162933fb6f9c54f3395611ac27 100644
--- a/base/metrics/field_trial.h
+++ b/base/metrics/field_trial.h
@@ -13,12 +13,13 @@
 // pseudo-randomly selected).
 //
 // States are typically generated randomly, either based on a one time
-// randomization (generated randomly once, and then persistently reused in the
-// client during each future run of the program), or by a startup randomization
+// randomization (which will yield the same results, in terms of selecting
+// the client for a field trial or not, for every run of the program on a
+// given machine, with some exceptions), or by a startup randomization
 // (generated each time the application starts up, but held constant during the
 // duration of the process), or by continuous randomization across a run (where
 // the state can be recalculated again and again, many times during a process).
-// Only startup randomization is implemented thus far.
+// Continuous randomization is not yet implemented.
 
 //------------------------------------------------------------------------------
 // Example:  Suppose we have an experiment involving memory, such as determining
@@ -107,10 +108,31 @@ class BASE_API FieldTrial : public RefCounted<FieldTrial> {
   // 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.
+  // Using this constructor creates a startup-randomized FieldTrial. If you
+  // want a one-time randomized trial, call UseOneTimeRandomization() right
+  // after construction.
   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);
 
+  // Changes the field trial to use one-time randomization. Must be called
+  // right after construction. |machine_id| must be something that is fairly
+  // diverse, related to the current machine, and does not change, or changes
+  // very infrequently, while running on the same machine. The reason it must
+  // be fairly diverse is that users with the same |machine_id| and the
+  // same log-on user name may end up in the same FieldTrial group.
+  //
+  // A suggested |machine_id| might be the host name, or something fancier
+  // such as the primary network adapter's MAC address or the hard disk's
+  // serial number.
+  //
+  // If an empty |machine_id| is given, the field trial will be disabled.
+  void UseOneTimeRandomization(const std::string& machine_id);

[jar (doing other things), 2011/04/21 01:03:50]

I'm not convinced you need an argument here, and clearly it puts a large burden
on the caller.  Can't we do without??

I'd rather see an interface that emulates persisted coin toss, with one toss per
persistent trial, than to require all coin-tosses on a single machine to always
come out the same way.  

[Jói, 2011/04/21 19:50:33]

Done.

+
+  // Disables this trial, meaning it always determines the default group
+  // has been selected. Must be called right after construction.
+  void Disable();

[jar (doing other things), 2011/04/21 01:03:50]

Traditionally, disabling meant we were not part of the field trial.  That state
is quite distinct from the default case, although we do eventually turn into a
disabled case when our time expires. 

The subtle distinction is visible in MakeName() and the pattern by which that
function is used in histograms.  When we are disabled, the user often has
over-ridden the target state, and hence the user can't be included in a
would-be-random population.

How will this fit in with your planned use case?

[Jói, 2011/04/21 19:50:33]

So I actually took a closer look at this logic.  It seems that group_name() can
never return the empty string, neither before nor after my change, as you are
always in one of the groups of a trial if the trial is registered.  I updated
the documentation to reflect this, including at the top where it shows how to
determine whether to produce a separate histogram name.  Please verify my
findings as you obviously know this code a lot better than I do.

+
   // Establish the name and probability of the next group in this trial.
   // Sometimes, based on construction randomization, this call may cause the
   // provided group to be *THE* group selected for use in this instance.
@@ -123,7 +145,7 @@ class BASE_API FieldTrial : public RefCounted<FieldTrial> {
   // Return the randomly selected group number that was assigned.
   // 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.
+  // to attempt to probabilistically add any other groups to the trial.
   int group();
 
   // If the field trial is not in an experiment, this returns the empty string.
@@ -134,7 +156,7 @@ class BASE_API FieldTrial : public RefCounted<FieldTrial> {
   // Return the default group name of the FieldTrial.
   std::string default_group_name() const { return default_group_name_; }
 
-  // Helper function for the most common use: as an argument to specifiy the
+  // Helper function for the most common use: as an argument to specify 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);
@@ -154,6 +176,9 @@ class BASE_API FieldTrial : public RefCounted<FieldTrial> {
   FRIEND_TEST(FieldTrialTest, Save);
   FRIEND_TEST(FieldTrialTest, DuplicateRestore);
   FRIEND_TEST(FieldTrialTest, MakeName);
+  FRIEND_TEST(FieldTrialTest, MachineIdToUniformDouble);
+  FRIEND_TEST(FieldTrialTest, ProbabilisticMachineIdToUniformDoubleIsUniform);
+  FRIEND_TEST(FieldTrialTest, UseOneTimeRandomization);
 
   friend class base::FieldTrialList;
 
@@ -167,6 +192,10 @@ class BASE_API FieldTrial : public RefCounted<FieldTrial> {
   // Get build time.
   static Time GetBuildTime();
 
+  // Calculates a uniformly-distributed double between [0.0, 1.0) given
+  // a |machine_id|.
+  static double MachineIdToUniformDouble(const std::string& machine_id);
+
   // 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_;
@@ -181,7 +210,7 @@ class BASE_API FieldTrial : public RefCounted<FieldTrial> {
   // 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).
-  const Probability random_;
+  Probability random_;
 
   // Sum of the probabilities of all appended groups.
   Probability accumulated_group_probability_;