src/base/prefs/pref_member.h

   1 // Copyright (c) 2012 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 // A helper class that stays in sync with a preference (bool, int, real,
   6 // string or filepath).  For example:
   7 //
   8 // class MyClass {
   9 //  public:
  10 //   MyClass(PrefService* prefs) {
  11 //     my_string_.Init(prefs::kHomePage, prefs);
  12 //   }
  13 //  private:
  14 //   StringPrefMember my_string_;
  15 // };
  16 //
  17 // my_string_ should stay in sync with the prefs::kHomePage pref and will
  18 // update if either the pref changes or if my_string_.SetValue is called.
  19 //
  20 // An optional observer can be passed into the Init method which can be used to
  21 // notify MyClass of changes. Note that if you use SetValue(), the observer
  22 // will not be notified.
  23
  24 #ifndef BASE_PREFS_PREF_MEMBER_H_
  25 #define BASE_PREFS_PREF_MEMBER_H_
  26
  27 #include <string>
  28 #include <vector>
  29
  30 #include "base/basictypes.h"
  31 #include "base/bind.h"
  32 #include "base/callback_forward.h"
  33 #include "base/files/file_path.h"
  34 #include "base/logging.h"
  35 #include "base/memory/ref_counted.h"
  36 #include "base/prefs/base_prefs_export.h"
  37 #include "base/prefs/pref_observer.h"
  38 #include "base/single_thread_task_runner.h"
  39 #include "base/values.h"
  40
  41 class PrefService;
  42
  43 namespace subtle {
  44
  45 class BASE_PREFS_EXPORT PrefMemberBase : public PrefObserver {
  46  public:
  47   // Type of callback you can register if you need to know the name of
  48   // the pref that is changing.
  49   typedef base::Callback<void(const std::string&)> NamedChangeCallback;
  50
  51   PrefService* prefs() { return prefs_; }
  52   const PrefService* prefs() const { return prefs_; }
  53
  54  protected:
  55   class BASE_PREFS_EXPORT Internal
  56       : public base::RefCountedThreadSafe<Internal> {
  57    public:
  58     Internal();
  59
  60     // Update the value, either by calling |UpdateValueInternal| directly
  61     // or by dispatching to the right thread.
  62     // Takes ownership of |value|.
  63     void UpdateValue(base::Value* value,
  64                      bool is_managed,
  65                      bool is_user_modifiable,
  66                      const base::Closure& callback) const;
  67
  68     void MoveToThread(
  69         const scoped_refptr<base::SingleThreadTaskRunner>& task_runner);
  70
  71     // See PrefMember<> for description.
  72     bool IsManaged() const {
  73       return is_managed_;
  74     }
  75
  76     bool IsUserModifiable() const {
  77       return is_user_modifiable_;
  78     }
  79
  80    protected:
  81     friend class base::RefCountedThreadSafe<Internal>;
  82     virtual ~Internal();
  83
  84     void CheckOnCorrectThread() const {
  85       DCHECK(IsOnCorrectThread());
  86     }
  87
  88    private:
  89     // This method actually updates the value. It should only be called from
  90     // the thread the PrefMember is on.
  91     virtual bool UpdateValueInternal(const base::Value& value) const = 0;
  92
  93     bool IsOnCorrectThread() const;
  94
  95     scoped_refptr<base::SingleThreadTaskRunner> thread_loop_;
  96     mutable bool is_managed_;
  97     mutable bool is_user_modifiable_;
  98
  99     DISALLOW_COPY_AND_ASSIGN(Internal);
 100   };
 101
 102   PrefMemberBase();
 103   virtual ~PrefMemberBase();
 104
 105   // See PrefMember<> for description.
 106   void Init(const char* pref_name, PrefService* prefs,
 107             const NamedChangeCallback& observer);
 108   void Init(const char* pref_name, PrefService* prefs);
 109
 110   virtual void CreateInternal() const = 0;
 111
 112   // See PrefMember<> for description.
 113   void Destroy();
 114
 115   void MoveToThread(
 116       const scoped_refptr<base::SingleThreadTaskRunner>& task_runner);
 117
 118   // PrefObserver
 119   void OnPreferenceChanged(PrefService* service,
 120                            const std::string& pref_name) override;
 121
 122   void VerifyValuePrefName() const {
 123     DCHECK(!pref_name_.empty());
 124   }
 125
 126   // This method is used to do the actual sync with the preference.
 127   // Note: it is logically const, because it doesn't modify the state
 128   // seen by the outside world. It is just doing a lazy load behind the scenes.
 129   void UpdateValueFromPref(const base::Closure& callback) const;
 130
 131   // Verifies the preference name, and lazily loads the preference value if
 132   // it hasn't been loaded yet.
 133   void VerifyPref() const;
 134
 135   const std::string& pref_name() const { return pref_name_; }
 136
 137   virtual Internal* internal() const = 0;
 138
 139   // Used to allow registering plain base::Closure callbacks.
 140   static void InvokeUnnamedCallback(const base::Closure& callback,
 141                                     const std::string& pref_name);
 142
 143  private:
 144   // Ordered the members to compact the class instance.
 145   std::string pref_name_;
 146   NamedChangeCallback observer_;
 147   PrefService* prefs_;
 148
 149  protected:
 150   bool setting_value_;
 151 };
 152
 153 // This function implements StringListPrefMember::UpdateValue().
 154 // It is exposed here for testing purposes.
 155 bool BASE_PREFS_EXPORT PrefMemberVectorStringUpdate(
 156     const base::Value& value,
 157     std::vector<std::string>* string_vector);
 158
 159 }  // namespace subtle
 160
 161 template <typename ValueType>
 162 class PrefMember : public subtle::PrefMemberBase {
 163  public:
 164   // Defer initialization to an Init method so it's easy to make this class be
 165   // a member variable.
 166   PrefMember() {}
 167   virtual ~PrefMember() {}
 168
 169   // Do the actual initialization of the class.  Use the two-parameter
 170   // version if you don't want any notifications of changes.  This
 171   // method should only be called on the UI thread.
 172   void Init(const char* pref_name, PrefService* prefs,
 173             const NamedChangeCallback& observer) {
 174     subtle::PrefMemberBase::Init(pref_name, prefs, observer);
 175   }
 176   void Init(const char* pref_name, PrefService* prefs,
 177             const base::Closure& observer) {
 178     subtle::PrefMemberBase::Init(
 179         pref_name, prefs,
 180         base::Bind(&PrefMemberBase::InvokeUnnamedCallback, observer));
 181   }
 182   void Init(const char* pref_name, PrefService* prefs) {
 183     subtle::PrefMemberBase::Init(pref_name, prefs);
 184   }
 185
 186   // Unsubscribes the PrefMember from the PrefService. After calling this
 187   // function, the PrefMember may not be used any more on the UI thread.
 188   // Assuming |MoveToThread| was previously called, |GetValue|, |IsManaged|,
 189   // and |IsUserModifiable| can still be called from the other thread but
 190   // the results will no longer update from the PrefService.
 191   // This method should only be called on the UI thread.
 192   void Destroy() {
 193     subtle::PrefMemberBase::Destroy();
 194   }
 195
 196   // Moves the PrefMember to another thread, allowing read accesses from there.
 197   // Changes from the PrefService will be propagated asynchronously
 198   // via PostTask.
 199   // This method should only be used from the thread the PrefMember is currently
 200   // on, which is the UI thread by default.
 201   void MoveToThread(
 202       const scoped_refptr<base::SingleThreadTaskRunner>& task_runner) {
 203     subtle::PrefMemberBase::MoveToThread(task_runner);
 204   }
 205
 206   // Check whether the pref is managed, i.e. controlled externally through
 207   // enterprise configuration management (e.g. windows group policy). Returns
 208   // false for unknown prefs.
 209   // This method should only be used from the thread the PrefMember is currently
 210   // on, which is the UI thread unless changed by |MoveToThread|.
 211   bool IsManaged() const {
 212     VerifyPref();
 213     return internal_->IsManaged();
 214   }
 215
 216   // Checks whether the pref can be modified by the user. This returns false
 217   // when the pref is managed by a policy or an extension, and when a command
 218   // line flag overrides the pref.
 219   // This method should only be used from the thread the PrefMember is currently
 220   // on, which is the UI thread unless changed by |MoveToThread|.
 221   bool IsUserModifiable() const {
 222     VerifyPref();
 223     return internal_->IsUserModifiable();
 224   }
 225
 226   // Retrieve the value of the member variable.
 227   // This method should only be used from the thread the PrefMember is currently
 228   // on, which is the UI thread unless changed by |MoveToThread|.
 229   ValueType GetValue() const {
 230     VerifyPref();
 231     return internal_->value();
 232   }
 233
 234   // Provided as a convenience.
 235   ValueType operator*() const {
 236     return GetValue();
 237   }
 238
 239   // Set the value of the member variable.
 240   // This method should only be called on the UI thread.
 241   void SetValue(const ValueType& value) {
 242     VerifyValuePrefName();
 243     setting_value_ = true;
 244     UpdatePref(value);
 245     setting_value_ = false;
 246   }
 247
 248   // Returns the pref name.
 249   const std::string& GetPrefName() const {
 250     return pref_name();
 251   }
 252
 253  private:
 254   class Internal : public subtle::PrefMemberBase::Internal {
 255    public:
 256     Internal() : value_(ValueType()) {}
 257
 258     ValueType value() {
 259       CheckOnCorrectThread();
 260       return value_;
 261     }
 262
 263    protected:
 264     virtual ~Internal() {}
 265
 266     virtual BASE_PREFS_EXPORT bool UpdateValueInternal(
 267         const base::Value& value) const override;
 268
 269     // We cache the value of the pref so we don't have to keep walking the pref
 270     // tree.
 271     mutable ValueType value_;
 272
 273     DISALLOW_COPY_AND_ASSIGN(Internal);
 274   };
 275
 276   virtual Internal* internal() const override { return internal_.get(); }
 277   virtual void CreateInternal() const override { internal_ = new Internal(); }
 278
 279   // This method is used to do the actual sync with pref of the specified type.
 280   void BASE_PREFS_EXPORT UpdatePref(const ValueType& value);
 281
 282   mutable scoped_refptr<Internal> internal_;
 283
 284   DISALLOW_COPY_AND_ASSIGN(PrefMember);
 285 };
 286
 287 // Declaration of template specialization need to be repeated here
 288 // specifically for each specialization (rather than just once above)
 289 // or at least one of our compilers won't be happy in all cases.
 290 // Specifically, it was failing on ChromeOS with a complaint about
 291 // PrefMember<FilePath>::UpdateValueInternal not being defined when
 292 // built in a chroot with the following parameters:
 293 //
 294 // FEATURES="noclean nostrip" USE="-chrome_debug -chrome_remoting
 295 // -chrome_internal -chrome_pdf component_build"
 296 // ~/trunk/goma/goma-wrapper cros_chrome_make --board=${BOARD}
 297 // --install --runhooks
 298
 299 template <>
 300 BASE_PREFS_EXPORT void PrefMember<bool>::UpdatePref(const bool& value);
 301
 302 template <>
 303 BASE_PREFS_EXPORT bool PrefMember<bool>::Internal::UpdateValueInternal(
 304     const base::Value& value) const;
 305
 306 template <>
 307 BASE_PREFS_EXPORT void PrefMember<int>::UpdatePref(const int& value);
 308
 309 template <>
 310 BASE_PREFS_EXPORT bool PrefMember<int>::Internal::UpdateValueInternal(
 311     const base::Value& value) const;
 312
 313 template <>
 314 BASE_PREFS_EXPORT void PrefMember<double>::UpdatePref(const double& value);
 315
 316 template <>
 317 BASE_PREFS_EXPORT bool PrefMember<double>::Internal::UpdateValueInternal(
 318     const base::Value& value) const;
 319
 320 template <>
 321 BASE_PREFS_EXPORT void PrefMember<std::string>::UpdatePref(
 322     const std::string& value);
 323
 324 template <>
 325 BASE_PREFS_EXPORT bool PrefMember<std::string>::Internal::UpdateValueInternal(
 326     const base::Value& value) const;
 327
 328 template <>
 329 BASE_PREFS_EXPORT void PrefMember<base::FilePath>::UpdatePref(
 330     const base::FilePath& value);
 331
 332 template <>
 333 BASE_PREFS_EXPORT bool
 334 PrefMember<base::FilePath>::Internal::UpdateValueInternal(
 335     const base::Value& value) const;
 336
 337 template <>
 338 BASE_PREFS_EXPORT void PrefMember<std::vector<std::string> >::UpdatePref(
 339     const std::vector<std::string>& value);
 340
 341 template <>
 342 BASE_PREFS_EXPORT bool
 343 PrefMember<std::vector<std::string> >::Internal::UpdateValueInternal(
 344     const base::Value& value) const;
 345
 346 typedef PrefMember<bool> BooleanPrefMember;
 347 typedef PrefMember<int> IntegerPrefMember;
 348 typedef PrefMember<double> DoublePrefMember;
 349 typedef PrefMember<std::string> StringPrefMember;
 350 typedef PrefMember<base::FilePath> FilePathPrefMember;
 351 // This preference member is expensive for large string arrays.
 352 typedef PrefMember<std::vector<std::string> > StringListPrefMember;
 353
 354 #endif  // BASE_PREFS_PREF_MEMBER_H_