1
    2
    3
    4
    5
    6
    7
    8
    9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
  100
  101
  102
  103
  104
  105
  106
  107
  108
  109
  110
  111
  112
  113
  114
  115
  116
  117
  118
  119
  120
  121
  122
  123
  124
  125
  126
  127
  128
  129
  130
  131
  132
  133
  134
  135
  136
  137
  138
  139
  140
  141
  142
  143
  144
  145
  146
  147
  148


base / scoped_observation.h [blame]

// Copyright 2020 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef BASE_SCOPED_OBSERVATION_H_
#define BASE_SCOPED_OBSERVATION_H_

#include <utility>

#include "base/check.h"
#include "base/check_op.h"
#include "base/memory/raw_ptr.h"
#include "base/scoped_observation_traits.h"

namespace base {

// `ScopedObservation` is used to keep track of a singular observation, i.e.,
// where an observer observes a single source only. Use
// `base::ScopedMultiSourceObservation` for objects that observe multiple
// sources.
//
// When a `ScopedObservation` is destroyed, it unregisters the observer from the
// observable if it was currently observing something. Otherwise it does
// nothing.
//
// Using a `ScopedObservation` instead of manually observing and unobserving has
// the following benefits:
// - The observer cannot accidentally forget to stop observing when it is
//   destroyed.
// - By calling `Reset`, an ongoing observation can be stopped before the
//   `ScopedObservation` is destroyed. If nothing was currently observed, then
//   calling `Reset` does nothing. This can be useful for when the observable is
//   destroyed before the observer is destroyed, because it prevents the
//   observer from accidentally unregistering itself from the destroyed
//   observable a second time when it itself is destroyed. Without
//   `ScopedObservation`, one might need to keep track of whether one has
//   already stopped observing in a separate boolean.
//
// A complete usage example can be found below.
//
// `observer.h`:
//   class Observer {
//    public:
//     virtual ~Observer() = default;
//
//     virtual void OnEvent() {}
//   };
//
// `source.h`:
//   class Observer;
//   class Source {
//    public:
//     void AddObserver(Observer* observer);
//     void RemoveObserver(Observer* observer);
//   };
//
// `observer_impl.h`:
//   #include "observer.h"
//
//   class Source;
//
//   class ObserverImpl: public Observer {
//    public:
//     ObserverImpl(Source* source);
//     // Note how there is no need to stop observing in the destructor.
//     ~ObserverImpl() override {}
//
//     void OnEvent() override {
//       ...
//     }
//
//    private:
//     // Note that |obs_| can be instantiated with forward-declared Source.
//     base::ScopedObservation<Source, Observer> obs_{this};
//   };
//
// `observer_impl.cc`:
//   #include "observer_impl.h"
//   #include "source.h"
//
//   ObserverImpl::ObserverImpl(Source* source) {
//     // After the call |this| starts listening to events from |source|.
//     obs_.Observe(source);
//   }
//
////////////////////////////////////////////////////////////////////////////////
//
// By default `ScopedObservation` only works with sources that expose
// `AddObserver` and `RemoveObserver`. However, it's also possible to
// adapt it to custom function names (say `AddFoo` and `RemoveFoo` accordingly)
// by tailoring ScopedObservationTraits<> for the given Source and Observer --
// see `base/scoped_observation_traits.h` for details.
//

template <class Source, class Observer>
class ScopedObservation {
 public:
  explicit ScopedObservation(Observer* observer) : observer_(observer) {}
  ScopedObservation(const ScopedObservation&) = delete;
  ScopedObservation& operator=(const ScopedObservation&) = delete;
  ~ScopedObservation() { Reset(); }

  // Adds the object passed to the constructor as an observer on |source|.
  // IsObserving() must be false.
  void Observe(Source* source) {
    DCHECK_EQ(source_, nullptr);
    source_ = source;
    Traits::AddObserver(source_, observer_);
  }

  // Remove the object passed to the constructor as an observer from |source_|
  // if currently observing. Does nothing otherwise.
  void Reset() {
    if (source_) {
      Traits::RemoveObserver(std::exchange(source_, nullptr), observer_);
    }
  }

  // Returns true if any source is being observed.
  bool IsObserving() const { return source_ != nullptr; }

  // Returns true if |source| is being observed.
  bool IsObservingSource(Source* source) const {
    DCHECK(source);
    return source_ == source;
  }

  // Gets a pointer to the observer that observes the source.
  Observer* GetObserver() { return observer_; }
  const Observer* GetObserver() const { return observer_; }

  // Gets a pointer to the observed source, or nullptr if no source is being
  // observed.
  Source* GetSource() { return source_; }
  const Source* GetSource() const { return source_; }

 private:
  using Traits = ScopedObservationTraits<Source, Observer>;

  const raw_ptr<Observer> observer_;

  // The observed source, if any.
  raw_ptr<Source, LeakedDanglingUntriaged> source_ = nullptr;
};

}  // namespace base

#endif  // BASE_SCOPED_OBSERVATION_H_