text: // Copyright 2003 Google Inc.
  //
  // The Singleton<Type> class manages a single instance of Type which will be
  // created on first use and (usually) never destroyed.
  //
  //   MyClass* ptr = Singleton<MyClass>::get()
  //   ptr->DoSomething();
  //
  // Singleton<> has no non-static members and is never actually instantiated.
  //
  // WARNING: Read go/singletons before using.
  //
  // This class is thread safe; the constructor will be run at most once, and
  // no user will gain access to the object until the constructor is completed.
  // The underlying Type must of course be thread-safe if you want to use it
  // concurrently.
  //
  // If you want to ensure that your class can only exist as a singleton, make
  // its constructors private, and make Singleton<> a friend:
  //
  //   class MySingletonOnlyClass {
  //    public:
  //     void DoSomething() { ... }
  //    private:
  //     DISALLOW_COPY_AND_ASSIGN(MySingletonOnlyClass);
  //     MySingletonOnlyClass() { ... }
  //     friend class Singleton<MySingletonOnlyClass>;
  //   }
  //
  // If your singleton requires complex initialization, or does not have a
  // suitable default constructor, you can provide a specialization of
  // Singleton<Type>::CreateInstance() to perform the appropriate setup, e.g.:
  //
  //   template <>
  //   Type* Singleton<VirtualType>::CreateInstance() { return new ConcreteImpl; }
  //
  // If you want to initialize something eagerly at startup, rather than lazily
  // upon use, consider using REGISTER_MODULE_INITIALIZER (in base/googleinit.h).
  //
  // This class also allows users to pick a particular instance as the
  // singleton with InjectInstance(). This enables unittesting and
  // dependency injection. It must only be used at program startup.
  //
  // Caveats:
  // (a) The instance is normally never destroyed.  Destroying a Singleton is
  //     complex and error-prone; C++ books go on about this at great length,
  //     and I have seen no perfect general solution to the problem.
  //     We *do* offer UnsafeReset() which is not thread-safe at all.
  //
  // (b) Your class must have a default (no-argument) constructor, or you must
  //     provide a specialization for Singleton<Type>::CreateInstance().
  //
  // (c) Your class's constructor must never throw an exception.
  //
  // Singleton::get() is very fast - about 1ns on a 2.4GHz Core 2.
  
  #ifndef UTIL_GTL_SINGLETON_H__
  #define UTIL_GTL_SINGLETON_H__
  
  #include <stddef.h>
  
  #include <glog/logging.h>
  #include "gutil/logging-inl.h"
  #include "gutil/once.h"
  
  namespace util {
  namespace gtl {
  template <typename SingletonType> class ScopedSingletonOverride;
  template <typename SingletonType> class ScopedSingletonOverrideNoDelete;
  }  // namespace gtl
  }  // namespace util
  
  template <typename Type>
  class Singleton {
   public:
    // Return a pointer to the one true instance of the class.
    static Type* get() {
      GoogleOnceInit(&once_, &Singleton<Type>::Init);
      return instance_;
    }
  
    // WARNING!!!  This function is not thread-safe and may leak memory.
    static void UnsafeReset() {
      delete instance_;
      instance_ = NULL;
      once_.state = GOOGLE_ONCE_INTERNAL_INIT;  // This is the bad part!
    }
  
    // This function is used to replace the instance used by
    // Singleton<Type>::get(). It can be used for breaking dependencies.  For
    // unittesting, you probably want to use ScopedSingletonOverride instead.
    //
    // This function must be called before Singleton<Type>::get() is
    // called and before any threads are created. If these assumptions
    // are violated, anything could happen, but we try to crash in debug
    // mode and do nothing in production.
    static void InjectInstance(Type* instance) {
      injected_instance_ = instance;
      GoogleOnceInit(&once_, &Singleton<Type>::Inject);
      injected_instance_ = NULL;  // Helps detect leaks in the unittest.
      if (instance_ != instance) {
        LOG(DFATAL) << "(jyasskin) InjectInstance() must be called at most once"
                    << " at the start of the program, before the Singleton has"
                    << " been accessed and before any threads have been created."
                    << " Ignoring the call in production.";
        delete instance;
      }
    }
  
   private:
    friend class util::gtl::ScopedSingletonOverride<Type>;
    friend class util::gtl::ScopedSingletonOverrideNoDelete<Type>;
  
    // Create the instance.
    static void Init() {
      instance_ = CreateInstance();
    }
  
    // Create and return the instance. You can use Singleton for objects which
    // require more complex setup by defining a specialization for your type.
    static Type* CreateInstance() {
      // use ::new to work around a gcc bug when operator new is overloaded
      return ::new Type;
    }
  
    // Inject the instance.
    static void Inject() {
      instance_ = injected_instance_;
    }
  
    // Used by ScopedSingletonOverride.  Definitely not threadsafe.  No one
    // should be calling this other than ScopedSingletonOverride (which has
    // friend access to do this and makes sure it calls get() first).
    static void OverrideSingleton(Type* override_instance) {
      instance_ = override_instance;
    }
  
    static GoogleOnceType once_;
    static Type* instance_;
    static Type* injected_instance_;
  };
  
  template <typename Type>
  GoogleOnceType Singleton<Type>::once_ = GOOGLE_ONCE_INIT;
  
  template <typename Type>
  Type* Singleton<Type>::instance_ = NULL;
  
  template <typename Type>
  Type* Singleton<Type>::injected_instance_ = NULL;
  
  #endif  // UTIL_GTL_SINGLETON_H__
  