juce/source/src/core/juce_Singleton.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_SINGLETON_JUCEHEADER__
  27 #define __JUCE_SINGLETON_JUCEHEADER__
  28
  29
  30 //==============================================================================
  31 /**
  32     Macro to declare member variables and methods for a singleton class.
  33
  34     To use this, add the line juce_DeclareSingleton (MyClass, doNotRecreateAfterDeletion)
  35     to the class's definition.
  36
  37     Then put a macro juce_ImplementSingleton (MyClass) along with the class's
  38     implementation code.
  39
  40     It's also a very good idea to also add the call clearSingletonInstance() in your class's
  41     destructor, in case it is deleted by other means than deleteInstance()
  42
  43     Clients can then call the static method MyClass::getInstance() to get a pointer
  44     to the singleton, or MyClass::getInstanceWithoutCreating() which will return 0 if
  45     no instance currently exists.
  46
  47     e.g. @code
  48
  49         class MySingleton
  50         {
  51         public:
  52             MySingleton()
  53             {
  54             }
  55
  56             ~MySingleton()
  57             {
  58                 // this ensures that no dangling pointers are left when the
  59                 // singleton is deleted.
  60                 clearSingletonInstance();
  61             }
  62
  63             juce_DeclareSingleton (MySingleton, false)
  64         };
  65
  66         juce_ImplementSingleton (MySingleton)
  67
  68
  69         // example of usage:
  70         MySingleton* m = MySingleton::getInstance(); // creates the singleton if there isn't already one.
  71
  72         ...
  73
  74         MySingleton::deleteInstance(); // safely deletes the singleton (if it's been created).
  75
  76     @endcode
  77
  78     If doNotRecreateAfterDeletion = true, it won't allow the object to be created more
  79     than once during the process's lifetime - i.e. after you've created and deleted the
  80     object, getInstance() will refuse to create another one. This can be useful to stop
  81     objects being accidentally re-created during your app's shutdown code.
  82
  83     If you know that your object will only be created and deleted by a single thread, you
  84     can use the slightly more efficient juce_DeclareSingleton_SingleThreaded() macro instead
  85     of this one.
  86
  87     @see juce_ImplementSingleton, juce_DeclareSingleton_SingleThreaded
  88 */
  89 #define juce_DeclareSingleton(classname, doNotRecreateAfterDeletion) \
  90 \
  91     static classname* _singletonInstance;  \
  92     static JUCE_NAMESPACE::CriticalSection _singletonLock; \
  93 \
  94     static classname* JUCE_CALLTYPE getInstance() \
  95     { \
  96         if (_singletonInstance == nullptr) \
  97         {\
  98             const JUCE_NAMESPACE::ScopedLock sl (_singletonLock); \
  99 \
 100             if (_singletonInstance == nullptr) \
 101             { \
 102                 static bool alreadyInside = false; \
 103                 static bool createdOnceAlready = false; \
 104 \
 105                 const bool problem = alreadyInside || ((doNotRecreateAfterDeletion) && createdOnceAlready); \
 106                 jassert (! problem); \
 107                 if (! problem) \
 108                 { \
 109                     createdOnceAlready = true; \
 110                     alreadyInside = true; \
 111                     classname* newObject = new classname();  /* (use a stack variable to avoid setting the newObject value before the class has finished its constructor) */ \
 112                     alreadyInside = false; \
 113 \
 114                     _singletonInstance = newObject; \
 115                 } \
 116             } \
 117         } \
 118 \
 119         return _singletonInstance; \
 120     } \
 121 \
 122     static inline classname* JUCE_CALLTYPE getInstanceWithoutCreating() noexcept\
 123     { \
 124         return _singletonInstance; \
 125     } \
 126 \
 127     static void JUCE_CALLTYPE deleteInstance() \
 128     { \
 129         const JUCE_NAMESPACE::ScopedLock sl (_singletonLock); \
 130         if (_singletonInstance != nullptr) \
 131         { \
 132             classname* const old = _singletonInstance; \
 133             _singletonInstance = nullptr; \
 134             delete old; \
 135         } \
 136     } \
 137 \
 138     void clearSingletonInstance() noexcept\
 139     { \
 140         if (_singletonInstance == this) \
 141             _singletonInstance = nullptr; \
 142     }
 143
 144
 145 //==============================================================================
 146 /** This is a counterpart to the juce_DeclareSingleton macro.
 147
 148     After adding the juce_DeclareSingleton to the class definition, this macro has
 149     to be used in the cpp file.
 150 */
 151 #define juce_ImplementSingleton(classname) \
 152 \
 153     classname* classname::_singletonInstance = nullptr; \
 154     JUCE_NAMESPACE::CriticalSection classname::_singletonLock;
 155
 156
 157 //==============================================================================
 158 /**
 159     Macro to declare member variables and methods for a singleton class.
 160
 161     This is exactly the same as juce_DeclareSingleton, but doesn't use a critical
 162     section to make access to it thread-safe. If you know that your object will
 163     only ever be created or deleted by a single thread, then this is a
 164     more efficient version to use.
 165
 166     If doNotRecreateAfterDeletion = true, it won't allow the object to be created more
 167     than once during the process's lifetime - i.e. after you've created and deleted the
 168     object, getInstance() will refuse to create another one. This can be useful to stop
 169     objects being accidentally re-created during your app's shutdown code.
 170
 171     See the documentation for juce_DeclareSingleton for more information about
 172     how to use it, the only difference being that you have to use
 173     juce_ImplementSingleton_SingleThreaded instead of juce_ImplementSingleton.
 174
 175     @see juce_ImplementSingleton_SingleThreaded, juce_DeclareSingleton, juce_DeclareSingleton_SingleThreaded_Minimal
 176 */
 177 #define juce_DeclareSingleton_SingleThreaded(classname, doNotRecreateAfterDeletion) \
 178 \
 179     static classname* _singletonInstance;  \
 180 \
 181     static classname* getInstance() \
 182     { \
 183         if (_singletonInstance == nullptr) \
 184         { \
 185             static bool alreadyInside = false; \
 186             static bool createdOnceAlready = false; \
 187 \
 188             const bool problem = alreadyInside || ((doNotRecreateAfterDeletion) && createdOnceAlready); \
 189             jassert (! problem); \
 190             if (! problem) \
 191             { \
 192                 createdOnceAlready = true; \
 193                 alreadyInside = true; \
 194                 classname* newObject = new classname();  /* (use a stack variable to avoid setting the newObject value before the class has finished its constructor) */ \
 195                 alreadyInside = false; \
 196 \
 197                 _singletonInstance = newObject; \
 198             } \
 199         } \
 200 \
 201         return _singletonInstance; \
 202     } \
 203 \
 204     static inline classname* getInstanceWithoutCreating() noexcept\
 205     { \
 206         return _singletonInstance; \
 207     } \
 208 \
 209     static void deleteInstance() \
 210     { \
 211         if (_singletonInstance != nullptr) \
 212         { \
 213             classname* const old = _singletonInstance; \
 214             _singletonInstance = nullptr; \
 215             delete old; \
 216         } \
 217     } \
 218 \
 219     void clearSingletonInstance() noexcept\
 220     { \
 221         if (_singletonInstance == this) \
 222             _singletonInstance = nullptr; \
 223     }
 224
 225 //==============================================================================
 226 /**
 227     Macro to declare member variables and methods for a singleton class.
 228
 229     This is like juce_DeclareSingleton_SingleThreaded, but doesn't do any checking
 230     for recursion or repeated instantiation. It's intended for use as a lightweight
 231     version of a singleton, where you're using it in very straightforward
 232     circumstances and don't need the extra checking.
 233
 234     Juce use the normal juce_ImplementSingleton_SingleThreaded as the counterpart
 235     to this declaration, as you would with juce_DeclareSingleton_SingleThreaded.
 236
 237     See the documentation for juce_DeclareSingleton for more information about
 238     how to use it, the only difference being that you have to use
 239     juce_ImplementSingleton_SingleThreaded instead of juce_ImplementSingleton.
 240
 241     @see juce_ImplementSingleton_SingleThreaded, juce_DeclareSingleton
 242 */
 243 #define juce_DeclareSingleton_SingleThreaded_Minimal(classname) \
 244 \
 245     static classname* _singletonInstance;  \
 246 \
 247     static classname* getInstance() \
 248     { \
 249         if (_singletonInstance == nullptr) \
 250             _singletonInstance = new classname(); \
 251 \
 252         return _singletonInstance; \
 253     } \
 254 \
 255     static inline classname* getInstanceWithoutCreating() noexcept\
 256     { \
 257         return _singletonInstance; \
 258     } \
 259 \
 260     static void deleteInstance() \
 261     { \
 262         if (_singletonInstance != nullptr) \
 263         { \
 264             classname* const old = _singletonInstance; \
 265             _singletonInstance = nullptr; \
 266             delete old; \
 267         } \
 268     } \
 269 \
 270     void clearSingletonInstance() noexcept\
 271     { \
 272         if (_singletonInstance == this) \
 273             _singletonInstance = nullptr; \
 274     }
 275
 276
 277 //==============================================================================
 278 /** This is a counterpart to the juce_DeclareSingleton_SingleThreaded macro.
 279
 280     After adding juce_DeclareSingleton_SingleThreaded or juce_DeclareSingleton_SingleThreaded_Minimal
 281     to the class definition, this macro has to be used somewhere in the cpp file.
 282 */
 283 #define juce_ImplementSingleton_SingleThreaded(classname) \
 284 \
 285     classname* classname::_singletonInstance = nullptr;
 286
 287
 288
 289 #endif   // __JUCE_SINGLETON_JUCEHEADER__