[Sync] Rework SharedValue<T> into Immutable<T>

chrome/browser/sync/util/immutable.h

+// Copyright (c) 2011 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.
+
+// Immutable<T> provides an easy, cheap, and thread-safe way to pass
+// large immutable data around.
+//
+// For example, consider the following code:
+//
+//  typedef std::vector<LargeObject> LargeObjectList;
+//
+//   void ProcessStuff(const LargeObjectList& stuff) {
+//     for (LargeObjectList::const_iterator it = stuff.begin();
+//          it != stuff.end(); ++it) {
+//       ... process it ...
+//     }
+//   }
+//
+//   ...
+//
+//   LargeObjectList my_stuff;
+//   ... fill my_stuff with lots of LargeObjects ...
+//   some_loop->PostTask(FROM_HERE, base::Bind(&ProcessStuff, my_stuff));
+//
+// The last line incurs the cost of copying my_stuff, which is
+// undesirable.  Here's the above code re-written using Immutable<T>:
+//
+//   void ProcessStuff(
+//       const browser_sync::Immutable<LargeObjectList>& stuff) {
+//     for (LargeObjectList::const_iterator it = stuff.Get().begin();
+//          it != stuff.Get().end(); ++it) {
+//       ... process it ...
+//     }
+//   }
+//
+//   ...
+//
+//   LargeObjectList my_stuff;
+//   ... fill my_stuff with lots of LargeObjects ...
+//   some_loop->PostTask(
+//       FROM_HERE, base::Bind(&ProcessStuff, MakeImmutable(&my_stuff)));
+//
+// The last line, which resets my_stuff to a default-initialized
+// state, incurs only the cost of a swap of LargeObjectLists, which is
+// O(1) for most STL container implementations.  The data in my_stuff
+// is ref-counted (thread-safely), so it is freed as soon as
+// ProcessStuff is finished.
+//
+// NOTE: By default, Immutable<T> relies on ADL
+// (http://en.wikipedia.org/wiki/Argument-dependent_name_lookup) to
+// find a swap() function for T, falling back to std::swap() when
+// necessary.  If you overload swap() for your type in its namespace,
+// or if you specialize std::swap() for your type, (see
+// http://stackoverflow.com/questions/11562/how-to-overload-stdswap
+// for discussion) Immutable<T> should be able to find it.
+//
+// Alternatively, you could explicitly control which swap function is
+// used by providing your own traits class or using one of the
+// pre-defined ones below.  See comments on traits below for details.
+//
+// NOTE: Some complexity is necessary in order to use Immutable<T>
+// with forward-declared types.  See comments on traits below for
+// details.
+
+#ifndef CHROME_BROWSER_SYNC_UTIL_IMMUTABLE_H_
+#define CHROME_BROWSER_SYNC_UTIL_IMMUTABLE_H_
+#pragma once
+
+// For std::swap().
+#include <algorithm>
+
+#include "base/basictypes.h"
+#include "base/memory/ref_counted.h"
+
+namespace browser_sync {
+
+namespace internal {
+// This class is part of the Immutable implementation.  DO NOT USE
+// THIS CLASS DIRECTLY YOURSELF.
+
+template <typename T, typename Traits>
+class ImmutableCore
+    : public base::RefCountedThreadSafe<ImmutableCore<T, Traits> > {
+ public:
+  // container_ is always explicitly default-initialized to handle
+  // primitive types.
+
+  ImmutableCore() : container_() {
+    Traits::CreateAndDefaultInitialize(&container_);
+  }
+
+  explicit ImmutableCore(T* t) : container_() {
+    Traits::CreateAndDefaultInitialize(&container_);
+    Traits::Swap(Traits::UnwrapMutable(&container_), t);
+  }
+
+  const T& Get() const {
+    return Traits::Unwrap(container_);
+  }
+
+ private:
+  ~ImmutableCore() {
+    Traits::Destroy(&container_);
+  }
+  friend class base::RefCountedThreadSafe<ImmutableCore<T, Traits> >;
+
+  // This is semantically const, but we can't mark it a such as we
+  // modify it in the constructor.
+  typename Traits::Container container_;
+
+  DISALLOW_COPY_AND_ASSIGN(ImmutableCore);
+};
+
+}  // namespace internal
+
+// Traits usage notes
+// ------------------
+// The most common reason to use your own traits class is to provide
+// your own swap method.  First, consider the pre-defined traits
+// classes HasSwapMemFn{ByRef,ByPtr} below.  If neither of those work,
+// then define your own traits class inheriting from
+// DefaultImmutableTraits<YourType> (to pick up the defaults for
+// everything else) and provide your own Swap() method.
+//
+// Another reason to use your own traits class is to be able to use
+// Immutable<T> with a forward-declared type (important for protobuf
+// classes, when you want to avoid headers pulling in generated
+// headers).  For example, if you want to do this:

[Nicolas Zea, 2011/09/15 23:39:46]

I find the distinction between the immutable type itself (T above) and
Traits::Container to be a fairly subtle one, and from what I can tell mainly
useful for forward declaring types. Perhaps a comment here emphasizing this
point?

[akalin, 2011/09/16 00:59:59]

Done.

+//
+//   my_class.h
+//   ----------
+//   #include ".../immutable.h"
+//
+//   // Forward declaration.
+//   class SomeOtherType;
+//
+//   class MyClass {
+//     ...
+//    private:
+//     // Doesn't work, as defaults traits class needs SomeOtherType's
+//     // definition to be visible.
+//     Immutable<SomeOtherType> foo_;
+//   };
+//
+// You'll have to do this:
+//
+//   my_class.h
+//   ----------
+//   #include ".../immutable.h"
+//
+//   // Forward declaration.
+//   class SomeOtherType;
+//
+//   class MyClass {
+//     ...
+//    private:
+//     struct ImmutableSomeOtherTypeTraits {
+//       // scoped_ptr<SomeOtherType> won't work here, either.
+//       typedef SomeOtherType* Container;
+//
+//       static void CreateAndDefaultInitialize...
+//       ...
+//     };
+//
+//     typedef Immutable<SomeOtherType, ImmutableSomeOtherTypeTraits>
+//         ImmutableSomeOtherType;
+//
+//     ImmutableSomeOtherType foo_;
+//   };
+//
+//   my_class.cc
+//   -----------
+//   #include ".../some_other_type.h"
+//
+//   void MyClass::ImmutableSomeOtherTypeTraits::CreateAndDefaultInitialize(
+//       Container* t) {
+//     *t = new SomeOtherType();
+//   }
+//
+//   void MyClass::ImmutableSomeOtherTypeTraits::Destroy(Container* t) {
+//     delete *t;
+//   }
+//
+//   ...
+//
+// Also note that this incurs an additional memory allocation when you
+// create an Immutable<SomeOtherType>.
+
+template <typename T>
+struct DefaultImmutableTraits {
+  typedef T Container;
+
+  // The container is already default-initialized, so do nothing.
+  static void CreateAndDefaultInitialize(Container* container) {}
+
+  // Since the container is automatically destroyed, no need to do
+  // anything.
+  static void Destroy(Container* container) {}
+
+  static const T& Unwrap(const Container& container) { return container; }
+
+  static T* UnwrapMutable(Container* container) { return container; }
+
+  static void Swap(T* t1, T* t2) {
+    // Uses ADL (see
+    // http://en.wikipedia.org/wiki/Argument-dependent_name_lookup).
+    using std::swap;
+    swap(*t1, *t2);
+  }
+};
+
+// Most STL containers have by-reference swap() member functions,
+// although they usually already overload std::swap() to use those.
+template <typename T>
+struct HasSwapMemFnByRef : public DefaultImmutableTraits<T> {
+  static void Swap(T* t1, T* t2) {
+    t1->swap(*t2);
+  }
+};
+
+// Most Google-style objects have by-pointer Swap() member functions
+// (for example, generated protocol buffer classes).
+template <typename T>
+struct HasSwapMemFnByPtr : public DefaultImmutableTraits<T> {
+  static void Swap(T* t1, T* t2) {
+    t1->Swap(t2);
+  }
+};
+
+template <typename T, typename Traits = DefaultImmutableTraits<T> >
+class Immutable {
+ public:
+  // Puts the underlying object in a default-initialized state.
+  Immutable() : core_(new internal::ImmutableCore<T, Traits>()) {}
+
+  // Copy constructor and assignment welcome.
+
+  // Resets |t| to a default-initialized state.
+  explicit Immutable(T* t)
+      : core_(new internal::ImmutableCore<T, Traits>(t)) {}
+
+  const T& Get() const {
+    return core_->Get();
+  }
+
+ private:
+  scoped_refptr<const internal::ImmutableCore<T, Traits> > core_;
+};
+
+// Helper function to avoid having to write out template arguments.
+template <typename T>
+Immutable<T> MakeImmutable(T* t) {
+  return Immutable<T>(t);
+}
+
+}  // namespace browser_sync
+
+#endif  // CHROME_BROWSER_SYNC_UTIL_IMMUTABLE_H_