Add base::ScopedObservation.

This class is for observers that observe only one source.
This is more readable and slightly more efficient than using
base::ScopedObserver, where an observer has zero or one subscriptions.

Change-Id: Iefd987ce006aa2106249cf2708f63d90326814ea
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2518028Reviewed-by: François Doray <fdoray@chromium.org>
Reviewed-by: Patrick Monette <pmonette@chromium.org>
Commit-Queue: François Doray <fdoray@chromium.org>
Commit-Queue: Sigurður Ásgeirsson <siggi@chromium.org>
Cr-Commit-Position: refs/heads/master@{#824014}

base/BUILD.gn

@@ -497,6 +497,7 @@ component("base") {
     "scoped_generic.h",
     "scoped_native_library.cc",
     "scoped_native_library.h",
+    "scoped_observation.h",
     "scoped_observer.h",
     "sequence_checker.h",
     "sequence_checker_impl.cc",
@@ -2863,6 +2864,7 @@ test("base_unittests") {
     "scoped_clear_last_error_unittest.cc",
     "scoped_generic_unittest.cc",
     "scoped_native_library_unittest.cc",
+    "scoped_observation_unittest.cc",
     "security_unittest.cc",
     "sequence_checker_unittest.cc",
     "sequence_token_unittest.cc",

base/scoped_observation.h

+// Copyright 2020 The Chromium Authors. All rights reserved.
+// 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 <stddef.h>
+
+#include "base/check_op.h"
+
+// ScopedObservation is used to keep track of a single observation.
+// When ScopedObservation is destroyed, it removes the registered observation,
+// if any. Basic example (as a member variable):
+//
+//   class MyFooObserver : public FooObserver {
+//     ...
+//    private:
+//     ScopedObservation<Foo, FooObserver> foo_observation_{this};
+//   };
+//
+// For cases with methods not named AddObserver/RemoveObserver:
+//
+//   class MyFooStateObserver : public FooStateObserver {
+//     ...
+//    private:
+//     ScopedObservation<Foo,
+//                    FooStateObserver,
+//                    &Foo::AddStateObserver,
+//                    &Foo::RemoveStateObserver>
+//       observed_foo_{this};
+//   };
+//
+// See also base::ScopedObserver to manage observations from multiple sources.
+template <class Source,
+          class Observer,
+          void (Source::*AddObsFn)(Observer*) = &Source::AddObserver,
+          void (Source::*RemoveObsFn)(Observer*) = &Source::RemoveObserver>
+class ScopedObservation {
+ public:
+  explicit ScopedObservation(Observer* observer) : observer_(observer) {}
+  ScopedObservation(const ScopedObservation&) = delete;
+  ScopedObservation& operator=(const ScopedObservation&) = delete;
+  ~ScopedObservation() {
+    if (IsObserving())
+      RemoveObservation();
+  }
+
+  // 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;
+    (source_->*AddObsFn)(observer_);
+  }
+
+  // Remove the object passed to the constructor as an observer from |source|.
+  void RemoveObservation() {
+    DCHECK_NE(source_, nullptr);
+    (source_->*RemoveObsFn)(observer_);
+    source_ = nullptr;
+  }
+
+  // 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 { return source_ == source; }
+
+ private:
+  Observer* const observer_;
+
+  // The observed source, if any.
+  Source* source_ = nullptr;
+};
+
+#endif  // BASE_SCOPED_OBSERVATION_H_

base/scoped_observation_unittest.cc

+// Copyright 2020 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#include "base/scoped_observation.h"
+
+#include "base/ranges/algorithm.h"
+#include "base/stl_util.h"
+#include "base/test/gtest_util.h"
+#include "testing/gtest/include/gtest/gtest.h"
+
+namespace base {
+namespace {
+
+class TestSourceObserver {};
+
+class TestSource {
+ public:
+  void AddObserver(TestSourceObserver* observer);
+  void RemoveObserver(TestSourceObserver* observer);
+
+  bool HasObserver(TestSourceObserver* observer) const;
+  size_t num_observers() const { return observers_.size(); }
+
+ private:
+  std::vector<TestSourceObserver*> observers_;
+};
+
+void TestSource::AddObserver(TestSourceObserver* observer) {
+  observers_.push_back(observer);
+}
+
+void TestSource::RemoveObserver(TestSourceObserver* observer) {
+  auto it = base::ranges::find(observers_, observer);
+  EXPECT_TRUE(it != observers_.end());
+  observers_.erase(it);
+}
+
+bool TestSource::HasObserver(TestSourceObserver* observer) const {
+  return base::Contains(observers_, observer);
+}
+
+using TestScopedObservation = ScopedObservation<TestSource, TestSourceObserver>;
+
+}  // namespace
+
+TEST(ScopedObservationTest, RemovesObservationOnDestruction) {
+  TestSource s1;
+
+  {
+    TestSourceObserver o1;
+    TestScopedObservation obs(&o1);
+    EXPECT_EQ(0u, s1.num_observers());
+    EXPECT_FALSE(s1.HasObserver(&o1));
+
+    obs.Observe(&s1);
+    EXPECT_EQ(1u, s1.num_observers());
+    EXPECT_TRUE(s1.HasObserver(&o1));
+  }
+
+  // Test that the observation is removed when it goes out of scope.
+  EXPECT_EQ(0u, s1.num_observers());
+}
+
+TEST(ScopedObservationTest, RemoveObservation) {
+  TestSource s1;
+  TestSourceObserver o1;
+  TestScopedObservation obs(&o1);
+  EXPECT_EQ(0u, s1.num_observers());
+  EXPECT_FALSE(s1.HasObserver(&o1));
+
+  obs.Observe(&s1);
+  EXPECT_EQ(1u, s1.num_observers());
+  EXPECT_TRUE(s1.HasObserver(&o1));
+
+  obs.RemoveObservation();
+  EXPECT_EQ(0u, s1.num_observers());
+}
+
+TEST(ScopedObservationTest, IsObserving) {
+  TestSource s1;
+  TestSourceObserver o1;
+  TestScopedObservation obs(&o1);
+  EXPECT_FALSE(obs.IsObserving());
+
+  obs.Observe(&s1);
+  EXPECT_TRUE(obs.IsObserving());
+
+  obs.RemoveObservation();
+  EXPECT_FALSE(obs.IsObserving());
+}
+
+TEST(ScopedObservationTest, IsObservingSource) {
+  TestSource s1;
+  TestSource s2;
+  TestSourceObserver o1;
+  TestScopedObservation obs(&o1);
+  EXPECT_FALSE(obs.IsObservingSource(&s1));
+  EXPECT_FALSE(obs.IsObservingSource(&s2));
+
+  obs.Observe(&s1);
+  EXPECT_TRUE(obs.IsObservingSource(&s1));
+  EXPECT_FALSE(obs.IsObservingSource(&s2));
+
+  obs.RemoveObservation();
+  EXPECT_FALSE(obs.IsObservingSource(&s1));
+  EXPECT_FALSE(obs.IsObservingSource(&s2));
+}
+
+namespace {
+
+// A test source with oddly named Add/Remove functions.
+class TestSourceWithNonDefaultNames {
+ public:
+  void AddFoo(TestSourceObserver* observer) { impl_.AddObserver(observer); }
+  void RemoveFoo(TestSourceObserver* observer) {
+    impl_.RemoveObserver(observer);
+  }
+
+  const TestSource& impl() const { return impl_; }
+
+ private:
+  TestSource impl_;
+};
+
+using TestScopedObservationWithNonDefaultNames =
+    ScopedObservation<TestSourceWithNonDefaultNames,
+                      TestSourceObserver,
+                      &TestSourceWithNonDefaultNames::AddFoo,
+                      &TestSourceWithNonDefaultNames::RemoveFoo>;
+
+}  // namespace
+
+TEST(ScopedObservationTest, NonDefaultNames) {
+  TestSourceWithNonDefaultNames s1;
+  TestSourceObserver o1;
+
+  EXPECT_EQ(0u, s1.impl().num_observers());
+  {
+    TestScopedObservationWithNonDefaultNames obs(&o1);
+    obs.Observe(&s1);
+    EXPECT_EQ(1u, s1.impl().num_observers());
+    EXPECT_TRUE(s1.impl().HasObserver(&o1));
+  }
+}
+
+}  // namespace base