====== Singleton Template (C++) ======

//An inheritance-based way to make singleton classes in C++//


===== License =====

  * **Author:** [[mailto:tjgrant@tatewake.com|Terence J. Grant]]
  * **License:** [[http://opensource.org/licenses/MIT|MIT License]]
  * **Last Update:** 2015-12-21
  * **Donate:** [[:donate|Your donations are appreciated!]]

===== Download =====

Before downloading or using this product, make sure you __**understand and accept**__ the terms of the [[#license]].

After downloading, make sure to follow the [[#how_to_use|how to use]] instructions below; they're worth reading.

  * Latest version: [[https://github.com/tatewake/singleton-template|Singleton Template(C++) version 2015-12-21 on GitHub]]

===== About =====

The Singleton Template is a [[wp>Template_(C%2B%2B)|C++ template class]] that allows you to define your own singleton classes as inheriting from a single base class.

This provides a few benefits over other techniques:

  * Consistent method interface among all singletons (all singletons will have a **''::getInstance()''** method)
  * Never having to copy / paste code for singleton creation (which is good if, for instance, best practices change)

The singleton creation method in **''::getInstance()''** is via the "Meyers Singleton" technique, described in the book [[http://www.amazon.com/gp/product/0321334876/ref=as_li_tl?ie=UTF8&camp=1789&creative=390957&creativeASIN=0321334876&linkCode=as2&tag=terjgra-20&linkId=FWGRI7VTSLU2WGVB|Effective C++ by Scott Meyers]]. So essentially, this class is a "Meyers Singleton C++ template class."
===== How to Use =====

==== Setup ====

  * First, copy the header into your project.
  * Next, include the header somewhere in your project or [[wp>Precompiled_header|precompiled header]] if you use one.

<code c++>
#include "tSingleton.h"
</code>

  * Create your own singleton class, ensuring that:

  - You inherit from **''tSingleton<MyClass>''**, where **''MyClass''** is the name of your class
  - Your **constructor**'s access method is **''protected''**
  - Your **destructor** is **''virtual''**
  - You have the **''friend class''** statement similar to the example below

<code c++>
class MyClass
: public tSingleton<MyClass>
{
protected:
    //Members go here

protected:
    MyClass();
public:
    virtual ~MyClass();

public:
    //Methods go here

    friend class tSingleton<MyClass>;
};
</code>

Your **''MyClass''** class will now have a **''::getInstance()''** method, which you can use to construct the class or get it's instance at runtime.

==== Usage ====

  * Construct the instance like so:

<code c++>
MyClass::getInstance();
</code>

  * Get the instance of the class at any point in time like so and you can do work with it:

<code c++>
MyClass* c = MyClass::getInstance();

if (c)
{
    c->doStuff(); // Assuming you have a method called ::doStuff, this is how you'd call it
}
</code>

  * You can also call methods directly without using a temporary / local variable:

<code c++>
MyClass::getInstance()->doStuff();
</code>

That's it! You should be good to go.

==== Q & A ====

//If you have a question not answered here, please feel free to [[mailto:tjgrant@tatewake.com|contact me]] and ask.//

=== Inheritance? ===

  * **Q:** My class already inherits from another class; can I still use this?
  * **A:** Yes; in fact this is generally the case
    * C++ allows for multiple inheritance so this not a problem; just comma-separate your inheritance classes and you're set
    * As an example, say your class **''MyClass''** originally inherited from **''MyBase''**; you would still follow the example above in [[#setup]] with just a minor change at the beginning:

<code c++>
class MyClass
: public MyBase,
  public tSingleton<MyClass>
</code>

=== Thread Safety? ===

  * **Q:** Is this library [[wp>Thread_safety|thread safe]]? //(Advanced: Won't apply to most users.)//
  * **A:** It's **Conditionally Safe**
    * The first time you call **''::getInstance''**, memory will be written; this is not thread-safe so your first call to **''::getInstance''** should be on the main thread
    * After the first time, **''::getInstance''** only reads memory, so this should be safe on any thread
  * //Note: That said, I would suggest only accessing **''::getInstance''** on the main thread whenever possible//

If you've found this project useful, [[:donate|please donate today!]] :-)
===== History =====

**July 5, 2016**

  * Removed the namespace, renamed class from "singleton" to "tSingleton" like it originally was

**December 21, 2015**

  * Added GitHub link to download section
  * First public release

**November 15, 2015**

  * Created project page