Singleton.h

Go to the documentation of this file.

/*
 * Copyright (C) 2012 by
 *   MetraLabs GmbH (MLAB), GERMANY
 * and
 *   Neuroinformatics and Cognitive Robotics Labs (NICR) at TU Ilmenau, GERMANY
 * All rights reserved.
 *
 * Contact: info@mira-project.org
 *
 * Commercial Usage:
 *   Licensees holding valid commercial licenses may use this file in
 *   accordance with the commercial license agreement provided with the
 *   software or, alternatively, in accordance with the terms contained in
 *   a written agreement between you and MLAB or NICR.
 *
 * GNU General Public License Usage:
 *   Alternatively, this file may be used under the terms of the GNU
 *   General Public License version 3.0 as published by the Free Software
 *   Foundation and appearing in the file LICENSE.GPL3 included in the
 *   packaging of this file. Please review the following information to
 *   ensure the GNU General Public License version 3.0 requirements will be
 *   met: http://www.gnu.org/copyleft/gpl.html.
 *   Alternatively you may (at your option) use any later version of the GNU
 *   General Public License if such license has been publicly approved by
 *   MLAB and NICR (or its successors, if any).
 *
 * IN NO EVENT SHALL "MLAB" OR "NICR" BE LIABLE TO ANY PARTY FOR DIRECT,
 * INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
 * THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF "MLAB" OR
 * "NICR" HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * "MLAB" AND "NICR" SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
 * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND "MLAB" AND "NICR" HAVE NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS.
 */

#ifndef _MIRA_SINGLETON_H_
#define _MIRA_SINGLETON_H_

#ifndef Q_MOC_RUN
#include <type_traits>
#include <boost/thread/mutex.hpp>
#endif

#include <error/Exception.h>
#include <platform/Platform.h>
#include <platform/Typename.h>

namespace mira {


namespace Private {

typedef void (*atexit_lifetime_fn) (void);

template <typename T,
          template <class> class I,
          template <class> class C,
          template <class> class L,
          class M>
struct SingletonTrait
{
    // type of singleton class without const and volatile qualifiers
    typedef typename std::remove_cv<T>::type Type;
    typedef I<SingletonTrait> InstantiationPolicy;
    typedef C<Type> CreationPolicy;
    typedef L<Type> LifetimePolicy;
    typedef M LockPolicy;
};

template <typename Trait>
class SingletonBase
{
public:
    typedef typename Trait::InstantiationPolicy InstantiationPolicy;
    typedef typename Trait::CreationPolicy CreationPolicy;
    typedef typename Trait::LifetimePolicy LifetimePolicy;
    typedef typename Trait::LockPolicy LockPolicy;
    typedef typename Trait::Type Type;
    typedef typename LockPolicy::template Volatile<Type>::type* TypePtr;

    SingletonBase() = default;
    SingletonBase(const SingletonBase&) = delete;
    SingletonBase& operator=(const SingletonBase&) = delete;

protected:

    static TypePtr sInstance;
    static bool sDestroyed;

};

// the static member sInstance
template <typename Trait>
typename SingletonBase<Trait>::TypePtr SingletonBase<Trait>::sInstance = NULL;

// the static member sDestroyed
template <typename Trait>
bool SingletonBase<Trait>::sDestroyed = false;

} // namespace Private


MIRA_DEFINE_EXCEPTION(XSingleton, Exception)

namespace singleton {

// Creation policies

template <typename T>
struct CreateUsingNew {
    static T* create() { return new T; }
    static void destroy(T* p) { delete p; }
};

template <typename T>
struct CreateStatic {

#ifdef _MSC_VER
#  define MIRA_CREATESTATIC_ALIGN __declspec(align(16))
#else
#  define MIRA_CREATESTATIC_ALIGN __attribute__((aligned(16)))
#endif

    static T* create() {
        // create 16 byte aligned static memory block
        static MIRA_CREATESTATIC_ALIGN char staticMemory[sizeof(T)];
        return new(&staticMemory) T;
    }
    static void destroy(T* p) {
        p->~T();
    }
#undef MIRA_CREATESTATIC_ALIGN
};

template <template <class> class Alloc>
struct CreateUsing {
    template <typename T>
    struct Allocator {
        static Alloc<T> alloc;
        static T* create() { return new (alloc.allocate(1)) T; }
        static void destroy(T* p) {
            p->~T();
            alloc.deallocate(p,1);
        }
    };
};

// Lifetime Policies

template <typename T>
struct NormalLifetime
{
    static void scheduleDestruction(T*, Private::atexit_lifetime_fn fun) {
        std::atexit(fun);
    }
};

template <typename T>
struct NoDestroyLifetime
{
    static void scheduleDestruction(T*, Private::atexit_lifetime_fn fun) {}
};

// Instantiation policies

template <typename Trait>
class LazyInstantiation : public Private::SingletonBase<Trait>
{
    typedef Private::SingletonBase<Trait> Base;

public:
    typedef typename Base::Type Type;

    static Type& instance() {
        if(!Base::sInstance)
            makeInstance();
        return *((Type*)Base::sInstance);
    }

protected:

