Construct a field trial to see if HIGH or MEDIUM memory model "works better"

Includes definition of a FieldTrial class to support this.
I have thoughts in my head about how this will eventually
extend to be controllable via UMA (as well as being able
to run tests defined at compile time, as was done in this
example.


r=mbelshe, mmentovai
Review URL: http://codereview.chromium.org/7638

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@3604 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 92 insertions, 0 deletions

diff --git a/base/field_trial.h b/base/field_trial.h
new file mode 100644
index 0000000..e70ab1a
--- /dev/null
+++ b/base/field_trial.h
@@ -0,0 +1,92 @@
+// Copyright (c) 2006-2008 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 a test to see whether one of two options produces
+// "better" results across our user population.  In that scenario, UMA data
+// is uploaded to show the test results, and this class manages the state of
+// each such test (state == which option was pseudo-randomly selected).
+// States are typically generated randomly, either based on a one time
+// randomization (reused during each run of the program), or by a startup
+// randomization (keeping that tests state constant across a run), or by
+// continuous randomization across a run.
+// Only startup randomization is implemented (thus far).
+
+#ifndef BASE_FIELD_TRIAL_H_
+#define BASE_FIELD_TRIAL_H_
+
+#include <map>
+#include <string>
+
+#include "base/non_thread_safe.h"
+#include "base/ref_counted.h"
+#include "base/time.h"
+
+class FieldTrial : public base::RefCounted<FieldTrial> {
+ public:
+  // Constructor for a 2-state (boolean) trial.
+  // 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) using the Find() method.
+  // The probability is a number in the range [0, 1], and is the likliehood that
+  // the assigned boolean value will be true.
+  FieldTrial(const std::wstring& name, double probability);
+
+  // Return the selected boolean value.
+  bool boolean_value() const { return boolean_value_; }
+  std::wstring name() const { return name_; }
+
+ private:
+  const std::wstring name_;
+  bool boolean_value_;
+
+  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 : NonThreadSafe {
+ public:
+  // This singleton holds the global list of registered FieldTrials.
+  FieldTrialList();
+  // 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);
+
+  // 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::wstring& name);
+
+  // The time of construction of the global map is recorded in a static variable
+  // and is commonly used by experiments to identify the time since the start
+  // of the application.  In some experiments it may be useful to discount
+  // data that is gathered before the application has reach sufficient
+  // stability (example: most DLL have loaded, etc.)
+  static Time application_start_time() {
+    return global_->application_start_time_;
+  }
+
+ private:
+  typedef std::map<std::wstring, FieldTrial*> RegistrationList;
+
+  friend class FieldTrialTest;
+  static void ResetConstructorCountForTestingOnly() { constructor_count_ = 0; }
+
+  static FieldTrialList* global_;  // The singleton of this class.
+  static int constructor_count_;   // Prevent having more than one.
+
+  Time application_start_time_;
+  RegistrationList registered_;
+
+  DISALLOW_COPY_AND_ASSIGN(FieldTrialList);
+};
+
+#endif  // BASE_FIELD_TRIAL_H_