1 // Copyright 2015 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_FEATURE_LIST_H_ 6 #define BASE_FEATURE_LIST_H_ 7 8 #include <map> 9 #include <memory> 10 #include <string> 11 #include <vector> 12 13 #include "base/base_export.h" 14 #include "base/gtest_prod_util.h" 15 #include "base/macros.h" 16 #include "base/metrics/persistent_memory_allocator.h" 17 #include "base/strings/string_piece.h" 18 #include "base/synchronization/lock.h" 19 20 namespace base { 21 22 class FieldTrial; 23 24 // Specifies whether a given feature is enabled or disabled by default. 25 enum FeatureState { 26 FEATURE_DISABLED_BY_DEFAULT, 27 FEATURE_ENABLED_BY_DEFAULT, 28 }; 29 30 // The Feature struct is used to define the default state for a feature. See 31 // comment below for more details. There must only ever be one struct instance 32 // for a given feature name - generally defined as a constant global variable or 33 // file static. It should never be used as a constexpr as it breaks 34 // pointer-based identity lookup. 35 struct BASE_EXPORT Feature { 36 // The name of the feature. This should be unique to each feature and is used 37 // for enabling/disabling features via command line flags and experiments. 38 // It is strongly recommended to use CamelCase style for feature names, e.g. 39 // "MyGreatFeature". 40 const char* const name; 41 42 // The default state (i.e. enabled or disabled) for this feature. 43 const FeatureState default_state; 44 }; 45 46 #if DCHECK_IS_CONFIGURABLE 47 // DCHECKs have been built-in, and are configurable at run-time to be fatal, or 48 // not, via a DcheckIsFatal feature. We define the Feature here since it is 49 // checked in FeatureList::SetInstance(). See https://crbug.com/596231. 50 extern BASE_EXPORT const Feature kDCheckIsFatalFeature; 51 #endif // DCHECK_IS_CONFIGURABLE 52 53 // The FeatureList class is used to determine whether a given feature is on or 54 // off. It provides an authoritative answer, taking into account command-line 55 // overrides and experimental control. 56 // 57 // The basic use case is for any feature that can be toggled (e.g. through 58 // command-line or an experiment) to have a defined Feature struct, e.g.: 59 // 60 // const base::Feature kMyGreatFeature { 61 // "MyGreatFeature", base::FEATURE_ENABLED_BY_DEFAULT 62 // }; 63 // 64 // Then, client code that wishes to query the state of the feature would check: 65 // 66 // if (base::FeatureList::IsEnabled(kMyGreatFeature)) { 67 // // Feature code goes here. 68 // } 69 // 70 // Behind the scenes, the above call would take into account any command-line 71 // flags to enable or disable the feature, any experiments that may control it 72 // and finally its default state (in that order of priority), to determine 73 // whether the feature is on. 74 // 75 // Features can be explicitly forced on or off by specifying a list of comma- 76 // separated feature names via the following command-line flags: 77 // 78 // --enable-features=Feature5,Feature7 79 // --disable-features=Feature1,Feature2,Feature3 80 // 81 // To enable/disable features in a test, do NOT append --enable-features or 82 // --disable-features to the command-line directly. Instead, use 83 // ScopedFeatureList. See base/test/scoped_feature_list.h for details. 84 // 85 // After initialization (which should be done single-threaded), the FeatureList 86 // API is thread safe. 87 // 88 // Note: This class is a singleton, but does not use base/memory/singleton.h in 89 // order to have control over its initialization sequence. Specifically, the 90 // intended use is to create an instance of this class and fully initialize it, 91 // before setting it as the singleton for a process, via SetInstance(). 92 class BASE_EXPORT FeatureList { 93 public: 94 FeatureList(); 95 ~FeatureList(); 96 97 // Initializes feature overrides via command-line flags |enable_features| and 98 // |disable_features|, each of which is a comma-separated list of features to 99 // enable or disable, respectively. If a feature appears on both lists, then 100 // it will be disabled. If a list entry has the format "FeatureName<TrialName" 101 // then this initialization will also associate the feature state override 102 // with the named field trial, if it exists. If a feature name is prefixed 103 // with the '*' character, it will be created with OVERRIDE_USE_DEFAULT - 104 // which is useful for associating with a trial while using the default state. 105 // Must only be invoked during the initialization phase (before 106 // FinalizeInitialization() has been called). 107 void InitializeFromCommandLine(const std::string& enable_features, 108 const std::string& disable_features); 109 110 // Initializes feature overrides through the field trial allocator, which 111 // we're using to store the feature names, their override state, and the name 112 // of the associated field trial. 113 void InitializeFromSharedMemory(PersistentMemoryAllocator* allocator); 114 115 // Specifies whether a feature override enables or disables the feature. 116 enum OverrideState { 117 OVERRIDE_USE_DEFAULT, 118 OVERRIDE_DISABLE_FEATURE, 119 OVERRIDE_ENABLE_FEATURE, 120 }; 121 122 // Returns true if the state of |feature_name| has been overridden via 123 // |InitializeFromCommandLine()|. 124 bool IsFeatureOverriddenFromCommandLine(const std::string& feature_name, 125 OverrideState state) const; 126 127 // Associates a field trial for reporting purposes corresponding to the 128 // command-line setting the feature state to |for_overridden_state|. The trial 129 // will be activated when the state of the feature is first queried. This 130 // should be called during registration, after InitializeFromCommandLine() has 131 // been called but before the instance is registered via SetInstance(). 132 void AssociateReportingFieldTrial(const std::string& feature_name, 133 OverrideState for_overridden_state, 134 FieldTrial* field_trial); 135 136 // Registers a field trial to override the enabled state of the specified 137 // feature to |override_state|. Command-line overrides still take precedence 138 // over field trials, so this will have no effect if the feature is being 139 // overridden from the command-line. The associated field trial will be 140 // activated when the feature state for this feature is queried. This should 141 // be called during registration, after InitializeFromCommandLine() has been 142 // called but before the instance is registered via SetInstance(). 143 void RegisterFieldTrialOverride(const std::string& feature_name, 144 OverrideState override_state, 145 FieldTrial* field_trial); 146 147 // Loops through feature overrides and serializes them all into |allocator|. 148 void AddFeaturesToAllocator(PersistentMemoryAllocator* allocator); 149 150 // Returns comma-separated lists of feature names (in the same format that is 151 // accepted by InitializeFromCommandLine()) corresponding to features that 152 // have been overridden - either through command-line or via FieldTrials. For 153 // those features that have an associated FieldTrial, the output entry will be 154 // of the format "FeatureName<TrialName", where "TrialName" is the name of the 155 // FieldTrial. Features that have overrides with OVERRIDE_USE_DEFAULT will be 156 // added to |enable_overrides| with a '*' character prefix. Must be called 157 // only after the instance has been initialized and registered. 158 void GetFeatureOverrides(std::string* enable_overrides, 159 std::string* disable_overrides); 160 161 // Like GetFeatureOverrides(), but only returns overrides that were specified 162 // explicitly on the command-line, omitting the ones from field trials. 163 void GetCommandLineFeatureOverrides(std::string* enable_overrides, 164 std::string* disable_overrides); 165 166 // Returns whether the given |feature| is enabled. Must only be called after 167 // the singleton instance has been registered via SetInstance(). Additionally, 168 // a feature with a given name must only have a single corresponding Feature 169 // struct, which is checked in builds with DCHECKs enabled. 170 static bool IsEnabled(const Feature& feature); 171 172 // Returns the field trial associated with the given |feature|. Must only be 173 // called after the singleton instance has been registered via SetInstance(). 174 static FieldTrial* GetFieldTrial(const Feature& feature); 175 176 // Splits a comma-separated string containing feature names into a vector. The 177 // resulting pieces point to parts of |input|. 178 static std::vector<base::StringPiece> SplitFeatureListString( 179 base::StringPiece input); 180 181 // Initializes and sets an instance of FeatureList with feature overrides via 182 // command-line flags |enable_features| and |disable_features| if one has not 183 // already been set from command-line flags. Returns true if an instance did 184 // not previously exist. See InitializeFromCommandLine() for more details 185 // about |enable_features| and |disable_features| parameters. 186 static bool InitializeInstance(const std::string& enable_features, 187 const std::string& disable_features); 188 189 // Returns the singleton instance of FeatureList. Will return null until an 190 // instance is registered via SetInstance(). 191 static FeatureList* GetInstance(); 192 193 // Registers the given |instance| to be the singleton feature list for this 194 // process. This should only be called once and |instance| must not be null. 195 // Note: If you are considering using this for the purposes of testing, take 196 // a look at using base/test/scoped_feature_list.h instead. 197 static void SetInstance(std::unique_ptr<FeatureList> instance); 198 199 // Clears the previously-registered singleton instance for tests and returns 200 // the old instance. 201 // Note: Most tests should never call this directly. Instead consider using 202 // base::test::ScopedFeatureList. 203 static std::unique_ptr<FeatureList> ClearInstanceForTesting(); 204 205 // Sets a given (initialized) |instance| to be the singleton feature list, 206 // for testing. Existing instance must be null. This is primarily intended 207 // to support base::test::ScopedFeatureList helper class. 208 static void RestoreInstanceForTesting(std::unique_ptr<FeatureList> instance); 209 210 private: 211 FRIEND_TEST_ALL_PREFIXES(FeatureListTest, CheckFeatureIdentity); 212 FRIEND_TEST_ALL_PREFIXES(FeatureListTest, 213 StoreAndRetrieveFeaturesFromSharedMemory); 214 FRIEND_TEST_ALL_PREFIXES(FeatureListTest, 215 StoreAndRetrieveAssociatedFeaturesFromSharedMemory); 216 217 struct OverrideEntry { 218 // The overridden enable (on/off) state of the feature. 219 const OverrideState overridden_state; 220 221 // An optional associated field trial, which will be activated when the 222 // state of the feature is queried for the first time. Weak pointer to the 223 // FieldTrial object that is owned by the FieldTrialList singleton. 224 base::FieldTrial* field_trial; 225 226 // Specifies whether the feature's state is overridden by |field_trial|. 227 // If it's not, and |field_trial| is not null, it means it is simply an 228 // associated field trial for reporting purposes (and |overridden_state| 229 // came from the command-line). 230 const bool overridden_by_field_trial; 231 232 // TODO(asvitkine): Expand this as more support is added. 233 234 // Constructs an OverrideEntry for the given |overridden_state|. If 235 // |field_trial| is not null, it implies that |overridden_state| comes from 236 // the trial, so |overridden_by_field_trial| will be set to true. 237 OverrideEntry(OverrideState overridden_state, FieldTrial* field_trial); 238 }; 239 240 // Finalizes the initialization state of the FeatureList, so that no further 241 // overrides can be registered. This is called by SetInstance() on the 242 // singleton feature list that is being registered. 243 void FinalizeInitialization(); 244 245 // Returns whether the given |feature| is enabled. This is invoked by the 246 // public FeatureList::IsEnabled() static function on the global singleton. 247 // Requires the FeatureList to have already been fully initialized. 248 bool IsFeatureEnabled(const Feature& feature); 249 250 // Returns the field trial associated with the given |feature|. This is 251 // invoked by the public FeatureList::GetFieldTrial() static function on the 252 // global singleton. Requires the FeatureList to have already been fully 253 // initialized. 254 base::FieldTrial* GetAssociatedFieldTrial(const Feature& feature); 255 256 // For each feature name in comma-separated list of strings |feature_list|, 257 // registers an override with the specified |overridden_state|. Also, will 258 // associate an optional named field trial if the entry is of the format 259 // "FeatureName<TrialName". 260 void RegisterOverridesFromCommandLine(const std::string& feature_list, 261 OverrideState overridden_state); 262 263 // Registers an override for feature |feature_name|. The override specifies 264 // whether the feature should be on or off (via |overridden_state|), which 265 // will take precedence over the feature's default state. If |field_trial| is 266 // not null, registers the specified field trial object to be associated with 267 // the feature, which will activate the field trial when the feature state is 268 // queried. If an override is already registered for the given feature, it 269 // will not be changed. 270 void RegisterOverride(StringPiece feature_name, 271 OverrideState overridden_state, 272 FieldTrial* field_trial); 273 274 // Implementation of GetFeatureOverrides() with a parameter that specifies 275 // whether only command-line enabled overrides should be emitted. See that 276 // function's comments for more details. 277 void GetFeatureOverridesImpl(std::string* enable_overrides, 278 std::string* disable_overrides, 279 bool command_line_only); 280 281 // Verifies that there's only a single definition of a Feature struct for a 282 // given feature name. Keeps track of the first seen Feature struct for each 283 // feature. Returns false when called on a Feature struct with a different 284 // address than the first one it saw for that feature name. Used only from 285 // DCHECKs and tests. 286 bool CheckFeatureIdentity(const Feature& feature); 287 288 // Map from feature name to an OverrideEntry struct for the feature, if it 289 // exists. 290 std::map<std::string, OverrideEntry> overrides_; 291 292 // Locked map that keeps track of seen features, to ensure a single feature is 293 // only defined once. This verification is only done in builds with DCHECKs 294 // enabled. 295 Lock feature_identity_tracker_lock_; 296 std::map<std::string, const Feature*> feature_identity_tracker_; 297 298 // Whether this object has been fully initialized. This gets set to true as a 299 // result of FinalizeInitialization(). 300 bool initialized_ = false; 301 302 // Whether this object has been initialized from command line. 303 bool initialized_from_command_line_ = false; 304 305 DISALLOW_COPY_AND_ASSIGN(FeatureList); 306 }; 307 308 } // namespace base 309 310 #endif // BASE_FEATURE_LIST_H_ 311