Supporting command line argument to force field trials

base/metrics/field_trial.h

-// Copyright (c) 2011 The Chromium Authors. All rights reserved.
+// Copyright (c) 2012 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
 // data is uploaded to aggregate the test results, and this FieldTrial class
@@ skipping 84 matching lines @@
   // hashes of the trial and group name strings.
   struct NameGroupId {
     uint32 name;
     uint32 group;
   };
 
   // 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 kNotFinalized;
 
-  // 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).  |name| and |default_group_name| may not be empty.
-  //
-  // Group probabilities that are later supplied must sum to less than or equal
-  // 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, i.e. produce the
   // same result for the current trial on every run of this client. Must be
   // called right after construction.
   void UseOneTimeRandomization();
 
   // Disables this trial, meaning it always determines the default group
   // has been selected. May be called immediately after construction, or
   // at any time after initialization (should not be interleaved with
   // AppendGroup calls). Once disabled, there is no way to re-enable a
   // trial.
+  // TODO(mad): http://code.google.com/p/chromium/issues/detail?id=121446
+  // This doesn't properly reset to Default when a group was forced.
   void Disable();
 
   // 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.
   // The return value is the group number of the new group.
   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 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 probabilistically add any other groups to the trial.
   int group();
 
-  // If the group's name is empty, a string version containing the group
-  // number is used as the group name.
+  // If the group's name is empty, a string version containing the group number
+  // is used as the group name. This causes a winner to be chosen if none was.
   std::string group_name();
 
   // Gets the unique identifier of the Field Trial, but only if a group was
   // officially chosen, otherwise name_group_id is left untouched and false
-  // is returned. When true is returned, the name and group ids were successfuly
-  // set in name_group_id.
+  // is returned. When true is returned, the name and group ids were
+  // successfully set in name_group_id.
   bool GetNameGroupId(NameGroupId* name_group_id);
 
-  // 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 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);
 
   // Enable benchmarking sets field trials to a common setting.
   static void EnableBenchmarking();
 
  private:
   // Allow tests to access our innards for testing purposes.
@@ skipping 10 matching lines @@
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, HashClientId);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, HashClientIdIsUniform);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, HashName);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, NameGroupIds);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, UseOneTimeRandomization);
 
   friend class base::FieldTrialList;
 
   friend class RefCounted<FieldTrial>;
 
+  // This is the group number of the 'default' group when a choice wasn't forced
+  // by a call to FieldTrialList::CreateFieldTrial. It is kept private so that
+  // consumers don't use it by mistake in cases where the group was forced.
+  static const int kDefaultGroupNumber;
+
+  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);
   virtual ~FieldTrial();
 
+  // Return the default group name of the FieldTrial.
+  std::string default_group_name() const { return default_group_name_; }
+
   // Returns the group_name. A winner need not have been chosen.
   std::string group_name_internal() const { return group_name_; }
 
   // Calculates a uniformly-distributed double between [0.0, 1.0) given
   // a |client_id| and a |trial_name| (the latter is used as salt to avoid
   // separate one-time randomized trials from all having the same results).
   static double HashClientId(const std::string& client_id,
                              const std::string& trial_name);
 
   // Creates unique identifier for the trial by hashing a name string, whether
@@ skipping 32 matching lines @@
   std::string group_name_;
 
   // The hashed name of the group to be sent as a unique identifier.
   // Is not valid while group_ is equal to kNotFinalized.
   uint32 group_name_hash_;
 
   // When enable_field_trial_ is false, field trial reverts to the 'default'
   // group.
   bool enable_field_trial_;
 
