Expand FeatureList to support FieldTrial association.

base/feature_list.h

 // Copyright 2015 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.
 
 #ifndef BASE_FEATURE_LIST_H_
 #define BASE_FEATURE_LIST_H_
 
 #include <map>
 #include <string>
+#include <utility>
 
 #include "base/base_export.h"
 #include "base/basictypes.h"
 #include "base/gtest_prod_util.h"
 #include "base/memory/scoped_ptr.h"
 #include "base/synchronization/lock.h"
 
 namespace base {
 
+class FieldTrial;
+
 // Specifies whether a given feature is enabled or disabled by default.
 enum FeatureState {
   FEATURE_DISABLED_BY_DEFAULT,
   FEATURE_ENABLED_BY_DEFAULT,
 };
 
 // The Feature struct is used to define the default state for a feature. See
 // comment below for more details. There must only ever be one struct instance
 // for a given feature name - generally defined as a constant global variable or
 // file static.
@@ skipping 47 matching lines @@
   ~FeatureList();
 
   // Initializes feature overrides via command-line flags |enable_features| and
   // |disable_features|, each of which is a comma-separated list of features to
   // enable or disable, respectively. If a feature appears on both lists, then
   // it will be disabled. Must only be invoked during the initialization phase
   // (before FinalizeInitialization() has been called).
   void InitializeFromCommandLine(const std::string& enable_features,
                                  const std::string& disable_features);
 
+  // Specifies whether a feature override enables or disables the feature.
+  enum OverrideState {
+    OVERRIDE_DISABLE_FEATURE,
+    OVERRIDE_ENABLE_FEATURE,
+  };
+
+  // Registers a field trial to override the enabled state of the specified
+  // feature to |override_state|. Command-line overrides still take precedence
+  // over field trials, so this will have no effect if the feature is being
+  // overridden from the command-line. The associated field trial will be
+  // activated when the feature state for this feature is queried. This should
+  // be called during registration, after InitializeFromCommandLine() has been
+  // called but before the instance is registered via SetInstance().
+  void RegisterFieldTrialOverride(const std::string& feature_name,
+                                  OverrideState override_state,
+                                  FieldTrial* field_trial);
+
+  // Creates and associates a field trial for reporting purposes corresponding
+  // to the command-line setting the feature state to |for_overridden_state|.
+  // This is a no-op and returns null if the specified feature is not being
+  // affected by a command-line override to the given state. Otherwise, it
+  // creates a field trial with name |field_trial_name| and a single group named
+  // |group_name| and returns it. The trial will be activated when the state of
+  // the feature is queried. This should be called during registration, after
+  // InitializeFromCommandLine() has been called but before the instance is
+  // registered via SetInstance().
+  FieldTrial* AssociateReportingFieldTrial(const std::string& feature_name,
+                                           OverrideState for_overridden_state,
+                                           const std::string& field_trial_name,
+                                           const std::string& group_name);
+
   // Returns whether the given |feature| is enabled. Must only be called after
   // the singleton instance has been registered via SetInstance(). Additionally,
   // a feature with a given name must only have a single corresponding Feature
   // struct, which is checked in builds with DCHECKs enabled.
   static bool IsEnabled(const Feature& feature);
 
   // Returns the singleton instance of FeatureList. Will return null until an
   // instance is registered via SetInstance().
   static FeatureList* GetInstance();
 
   // Registers the given |instance| to be the singleton feature list for this
   // process. This should only be called once and |instance| must not be null.
   static void SetInstance(scoped_ptr<FeatureList> instance);
 
   // Clears the previously-registered singleton instance for tests.
   static void ClearInstanceForTesting();
 
  private:
   FRIEND_TEST_ALL_PREFIXES(FeatureListTest, CheckFeatureIdentity);
 
-  // Specifies whether a feature override enables or disables the feature.
-  enum OverrideState {
-    OVERRIDE_DISABLE_FEATURE,
-    OVERRIDE_ENABLE_FEATURE,
+  struct OverrideEntry {
+    // The overridden enable (on/off) state of the feature.
+    const OverrideState overridden_state;
+
+    // An optional associated field trial, which will be activated when the
+    // state of the feature is queried for the first time. Weak pointer to the
+    // FieldTrial object that is owned by the FieldTrialList singleton.
+    base::FieldTrial* field_trial;
+
+    // TODO(asvitkine): Expand this as more support is added.
+
+    OverrideEntry(OverrideState overridden_state, FieldTrial* field_trial);
   };
 
   // Finalizes the initialization state of the FeatureList, so that no further
   // overrides can be registered. This is called by SetInstance() on the
   // singleton feature list that is being registered.
   void FinalizeInitialization();
 
   // Returns whether the given |feature| is enabled. This is invoked by the
   // public FeatureList::IsEnabled() static function on the global singleton.
   // Requires the FeatureList to have already been fully initialized.
   bool IsFeatureEnabled(const Feature& feature);
 
   // Registers an override for feature |feature_name|. The override specifies
   // whether the feature should be on or off (via |overridden_state|), which
-  // will take precedence over the feature's default state.
-  void RegisterOverride(const std::string& feature_name,
-                        OverrideState overridden_state);
+  // will take precedence over the feature's default state. If |field_trial| is
+  // not null, registers the specified field trial object to be associated with
+  // the feature, which will activate the field trial when the feature state is
+  // queried. If an override is already registered for the given feature, it
+  // will not be changed. Returns a pair<entry, bool>, where the bool indicates
+  // whether the override was registered and entry is the entry in the map -
+  // either the existing one or the one that was inserted.
+  std::pair<const FeatureList::OverrideEntry&, bool> RegisterOverride(
+      const std::string& feature_name,
+      OverrideState overridden_state,
+      FieldTrial* field_trial);
 
   // Verifies that there's only a single definition of a Feature struct for a
   // given feature name. Keeps track of the first seen Feature struct for each
   // feature. Returns false when called on a Feature struct with a different
   // address than the first one it saw for that feature name. Used only from
   // DCHECKs and tests.
   bool CheckFeatureIdentity(const Feature& feature);
 
-  struct OverrideEntry {
-    // The overridden enable (on/off) state of the feature.
-    const OverrideState overridden_state;
-
-    // TODO(asvitkine): Expand this as more support is added.
-
-    explicit OverrideEntry(OverrideState overridden_state);
-  };
   // Map from feature name to an OverrideEntry struct for the feature, if it
   // exists.
   std::map<std::string, OverrideEntry> overrides_;
 
   // Locked map that keeps track of seen features, to ensure a single feature is
   // only defined once. This verification is only done in builds with DCHECKs
   // enabled.
   Lock feature_identity_tracker_lock_;
   std::map<std::string, const Feature*> feature_identity_tracker_;
 
   // Whether this object has been fully initialized. This gets set to true as a
   // result of FinalizeInitialization().
   bool initialized_;
 
   DISALLOW_COPY_AND_ASSIGN(FeatureList);
 };
 
 }  // namespace base
 
 #endif  // BASE_FEATURE_LIST_H_