Added a Unique ID for a Field Trial containing it's hashed name and the selected group ID.

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 74 matching lines @@
 #include "base/synchronization/lock.h"
 #include "base/time.h"
 
 namespace base {
 
 class FieldTrialList;
 
 class BASE_EXPORT FieldTrial : public RefCounted<FieldTrial> {
  public:
   typedef int Probability;  // Probability type for being selected in a trial.
+  // The Unique ID of a trial, where the name and group identifiers are
+  // hashes of the trial and group name strings.
+  struct NameGroupId{

[Alexei Svitkine (slow), 2012/01/25 15:25:19]

Nit: Add a space before {.

[MAD, 2012/01/25 17:02:33]

Done.

+    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;
 
+  // This value is reserved for an uninitialized hash value.
+  static const uint32 kReservedHashValue;
+
   // 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
@@ skipping 27 matching lines @@
   // 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.
   std::string group_name();
 
+  // Gets the unique identifier of the Field Trial, but only if a winner was
+  // elected. Returns true if a winner is returned, false otherwise.

[Alexei Svitkine (slow), 2012/01/25 15:25:19]

Can you reword this to either explain what you mean by "winner", or using
different terms? Also "Returns true if a winner is returned" could be worded
better, even if you do wish to keep the term "winner".

[MAD, 2012/01/25 17:02:33]

Done.

+  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.
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, Registration);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, AbsoluteProbabilities);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, RemainingProbability);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, FiftyFiftyProbability);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, MiddleProbabilities);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, OneWinner);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, DisableProbability);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, Save);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, DuplicateRestore);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, MakeName);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, HashClientId);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, HashClientIdIsUniform);
   FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, UseOneTimeRandomization);
+  FRIEND_TEST_ALL_PREFIXES(FieldTrialTest, NameGroupIds);
 
   friend class base::FieldTrialList;
 
   friend class RefCounted<FieldTrial>;
 
   virtual ~FieldTrial();
 
   // 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 the name string.

[Alexei Svitkine (slow), 2012/01/25 15:25:19]

The comment should probably mention that this hash function is used for hashing
both name and group name, not just the name.

[MAD, 2012/01/25 17:02:33]

Done.

+  static uint32 HashName(const std::string& name);
+
   // The name of the field trial, as can be found via the FieldTrialList.
   const std::string name_;
 
+  // The hashed name of the field trial to be sent as a unique identifier.
+  const uint32 name_hash_;
+
   // The maximum sum of all probabilities supplied, which corresponds to 100%.
   // This is the scaling factor used to adjust supplied probabilities.
   const 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 kNotFinalized if no group has been assigned.
   int group_;
 
   // A textual name for the randomly selected group. Valid after |group()|
   // has been called.
   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 benchmarking is enabled, field trials all revert to the 'default'
   // group.
   static bool enable_benchmarking_;
 
   DISALLOW_COPY_AND_ASSIGN(FieldTrial);
 };
@@ skipping 47 matching lines @@
 
   // 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 by
+  // 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.
   static void StatesToString(std::string* output);
 
+  // Returns an array of Unique IDs for each currently running Field Trials.

[Alexei Svitkine (slow), 2012/01/25 15:25:19]

Can you expand this comment to explain what "currently running" means? e.g. that
if a group hasn't been chosen yet, then it is not included.

[MAD, 2012/01/25 17:02:33]

Done.

+  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);
@@ skipping 76 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_