35 // Specifies whether a given feature is enabled or disabled by default.
45 // - `kFeature` is the C++ identifier that will be used for the `base::Feature`.
46 // - `name` is the feature name, which must be globally unique. This name is
49 // - `default_state` is the default state to use for the feature, i.e.
58 // If the feature needs to be marked as exported, i.e. it is referenced by
63   extern CONSTINIT const base::Feature kFeature
71 #define BASE_FEATURE(feature, name, default_state) \  argument
72   CONSTINIT const base::Feature feature(name, default_state)
74 // The Feature struct is used to define the default state for a feature. There
75 // must only ever be one struct instance for a given feature name—generally
80 // Feature constants are internally mutable, as this allows them to contain a
95 struct BASE_EXPORT LOGICALLY_CONST Feature {  struct
96   constexpr Feature(const char* name, FeatureState default_state)  in Feature()  function
100       LOG(FATAL) << "Invalid feature name " << name << " starts with "  in Feature()
107   // - there should be only one `Feature` instance per unique name.
108   // - a `Feature` contains internal cached state about the override state.
109   Feature(const Feature&) = delete;
110   Feature& operator=(const Feature&) = delete;  argument
112   // The name of the feature. This should be unique to each feature and is used
114   // It is strongly recommended to use CamelCase style for feature names, e.g.
118   // The default state (i.e. enabled or disabled) for this feature.
127   // feature, and the last 16 bits are a caching context ID used to allow
141   // feature list and the cache is updated.
147 // not, via a DcheckIsFatal feature. We define the Feature here since it is  argument
152 // The FeatureList class is used to determine whether a given feature is on or
156 // The basic use case is for any feature that can be toggled (e.g. through
157 // command-line or an experiment) to have a defined Feature struct, e.g.:
159 //   const base::Feature kMyGreatFeature {
163 // Then, client code that wishes to query the state of the feature would check:
166 //     // Feature code goes here.
170 // flags to enable or disable the feature, any experiments that may control it
172 // whether the feature is on.
175 // separated feature names via the following command-line flags:
213   // Specifies whether a feature override enables or disables the feature.
220   // Accessor class, used to look up features by _name_ rather than by Feature
228     // Looks up the feature, returning only its override state, rather than
235     // Look up the feature, and, if present, populate |params|.
246     // Unowned pointer to the FeatureList object we use to look up feature
251   // Describes a feature override. The first member is a Feature that will be
254       std::pair<const std::reference_wrapper<const Feature>, OverrideState>;
256   // Initializes feature overrides via command-line flags `--enable-features=`
259   // users to set a feature's field trial params via `--enable-features=`. Must
263   // If a feature appears on both lists, then it will be disabled. If
265   // initialization will also associate the feature state override with the
269   // also associate the feature state override with the named field trial and
270   // its params. If the feature params part is provided but trial and/or group
272   // "Study" followed by the feature name, i.e. "StudyFeature", and group, named
273   // "Group" followed by the feature name, i.e. "GroupFeature", for the params.
274   // If a feature name is prefixed with the '*' character, it will be created
280   // Initializes feature overrides through the field trial allocator, which
281   // we're using to store the feature names, their override state, and the name
293   // any extra feature overrides that depend on command line switches.
303   // command-line setting the feature state to |for_overridden_state|. The trial
304   // will be activated when the state of the feature is first queried. This
312   // feature to |override_state|. Command-line overrides still take precedence
313   // over field trials, so this will have no effect if the feature is being
315   // activated when the feature state for this feature is queried. This should
331   // Loops through feature overrides and serializes them all into |allocator|.
334   // Returns comma-separated lists of feature names (in the same format that is
354   // Returns the field trial associated with the given feature |name|. Used for
355   // getting the FieldTrial without requiring a struct Feature.
363   // Returns whether the given feature |name| is associated with a field trial.
364   // If the given feature |name| does not exist, return false. Unlike
370   // Get associated field trial for the given feature |name| only if override
381   // Returns whether the given `feature` is enabled.
394   // A feature with a given name must only have a single corresponding Feature
396   static bool IsEnabled(const Feature& feature);
398   // Some characters are not allowed to appear in feature names or the
406   // If the given |feature| is overridden, returns its enabled state; otherwise,
408   // has been registered via SetInstance(). Additionally, a feature with a given
409   // name must only have a single corresponding Feature struct, which is checked
411   static absl::optional<bool> GetStateIfOverridden(const Feature& feature);
413   // Returns the field trial associated with the given |feature|. Must only be
415   static FieldTrial* GetFieldTrial(const Feature& feature);
417   // Splits a comma-separated string containing feature names into a vector. The
425   // |feature_name| to be the feature's name, |study_name| and |group_name| to
435   // Initializes and sets an instance of FeatureList with feature overrides via
443   // Like the above, but also adds extra overrides. If a feature appears in
455   // Registers the given |instance| to be the singleton feature list for this
467   // Sets a given (initialized) |instance| to be the singleton feature list,
472   // After calling this, an attempt to access feature state when no FeatureList
495     // The overridden enable (on/off) state of the feature.
499     // state of the feature is queried for the first time. Weak pointer to the
503     // Specifies whether the feature's state is overridden by |field_trial|.
517   // Returns the override for the field trial associated with the given feature
518   // |name| or null if the feature is not found.
524   // singleton feature list that is being registered.
527   // Returns whether the given |feature| is enabled. This is invoked by the
530   bool IsFeatureEnabled(const Feature& feature) const;
532   // Returns whether the given |feature| is enabled. This is invoked by the
536       const Feature& feature) const;
538   // Returns the override state of a given |feature|. If the feature was not
540   // for when the feature state has been observed, e.g. activating field trials.
541   OverrideState GetOverrideState(const Feature& feature) const;
546   // Returns the field trial associated with the given |feature|. This is
550   base::FieldTrial* GetAssociatedFieldTrial(const Feature& feature) const;
552   // For each feature name in comma-separated list of strings |feature_list|,
559   // Registers an override for feature |feature_name|. The override specifies
560   // whether the feature should be on or off (via |overridden_state|), which
561   // will take precedence over the feature's default state. If |field_trial| is
563   // the feature, which will activate the field trial when the feature state is
564   // queried. If an override is already registered for the given feature, it
578   // Verifies that there's only a single definition of a Feature struct for a
579   // given feature name. Keeps track of the first seen Feature struct for each
580   // feature. Returns false when called on a Feature struct with a different
581   // address than the first one it saw for that feature name. Used only from
584   bool CheckFeatureIdentity(const Feature& feature) const;
586   // Map from feature name to an OverrideEntry struct for the feature, if it
590   // Locked map that keeps track of seen features, to ensure a single feature is
595   mutable std::map<std::string, const Feature*> feature_identity_tracker_
611   // Used when querying `base::Feature` state to determine if the cached value
612   // in the `Feature` object is populated and valid. See the comment on
613   // `base::Feature::cached_value` for more details.