public/util/immutable.h

// Copyright (c) 2012 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 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 SYNC_UTIL_IMMUTABLE_H_
#define SYNC_UTIL_IMMUTABLE_H_

// For std::swap().
#include <algorithm>

#include "base/basictypes.h"
#include "base/memory/ref_counted.h"

namespace syncer {

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:
  // wrapper_ is always explicitly default-initialized to handle
  // primitive types and the case where Traits::Wrapper == T.

  ImmutableCore() : wrapper_() {
    Traits::InitializeWrapper(&wrapper_);
  }

  explicit ImmutableCore(T* t) : wrapper_() {
    Traits::InitializeWrapper(&wrapper_);
    Traits::Swap(Traits::UnwrapMutable(&wrapper_), t);
  }

  const T& Get() const {
    return Traits::Unwrap(wrapper_);
  }

 private:
  ~ImmutableCore() {
    Traits::DestroyWrapper(&wrapper_);
  }
  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::Wrapper wrapper_;

  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).  (This is why the Traits::Wrapper type exists; normally,
// Traits::Wrapper is just T itself, but that needs to be changed for
// forward-declared types.)
//
// For example, if you want to do this:
//
//   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* Wrapper;
//
//       static void InitializeWrapper(Wrapper* wrapper);
//
//       static void DestroyWrapper(Wrapper* wrapper);
//       ...
//     };
//
//     typedef Immutable<SomeOtherType, ImmutableSomeOtherTypeTraits>
//         ImmutableSomeOtherType;
//
//     ImmutableSomeOtherType foo_;
//   };
//
//   my_class.cc
//   -----------
//   #include ".../some_other_type.h"
//
//   void MyClass::ImmutableSomeOtherTypeTraits::InitializeWrapper(
//       Wrapper* wrapper) {
//     *wrapper = new SomeOtherType();
//   }
//
//   void MyClass::ImmutableSomeOtherTypeTraits::DestroyWrapper(
//       Wrapper* wrapper) {
//     delete *wrapper;
//   }
//
//   ...
//
// Also note that this incurs an additional memory allocation when you
// create an Immutable<SomeOtherType>.

template <typename T>
struct DefaultImmutableTraits {
  typedef T Wrapper;

  static void InitializeWrapper(Wrapper* wrapper) {}

  static void DestroyWrapper(Wrapper* wrapper) {}

  static const T& Unwrap(const Wrapper& wrapper) { return wrapper; }

  static T* UnwrapMutable(Wrapper* wrapper) { return wrapper; }

  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 syncer

#endif  // SYNC_UTIL_IMMUTABLE_H_