dep/ACE_wrappers/ace/Singleton.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Singleton.h
   6  *
   7  *  $Id: Singleton.h 80826 2008-03-04 14:51:23Z wotte $
   8  *
   9  *  @brief
  10  *
  11  *  @author Tim Harrison <harrison@cs.wustl.edu>
  12  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
  13  *  @author Chris Lahey
  14  *  @author Rich Christy
  15  *  @author David Levine <levine@cs.wustl.edu>
  16  */
  17 //=============================================================================
  18
  19 #ifndef ACE_SINGLETON_H
  20 #define ACE_SINGLETON_H
  21 #include /**/ "ace/pre.h"
  22
  23 #include /**/ "ace/config-all.h"
  24 #include "ace/TSS_T.h"
  25 #include "ace/Cleanup.h"
  26
  27 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  28 # pragma once
  29 #endif /* ACE_LACKS_PRAGMA_ONCE */
  30
  31 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  32
  33 /**
  34  * @class ACE_Singleton
  35  *
  36  * @brief A Singleton Adapter uses the Adapter pattern to turn ordinary
  37  * classes into Singletons optimized with the Double-Checked
  38  * Locking optimization pattern.
  39  *
  40  * This implementation is a slight variation on the GoF
  41  * Singleton pattern.  In particular, a single
  42  * <ACE_Singleton<TYPE, ACE_LOCK> > instance is allocated here,
  43  * not a <TYPE> instance.  The reason for this is to allow
  44  * registration with the ACE_Object_Manager, so that the
  45  * Singleton can be cleaned up when the process exits.  For this
  46  * scheme to work, a (static) cleanup() function must be
  47  * provided.  ACE_Singleton provides one so that TYPE doesn't
  48  * need to.
  49  * If you want to make sure that only the singleton instance of
  50  * <T> is created, and that users cannot create their own
  51  * instances of <T>, do the following to class <T>:
  52  * (a) Make the constructor of <T> private (or protected)
  53  * (b) Make Singleton a friend of <T>
  54  * Here is an example:
  55  * @verbatim
  56  * class foo
  57  * {
  58  * friend class ACE_Singleton<foo, ACE_Null_Mutex>;
  59  * private:
  60  * foo () { cout << "foo constructed" << endl; }
  61  * ~foo () { cout << "foo destroyed" << endl; }
  62  * };
  63  * typedef ACE_Singleton<foo, ACE_Null_Mutex> FOO;
  64  * @endverbatim
  65  *
  66  * @note The best types to use for ACE_LOCK are
  67  * ACE_Recursive_Thread_Mutex and ACE_Null_Mutex.
  68  * ACE_Recursive_Thread_Mutex should be used in multi-threaded
  69  * programs in which it is possible for more than one thread to
  70  * access the <ACE_Singleton<TYPE, ACE_LOCK>> instance.
  71  * ACE_Null_Mutex can be used otherwise.  The reason that these
  72  * types of locks are best has to do with their allocation by
  73  * the ACE_Object_Manager.  Single ACE_Recursive_Thread_Mutex
  74  * and ACE_Null_Mutex instances are used for all ACE_Singleton
  75  * instantiations.  However, other types of locks are allocated
  76  * per ACE_Singleton instantiation.
  77  */
  78 template <class TYPE, class ACE_LOCK>
  79 class ACE_Singleton : public ACE_Cleanup
  80 {
  81 public:
  82   /// Global access point to the Singleton.
  83   static TYPE *instance (void);
  84
  85   /// Cleanup method, used by <ace_cleanup_destroyer> to destroy the
  86   /// ACE_Singleton.
  87   virtual void cleanup (void *param = 0);
  88
  89   /// Dump the state of the object.
  90   static void dump (void);
  91
  92 protected:
  93   /// Default constructor.
  94   ACE_Singleton (void);
  95
  96   /// Contained instance.
  97   TYPE instance_;
  98
  99 #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES)
 100   /// Pointer to the Singleton (ACE_Cleanup) instance.
 101   static ACE_Singleton<TYPE, ACE_LOCK> *singleton_;
 102 #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */
 103
 104   /// Get pointer to the Singleton instance.
 105   static ACE_Singleton<TYPE, ACE_LOCK> *&instance_i (void);
 106 };
 107
 108 /**
 109  * @class ACE_Unmanaged_Singleton
 110  *
 111  * @brief Same as ACE_Singleton, except does _not_ register with
 112  * ACE_Object_Manager for destruction.
 113  *
 114  * This version of ACE_Singleton can be used if, for example,
 115  * its DLL will be unloaded before the ACE_Object_Manager
 116  * destroys the instance.  Unlike with ACE_Singleton, the
 117  * application is responsible for explicitly destroying the
 118  * instance after it is no longer needed (if it wants to avoid
 119  * memory leaks, at least).  The close() static member function
 120  * must be used to explicitly destroy the Singleton.
 121  * Usage is the same as for ACE_Singleton, but note that if you
 122  * you declare a friend, the friend class must still be an
 123  * *ACE_Singleton*<T, [ACE_LOCK]>, not an ACE_Unmanaged_Singleton.
 124  */
 125 template <class TYPE, class ACE_LOCK>
 126 class ACE_Unmanaged_Singleton : public ACE_Singleton <TYPE, ACE_LOCK>
 127 {
 128 public:
 129   /// Global access point to the Singleton.
 130   static TYPE *instance (void);
 131
 132   /// Explicitly delete the Singleton instance.
 133   static void close (void);
 134
 135   /// Dump the state of the object.
 136   static void dump (void);
 137
 138 protected:
 139   /// Default constructor.
 140   ACE_Unmanaged_Singleton (void);
 141
 142 #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES)
 143   /// Pointer to the Singleton (ACE_Cleanup) instance.
 144   static ACE_Unmanaged_Singleton<TYPE, ACE_LOCK> *singleton_;
 145 #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */
 146
 147   /// Get pointer to the Singleton instance.
 148   static ACE_Unmanaged_Singleton<TYPE, ACE_LOCK> *&instance_i (void);
 149 };
 150
 151 /**
 152  * @class ACE_TSS_Singleton
 153  *
 154  * @brief This class uses the Adapter pattern to turn ordinary classes
 155  * into Thread-specific Singletons optimized with the
 156  * Double-Checked Locking optimization pattern.
 157  *
 158  * This implementation is another variation on the GoF Singleton
 159  * pattern.  In this case, a single <ACE_TSS_Singleton<TYPE,
 160  * LOCK> > instance is allocated here, not a <TYPE> instance.
 161  * Each call to the <instance> static method returns a Singleton
 162  * whose pointer resides in thread-specific storage.  As with
 163  * ACE_Singleton, we use the ACE_Object_Manager so that the
 164  * Singleton can be cleaned up when the process exits.  For this
 165  * scheme to work, a (static) cleanup() function must be
 166  * provided.  ACE_Singleton provides one so that TYPE doesn't
 167  * need to.
 168  */
 169 template <class TYPE, class ACE_LOCK>
 170 class ACE_TSS_Singleton : public ACE_Cleanup
 171 {
 172 public:
 173   /// Global access point to the singleton.
 174   static TYPE *instance (void);
 175
 176   /// Cleanup method, used by <ace_cleanup_destroyer> to destroy the
 177   /// singleton.
 178   virtual void cleanup (void *param = 0);
 179
 180   /// Dump the state of the object.
 181   static void dump (void);
 182
 183 protected:
 184   /// Default constructor.
 185   ACE_TSS_Singleton (void);
 186
 187   /// Contained instance.
 188   ACE_TSS_TYPE (TYPE) instance_;
 189
 190   ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_TSS_Singleton<TYPE,ACE_LOCK> &))
 191   ACE_UNIMPLEMENTED_FUNC (ACE_TSS_Singleton (const ACE_TSS_Singleton<TYPE,ACE_LOCK> &))
 192
 193 #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES)
 194   /// Pointer to the Singleton (ACE_Cleanup) instance.
 195   static ACE_TSS_Singleton<TYPE, ACE_LOCK> *singleton_;
 196 #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */
 197
 198   /// Get pointer to the TSS Singleton instance.
 199   static ACE_TSS_Singleton<TYPE, ACE_LOCK> *&instance_i (void);
 200 };
 201
 202 /**
 203  * @class ACE_Unmanaged_TSS_Singleton
 204  *
 205  * @brief Same as ACE_TSS_Singleton, except does _not_ register with
 206  * ACE_Object_Manager for destruction.
 207  *
 208  * This version of ACE_TSS_Singleton can be used if, for example, its DLL will
 209  * be unloaded before the ACE_Object_Manager destroys the instance.  Unlike with
 210  * ACE_Singleton, the application is responsible for explicitly destroying the
 211  * instance after it is no longer needed (if it wants to avoid memory leaks,
 212  * at least).  The close() static member function must be used to explicitly
 213  * destroy the Singleton.
 214  */
 215 template <class TYPE, class ACE_LOCK>
 216 class ACE_Unmanaged_TSS_Singleton : public ACE_TSS_Singleton <TYPE, ACE_LOCK>
 217 {
 218 public:
 219   /// Global access point to the singleton.
 220   static TYPE *instance (void);
 221
 222   /// Explicitly delete the singleton instance.
 223   static void close (void);
 224
 225   /// Dump the state of the object.
 226   static void dump (void);
 227
 228 protected:
 229   /// Default constructor.
 230   ACE_Unmanaged_TSS_Singleton (void);
 231
 232 #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES)
 233   /// Pointer to the Singleton (ACE_Cleanup) instance.
 234   static ACE_Unmanaged_TSS_Singleton<TYPE, ACE_LOCK> *singleton_;
 235 #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */
 236
 237   /// Get pointer to the Singleton instance.
 238   static ACE_Unmanaged_TSS_Singleton<TYPE, ACE_LOCK> *&instance_i (void);
 239 };
 240
 241 /**
 242  * @class ACE_DLL_Singleton_T
 243  *
 244  * @brief Same as ACE_Singleton, except that it registers for
 245  * destruction with the ACE_Framework_Repository instead of
 246  * with the ACE_Object_Manager directly.
 247  *
 248  * This version of ACE_Singleton should be used for singletons
 249  * that live in a dll loaded either directly by ACE_DLL or indirectly
 250  * by the ACE Service Configuration framework.  Whenever ACE_DLL is ready
 251  * to actually unload the dll, ACE_DLL_Singleton based dlls associated
 252  * with that dll will be destroyed first.  In fact, any singleton can
 253  * safely use ACE_DLL_Singleton, even those that don't live in dlls.  In
 254  * that case, the singleton will be destroyed at normal program shutdown.
 255  *
 256  * The only additional requirement is that the contained class
 257  * export name() and dll_name() methods.  See ACE_DLL_Singleton_Adapter_T
 258  * below for a convenient example of how to satisfy this
 259  * requirement for the dll_name().
 260  *
 261  * Usage is the same as for ACE_Singleton, but note that if you
 262  * you declare a friend, the friend class must still be an
 263  * *ACE_Singleton*<T, [ACE_LOCK]>, not an ACE_Unmanaged_Singleton.
 264  */
 265 template <class TYPE, class ACE_LOCK>
 266 class ACE_DLL_Singleton_T
 267 {
 268 public:
 269   //void cleanup (void *param = 0);
 270
 271   /// Global access point to the Singleton.
 272   static TYPE *instance (void);
 273
 274   /// Explicitly delete the Singleton instance.
 275   static void close (void);
 276
 277   static void close_singleton (void);
 278
 279   /// Dump the state of the object.
 280   static void dump (void);
 281
 282   const ACE_TCHAR *dll_name (void);
 283
 284   const ACE_TCHAR *name (void);
 285
 286 protected:
 287   /// Default constructor.
 288   ACE_DLL_Singleton_T (void);
 289
 290   /// Destructor.
 291   ~ACE_DLL_Singleton_T (void);
 292
 293   /// Contained instance.
 294   TYPE instance_;
 295
 296 #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES)
 297   /// Pointer to the Singleton instance.
 298   static ACE_DLL_Singleton_T<TYPE, ACE_LOCK> *singleton_;
 299 #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */
 300
 301   /// Get pointer to the singleton instance.
 302   static ACE_DLL_Singleton_T<TYPE, ACE_LOCK> *&instance_i (void);
 303 };
 304
 305 template <class TYPE>
 306 class ACE_DLL_Singleton_Adapter_T : public TYPE
 307 {
 308 public:
 309   const ACE_TCHAR *dll_name (void);
 310 };
 311
 312 ACE_END_VERSIONED_NAMESPACE_DECL
 313
 314 #if defined (__ACE_INLINE__)
 315 #include "ace/Singleton.inl"
 316 #endif /* __ACE_INLINE__ */
 317
 318 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
 319 #include "ace/Singleton.cpp"
 320 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
 321
 322 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
 323 #pragma implementation ("Singleton.cpp")
 324 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
 325
 326 #include /**/ "ace/post.h"
 327 #endif /* ACE_SINGLETON_H */