    static Type* makeInstance()
    {
        // according to the standard, the creation of static variables is thread-safe
        static typename Base::LockPolicy::Mutex sMutex;

        // protect the instantiation of a new singleton object
        typename Base::LockPolicy::Lock lock(sMutex);

        // together with the check in instance() this is the
        // double-checked locking pattern which is safe, if sInstance is
        // declared volatile
        if(!Base::sInstance) {
            if(Base::sDestroyed)
                MIRA_THROW(XSingleton, "Singleton of class '" 
                           << typeName<Type>() << "' was already destroyed!");

            Type* p = Base::CreationPolicy::create();
            Base::LifetimePolicy::scheduleDestruction(p,&destroyInstance);
            Base::sInstance = p;
        }

        assert(Base::sInstance);
        return (Type*)Base::sInstance;
    }

    static void destroyInstance(void){
        if (!Base::sDestroyed) {
            Base::CreationPolicy::destroy((Type*)Base::sInstance);
            Base::sInstance=NULL;
            Base::sDestroyed=true;
        }
    }
};


template <typename Trait>
class EagerInstantiation : public LazyInstantiation<Trait>
{
    typedef LazyInstantiation<Trait> Base;

public:
    typedef typename Base::Type Type;

    static Type& instance() {
        if(!sInstantiationHelper)
            sInstantiationHelper = Base::makeInstance();

        assert(sInstantiationHelper);
        return *sInstantiationHelper;
    }
private:
    // include this to provoke instantiation at pre-execution time
    static void use(const Type*) {}
    static Type* forceInstantiation() {
        Type* inst = Base::makeInstance();
        // refer to instance, causing it to be instantiated (and
        // initialized at startup on working compilers)
        use(sInstantiationHelper);
        return inst;
    }
    
    static Type* sInstantiationHelper;
};
template <typename Trait>
typename EagerInstantiation<Trait>::Type* EagerInstantiation<Trait>::sInstantiationHelper = EagerInstantiation<Trait>::forceInstantiation();


template <typename Trait>
class ExplicitInstantiation : public Private::SingletonBase<Trait>
{
    typedef Private::SingletonBase<Trait> Base;

public:
    typedef typename Base::Type Type;

    ExplicitInstantiation() {
        if(Base::sInstance!=NULL)
            MIRA_THROW(XSingleton, "There should be just one object of '"
                       << typeName<Type>() << "', you tried to initialize another one!");
        Base::sInstance = static_cast<Type*>(this);
        Base::sDestroyed=false;
    }

    ~ExplicitInstantiation()
    {
        // remove singleton instance
        Base::sInstance = NULL;
        Base::sDestroyed=true;
    }

    static Type& instance()
    {
        if(Base::sInstance==NULL) {
            MIRA_THROW(XSingleton, "No instance of the explicit singleton '" 
                       << typeName<Type>() << "' created, "
                       "or instance was already destroyed. "
                       "You must create one object of this class before "
                       "you can start using it!");
        }
        return *((Type*)Base::sInstance);
    }
};


// Lock Policies

struct NoLock
{
    typedef int Mutex; // use an int as dummy mutex instance
    struct Lock {
        Lock(int) {}
    };
    template <typename T>
    struct Volatile {
        typedef T type;
    };
};

struct MutexLock
{
    typedef boost::mutex Mutex;
    typedef boost::mutex::scoped_lock Lock;

    // adds volatile to T to make the double-checked locking pattern safe
    template <typename T>
    struct Volatile {
        typedef volatile T type;
    };
};

} // namespace singleton


template <typename T,
          template <class> class TInstantiationPolicy = singleton::LazyInstantiation,
          template <class> class TCreationPolicy = singleton::CreateUsingNew,
          template <class> class TLifetimePolicy = singleton::NormalLifetime,
          class TLockPolicy = singleton::MutexLock>
class Singleton : public TInstantiationPolicy<Private::SingletonTrait<T,TInstantiationPolicy,TCreationPolicy,TLifetimePolicy,TLockPolicy>>
{
    typedef TInstantiationPolicy<Private::SingletonTrait<T,TInstantiationPolicy,TCreationPolicy,TLifetimePolicy,TLockPolicy>> Base;
public:

    // type of singleton class T without const and volatile qualifiers
    typedef typename Base::Type Type;

    static Type& instance() {
        return Base::instance();
    }

    static bool isDestroyed() {
        return Base::sDestroyed;
    }

};

template <typename T>
class LazySingleton : public Singleton<T, singleton::LazyInstantiation, singleton::CreateUsingNew> {};

template <typename T>
class EagerSingleton : public Singleton<T, singleton::EagerInstantiation, singleton::CreateUsingNew> {};

template <typename T>
class ExplicitSingleton : public Singleton<T, singleton::ExplicitInstantiation> {};

template <typename T>
class LazySingletonNoLock : public Singleton<T, singleton::LazyInstantiation,
                           singleton::CreateUsingNew, singleton::NormalLifetime,
                           singleton::NoLock> {};

template <typename T>
class EagerSingletonNoLock : public Singleton<T, singleton::EagerInstantiation,
                           singleton::CreateUsingNew, singleton::NormalLifetime,
                           singleton::NoLock> {};


} // namespace

#endif