base/scoped_observation.h

   1 // Copyright 2020 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_SCOPED_OBSERVATION_H_
   6 #define BASE_SCOPED_OBSERVATION_H_
   7
   8 #include <stddef.h>
   9
  10 #include "base/check_op.h"
  11
  12 namespace base {
  13
  14 // ScopedObservation is used to keep track of singular observation, e.g.
  15 // where an observer observes a single source only.
  16 //
  17 // Use base::ScopedMultiSourceObservation for objects that observe multiple
  18 // sources.
  19 //
  20 // When ScopedObservation is destroyed, it removes the registered observation,
  21 // if any. Basic example (as a member variable):
  22 //
  23 //   class MyFooObserver : public FooObserver {
  24 //     ...
  25 //    private:
  26 //     ScopedObservation<Foo, FooObserver> foo_observation_{this};
  27 //   };
  28 //
  29 //   MyFooObserver::MyFooObserver(Foo* foo) {
  30 //     foo_observation_.Observe(foo);
  31 //   }
  32 //
  33 // For cases with methods not named AddObserver/RemoveObserver:
  34 //
  35 //   class MyFooStateObserver : public FooStateObserver {
  36 //     ...
  37 //    private:
  38 //     ScopedObservation<Foo,
  39 //                       FooStateObserver,
  40 //                       &Foo::AddStateObserver,
  41 //                       &Foo::RemoveStateObserver>
  42 //       foo_observation_{this};
  43 //   };
  44 template <class Source,
  45           class Observer,
  46           void (Source::*AddObsFn)(Observer*) = &Source::AddObserver,
  47           void (Source::*RemoveObsFn)(Observer*) = &Source::RemoveObserver>
  48 class ScopedObservation {
  49  public:
  50   explicit ScopedObservation(Observer* observer) : observer_(observer) {}
  51   ScopedObservation(const ScopedObservation&) = delete;
  52   ScopedObservation& operator=(const ScopedObservation&) = delete;
  53   ~ScopedObservation() { Reset(); }
  54
  55   // Adds the object passed to the constructor as an observer on |source|.
  56   // IsObserving() must be false.
  57   void Observe(Source* source) {
  58     // TODO(https://crbug.com/1145565): Make this a DCHECK once ScopedObserver
  59     //     has been fully retired.
  60     CHECK_EQ(source_, nullptr);
  61     source_ = source;
  62     (source_->*AddObsFn)(observer_);
  63   }
  64
  65   // Remove the object passed to the constructor as an observer from |source_|
  66   // if currently observing. Does nothing otherwise.
  67   void Reset() {
  68     if (source_) {
  69       (source_->*RemoveObsFn)(observer_);
  70       source_ = nullptr;
  71     }
  72   }
  73
  74   // Returns true if any source is being observed.
  75   bool IsObserving() const { return source_ != nullptr; }
  76
  77   // Returns true if |source| is being observed.
  78   bool IsObservingSource(Source* source) const {
  79     DCHECK(source);
  80     return source_ == source;
  81   }
  82
  83  private:
  84   Observer* const observer_;
  85
  86   // The observed source, if any.
  87   Source* source_ = nullptr;
  88 };
  89
  90 }  // namespace base
  91
  92 #endif  // BASE_SCOPED_OBSERVATION_H_