+  // When forced_ is true, we return the chosen group from AppendGroup when
+  // appropriate.
+  bool forced_;
+
   // When benchmarking is enabled, field trials all revert to the 'default'
   // group.
   static bool enable_benchmarking_;
 
   // This value is reserved for an uninitialized hash value.
   static const uint32 kReservedHashValue;
 
   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 BASE_EXPORT FieldTrialList {
  public:
-  // Define a separator charactor to use when creating a persistent form of an
+  // Define a separator character to use when creating a persistent form of an
   // instance.  This is intended for use as a command line argument, passed to a
   // second process to mimic our state (i.e., provide the same group name).
   static const char kPersistentStringSeparator;  // Currently a slash.
 
   // Define expiration year in future. It is initialized to two years from Now.
   static int kExpirationYearInFuture;
 
   // Observer is notified when a FieldTrial's group is selected.
   class Observer {
    public:
     // Notify observers when FieldTrials's group is selected.
     virtual void OnFieldTrialGroupFinalized(const std::string& trial_name,
                                             const std::string& group_name) = 0;
 
    protected:
     virtual ~Observer() {}
   };
 
   // This singleton holds the global list of registered FieldTrials.
   //
   // |client_id| should be an opaque, diverse ID for this client that does not
   // change between sessions, to enable one-time randomized trials. The empty
   // string may be provided, in which case one-time randomized trials will
   // not be available.
   explicit FieldTrialList(const std::string& client_id);
   // Destructor Release()'s references to all registered FieldTrial instances.
   ~FieldTrialList();
 
-  // Register() stores a pointer to the given trial in a global map.
-  // This method also AddRef's the indicated trial.
-  static void Register(FieldTrial* trial);
+  // Creates a new FieldTrial instance if none exists already. If one exists,
+  // it has to be because it was forced by CreateFieldTrial.

[jar (doing other things), 2012/04/06 01:41:29]

nit: I had to read the sentence a few times, and stumbled over "...it has to be
because it was..."

IMO, the subtle distinction between "finding an existing instance" and "creates"
should not be surfaced here, as that is an internal element of the
implementation.  For instance, a list of "forced" group-results could be stored
separately, and then the construction (which might take place now!) could have
adjusted to their planned/forced state.

IMO, this CL just changes from using a constructor, to using a Factory, and the
factory has more liberties about construction and reuse... but that is hidden
inside the implementation.  

I'd suggest you use that metaphor, and you can leave your implementation hidden
more cleanly.  I'd suggest this function should probably be called something
more like:
FactoryGetFieldTrial()

IF you don't like that picture, and want to stay with the current commentary
(exposing the hidden fact that the instance may already be created) I'd suggest
changing your wording to something like:
Generally, this function should only be called once by a caller.  If the field
trial exists prior to this call, then it was probably created by a call to
CreateFieldTrial, which forced a specific group result.  Such pre-existence
should be transparent to the caller.

[MAD, 2012/04/11 02:38:08]

OK, I agree, I like this picture... Thanks!
Done.

+  //
+  // |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). |default_group_name| is the name of the default group which will
+  // be chosen if none of the subsequent appended groups get to be chosen.
+  // |default_group_number| can receive the group number of the default group as
+  // AppendGroup returns the number of the subsequence groups. |name| and
+  // |default_group_name| may not be empty but |default_group_number| can be
+  // NULL if the value is not needed.
+  //
+  // Group probabilities that are later supplied must sum to less than or equal
+  // 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.
+  //
+  // Use this static method to get a startup-randomized FieldTrial or a
+  // previously created forced FieldTrial. If you want a one-time randomized
+  // trial, call UseOneTimeRandomization() right after creation.
+  static FieldTrial* GetFieldTrialInstance(
+      const std::string& name, FieldTrial::Probability total_probability,

[jar (doing other things), 2012/04/06 01:41:29]

nit: I think it is more readable with one parameter per line once you had to
wrap, and that might follow from the style rule: "All parameters should be
aligned if possible" 

[MAD, 2012/04/11 02:38:08]

Done.

+      const std::string& default_group_name, int* default_group_number,

[jar (doing other things), 2012/04/06 01:41:29]

Since the return group number is a "return argument," it should be placed at the
end of the arg list, after all the "input" arguments.

[MAD, 2012/04/11 02:38:08]

Done.

+      const int year, const int month, const int day_of_month);
 
   // The Find() method can be used to test to see if a named Trial was already
   // registered, or to retrieve a pointer to it from the global map.
   static FieldTrial* Find(const std::string& name);
 
   // Returns the group number chosen for the named trial, or
   // FieldTrial::kNotFinalized if the trial does not exist.
   static int FindValue(const std::string& name);
 
   // Returns the group name chosen for the named trial, or the
   // empty string if the trial does not exist.
   static std::string FindFullName(const std::string& name);
 
   // Returns true if the named trial has been registered.
   static bool TrialExists(const std::string& name);
 
-  // Create a persistent representation of all FieldTrial instances and the
-  // |client_id()| state for resurrection in another process.  This allows
-  // randomization to be done in one process, and secondary processes can be
-  // synchronized on the result. The resulting string contains the
-  // |client_id()|, the names, the trial name, and a "/" separator.
+  // Creates a persistent representation of all FieldTrial instances for
+  // resurrection in another process. This allows randomization to be done in
+  // one process, and secondary processes can be synchronized on the result.
+  // The resulting string contains the name and group name pairs for all trials,
+  // with "/" used to separate all names and to terminate the string. This
+  // string is parsed by CreateTrialsFromString().
   static void StatesToString(std::string* output);
 
   // Returns an array of Unique IDs for each Field Trial that has a chosen
   // group. Field Trials for which a group has not been chosen yet are NOT
   // returned in this list.
   static void GetFieldTrialNameGroupIds(
       std::vector<FieldTrial::NameGroupId>* name_group_ids);
 
-  // Use a previously generated state string (re: StatesToString()) augment the
-  // current list of field tests to include the supplied tests, and using a 100%
-  // probability for each test, force them to have the same group string.  This
-  // is commonly used in a non-browser process, to carry randomly selected state
-  // in a browser process into this non-browser process. This method calls
-  // CreateFieldTrial to create the FieldTrial in the non-browser process.
-  // Currently only the group_name_ and name_ are restored, as well as the
-  // |client_id()| state, that could be used for one-time randomized trials
-  // set up only in child processes.
-  static bool CreateTrialsInChildProcess(const std::string& prior_trials);
+  // Use a state string (re: StatesToString()) to augment the current list of
+  // field tests to include the supplied tests, and using a 100% probability for
+  // each test, force them to have the same group string.  This is commonly used
+  // in a non-browser process, to carry randomly selected state in a browser
+  // process into this non-browser process, but could also be invoked through a
+  // command line argument to the browser process.
+  static bool CreateTrialsFromString(const std::string& prior_trials);
 
   // Create a FieldTrial with the given |name| and using 100% probability for
   // the FieldTrial, force FieldTrial to have the same group string as
   // |group_name|. This is commonly used in a non-browser process, to carry
   // randomly selected state in a browser process into this non-browser process.
-  // Currently only the group_name_ and name_ are set in the FieldTrial. It
-  // returns NULL if there is a FieldTrial that is already registered with the
-  // same |name| but has different finalized group string (|group_name|).
+  // It returns NULL if there is a FieldTrial that is already registered with
+  // the same |name| but has different finalized group string (|group_name|).
   static FieldTrial* CreateFieldTrial(const std::string& name,
                                       const std::string& group_name);
 
   // Add an observer to be notified when a field trial is irrevocably committed
   // to being part of some specific field_group (and hence the group_name is
   // also finalized for that field_trial).
   static void AddObserver(Observer* observer);
 
   // Remove an observer.
   static void RemoveObserver(Observer* observer);
@@ skipping 28 matching lines @@
   // Returns the empty string if one-time randomization is not enabled.
   static const std::string& client_id();
 
  private:
   // A map from FieldTrial names to the actual instances.
   typedef std::map<std::string, FieldTrial*> RegistrationList;
 
   // Helper function should be called only while holding lock_.
   FieldTrial* PreLockedFind(const std::string& name);
 
+  // Register() stores a pointer to the given trial in a global map.
+  // This method also AddRef's the indicated trial.
+  // This should always be called after creating a new FieldTrial instance.
+  static void Register(FieldTrial* trial);
+
   static FieldTrialList* global_;  // The singleton of this class.
 
   // This will tell us if there is an attempt to register a field
   // trial or check if one-time randomization is enabled without
   // creating the FieldTrialList. This is not an error, unless a
   // FieldTrialList is created after that.
   static bool used_without_global_;
 
   // A helper value made available to users, that shows when the FieldTrialList
   // was initialized.  Note that this is a singleton instance, and hence is a
@@ skipping 10 matching lines @@
 
   // List of observers to be notified when a group is selected for a FieldTrial.
   ObserverList<Observer> observer_list_;
 
   DISALLOW_COPY_AND_ASSIGN(FieldTrialList);
 };
 
 }  // namespace base
 
 #endif  // BASE_METRICS_FIELD_TRIAL_H_