Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Singleton.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Singleton.h
00006  *
00007  *  $Id: Singleton.h,v 1.1.1.4 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  @brief
00010  *
00011  *  @author Tim Harrison <harrison@cs.wustl.edu>
00012  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
00013  *  @author Chris Lahey
00014  *  @author Rich Christy
00015  *  @author David Levine <levine@cs.wustl.edu>
00016  */
00017 //=============================================================================
00018 
00019 
00020 #ifndef ACE_SINGLETON_H
00021 #define ACE_SINGLETON_H
00022 #include "ace/pre.h"
00023 
00024 #include "ace/Synch.h"
00025 
00026 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00027 # pragma once
00028 #endif /* ACE_LACKS_PRAGMA_ONCE */
00029 
00030 /**
00031  * @class ACE_Singleton
00032  *
00033  * @brief A Singleton Adapter uses the Adapter pattern to turn ordinary
00034  * classes into Singletons optimized with the Double-Checked
00035  * Locking optimization pattern.
00036  *
00037  * This implementation is a slight variation on the GoF
00038  * Singleton pattern.  In particular, a single
00039  * <ACE_Singleton<TYPE, ACE_LOCK> > instance is allocated here,
00040  * not a <TYPE> instance.  The reason for this is to allow
00041  * registration with the ACE_Object_Manager, so that the
00042  * Singleton can be cleaned up when the process exits.  For this
00043  * scheme to work, a (static) cleanup() function must be
00044  * provided.  ACE_Singleton provides one so that TYPE doesn't
00045  * need to.
00046  * If you want to make sure that only the singleton instance of
00047  * <T> is created, and that users cannot create their own
00048  * instances of <T>, do the following to class <T>:
00049  * (a) Make the constructor of <T> private (or protected)
00050  * (b) Make Singleton a friend of <T>
00051  * Here is an example:
00052  * @verbatim
00053  * class foo
00054  * {
00055  * friend class ACE_Singleton<foo, ACE_Null_Mutex>;
00056  * private:
00057  * foo () { cout << "foo constructed" << endl; }
00058  * ~foo () { cout << "foo destroyed" << endl; }
00059  * };
00060  * typedef ACE_Singleton<foo, ACE_Null_Mutex> FOO;
00061  * @endverbatim
00062  *
00063  * NOTE:  the best types to use for ACE_LOCK are
00064  * ACE_Recursive_Thread_Mutex and ACE_Null_Mutex.
00065  * ACE_Recursive_Thread_Mutex should be used in multi-threaded
00066  * programs in which it is possible for more than one thread to
00067  * access the <ACE_Singleton<TYPE, ACE_LOCK>> instance.
00068  * ACE_Null_Mutex can be used otherwise.  The reason that these
00069  * types of locks are best has to do with their allocation by
00070  * the ACE_Object_Manager.  Single ACE_Recursive_Thread_Mutex
00071  * and ACE_Null_Mutex instances are used for all ACE_Singleton
00072  * instantiations.  However, other types of locks are allocated
00073  * per ACE_Singleton instantiation.
00074  */
00075 template <class TYPE, class ACE_LOCK>
00076 class ACE_Singleton : public ACE_Cleanup
00077 {
00078 public:
00079   /// Global access point to the Singleton.
00080   static TYPE *instance (void);
00081 
00082   /// Cleanup method, used by <ace_cleanup_destroyer> to destroy the
00083   /// ACE_Singleton.
00084   virtual void cleanup (void *param = 0);
00085 
00086   /// Dump the state of the object.
00087   static void dump (void);
00088 
00089 protected:
00090   /// Default constructor.
00091   ACE_Singleton (void);
00092 
00093   /// Contained instance.
00094   TYPE instance_;
00095 
00096 #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES)
00097   /// Pointer to the Singleton (ACE_Cleanup) instance.
00098   static ACE_Singleton<TYPE, ACE_LOCK> *singleton_;
00099 #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */
00100 
00101   /// Get pointer to the Singleton instance.
00102   static ACE_Singleton<TYPE, ACE_LOCK> *&instance_i (void);
00103 };
00104 
00105 /**
00106  * @class ACE_Unmanaged_Singleton
00107  *
00108  * @brief Same as ACE_Singleton, except does _not_ register with
00109  * ACE_Object_Manager for destruction.
00110  *
00111  * This version of ACE_Singleton can be used if, for example,
00112  * its DLL will be unloaded before the ACE_Object_Manager
00113  * destroys the instance.  Unlike with ACE_Singleton, the
00114  * application is responsible for explicitly destroying the
00115  * instance after it is no longer needed (if it wants to avoid
00116  * memory leaks, at least).  The close() static member function
00117  * must be used to explicitly destroy the Singleton.
00118  * Usage is the same as for ACE_Singleton, but note that if you
00119  * you declare a friend, the friend class must still be an
00120  * *ACE_Singleton*<T, [ACE_LOCK]>, not an ACE_Unmanaged_Singleton.
00121  */
00122 template <class TYPE, class ACE_LOCK>
00123 class ACE_Unmanaged_Singleton : public ACE_Singleton <TYPE, ACE_LOCK>
00124 {
00125 public:
00126   /// Global access point to the Singleton.
00127   static TYPE *instance (void);
00128 
00129   /// Explicitly delete the Singleton instance.
00130   static void close (void);
00131 
00132   /// Dump the state of the object.
00133   static void dump (void);
00134 
00135 protected:
00136   /// Default constructor.
00137   ACE_Unmanaged_Singleton (void);
00138 
00139 #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES)
00140   /// Pointer to the Singleton (ACE_Cleanup) instance.
00141   static ACE_Unmanaged_Singleton<TYPE, ACE_LOCK> *singleton_;
00142 #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */
00143 
00144   /// Get pointer to the Singleton instance.
00145   static ACE_Unmanaged_Singleton<TYPE, ACE_LOCK> *&instance_i (void);
00146 };
00147 
00148 /**
00149  * @class ACE_TSS_Singleton
00150  *
00151  * @brief This class uses the Adapter pattern to turn ordinary classes
00152  * into Thread-specific Singletons optimized with the
00153  * Double-Checked Locking optimization pattern.
00154  *
00155  * This implementation is another variation on the GoF Singleton
00156  * pattern.  In this case, a single <ACE_TSS_Singleton<TYPE,
00157  * LOCK> > instance is allocated here, not a <TYPE> instance.
00158  * Each call to the <instance> static method returns a Singleton
00159  * whose pointer resides in thread-specific storage.  As with
00160  * ACE_Singleton, we use the ACE_Object_Manager so that the
00161  * Singleton can be cleaned up when the process exits.  For this
00162  * scheme to work, a (static) cleanup() function must be
00163  * provided.  ACE_Singleton provides one so that TYPE doesn't
00164  * need to.
00165  */
00166 template <class TYPE, class ACE_LOCK>
00167 class ACE_TSS_Singleton : public ACE_Cleanup
00168 {
00169 public:
00170   /// Global access point to the singleton.
00171   static TYPE *instance (void);
00172 
00173   /// Cleanup method, used by <ace_cleanup_destroyer> to destroy the
00174   /// singleton.
00175   virtual void cleanup (void *param = 0);
00176 
00177   /// Dump the state of the object.
00178   static void dump (void);
00179 
00180 protected:
00181   /// Default constructor.
00182   ACE_TSS_Singleton (void);
00183 
00184   /// Contained instance.
00185   ACE_TSS_TYPE (TYPE) instance_;
00186 
00187   ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_TSS_Singleton<TYPE,ACE_LOCK> &))
00188   ACE_UNIMPLEMENTED_FUNC (ACE_TSS_Singleton (const ACE_TSS_Singleton<TYPE,ACE_LOCK> &))
00189 
00190 #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES)
00191   /// Pointer to the Singleton (ACE_Cleanup) instance.
00192   static ACE_TSS_Singleton<TYPE, ACE_LOCK> *singleton_;
00193 #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */
00194 
00195   /// Get pointer to the TSS Singleton instance.
00196   static ACE_TSS_Singleton<TYPE, ACE_LOCK> *&instance_i (void);
00197 };
00198 
00199 /**
00200  * @class ACE_Unmanaged_TSS_Singleton
00201  *
00202  * @brief Same as ACE_TSS_Singleton, except does _not_ register with
00203  * ACE_Object_Manager for destruction.
00204  *
00205  * This version of ACE_TSS_Singleton can be used if, for example, its DLL will
00206  * be unloaded before the ACE_Object_Manager destroys the instance.  Unlike with
00207  * ACE_Singleton, the application is responsible for explicitly destroying the
00208  * instance after it is no longer needed (if it wants to avoid memory leaks,
00209  * at least).  The close() static member function must be used to explicitly
00210  * destroy the Singleton.
00211  */
00212 template <class TYPE, class ACE_LOCK>
00213 class ACE_Unmanaged_TSS_Singleton : public ACE_TSS_Singleton <TYPE, ACE_LOCK>
00214 {
00215 public:
00216   /// Global access point to the singleton.
00217   static TYPE *instance (void);
00218 
00219   /// Explicitly delete the singleton instance.
00220   static void close (void);
00221 
00222   /// Dump the state of the object.
00223   static void dump (void);
00224 
00225 protected:
00226   /// Default constructor.
00227   ACE_Unmanaged_TSS_Singleton (void);
00228 
00229 #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES)
00230   /// Pointer to the Singleton (ACE_Cleanup) instance.
00231   static ACE_Unmanaged_TSS_Singleton<TYPE, ACE_LOCK> *singleton_;
00232 #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */
00233 
00234   /// Get pointer to the Singleton instance.
00235   static ACE_Unmanaged_TSS_Singleton<TYPE, ACE_LOCK> *&instance_i (void);
00236 };
00237 
00238 /**
00239  * @class ACE_DLL_Singleton_T
00240  *
00241  * @brief Same as ACE_Singleton, except that it registers for
00242  * destruction with the ACE_Framework_Repository instead of
00243  * with the ACE_Object_Manager directly.
00244  *
00245  * This version of ACE_Singleton should be used for singletons
00246  * that live in a dll loaded either directly by ACE_DLL or indirectly
00247  * by the ACE Service Configuration framework.  Whenever ACE_DLL is ready
00248  * to actually unload the dll, ACE_DLL_Singleton based dlls associated
00249  * with that dll will be destroyed first.  In fact, any singleton can
00250  * safely use ACE_DLL_Singleton, even those that don't live in dlls.  In
00251  * that case, the singleton will be destroyed at normal program shutdown.
00252  *
00253  * The only additional requirement is that the contained class
00254  * export name() and dll_name() methods.  See ACE_DLL_Singleton_Adapter_T
00255  * below for a convenient example of how to satisfy this
00256  * requirement for the dll_name().
00257  *
00258  * Usage is the same as for ACE_Singleton, but note that if you
00259  * you declare a friend, the friend class must still be an
00260  * *ACE_Singleton*<T, [ACE_LOCK]>, not an ACE_Unmanaged_Singleton.
00261  */
00262 template <class TYPE, class ACE_LOCK>
00263 class ACE_DLL_Singleton_T
00264 {
00265 public:
00266   //void cleanup (void *param = 0);
00267 
00268   /// Global access point to the Singleton.
00269   static TYPE *instance (void);
00270 
00271   /// Explicitly delete the Singleton instance.
00272   static void close (void);
00273 
00274   static void close_singleton (void);
00275 
00276   /// Dump the state of the object.
00277   static void dump (void);
00278 
00279   const ACE_TCHAR *dll_name (void);
00280 
00281   const ACE_TCHAR *name (void);
00282 
00283 protected:
00284   /// Default constructor.
00285   ACE_DLL_Singleton_T (void);
00286 
00287   /// Destructor.
00288   ~ACE_DLL_Singleton_T (void);
00289 
00290   /// Contained instance.
00291   TYPE instance_;
00292 
00293 #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES)
00294   /// Pointer to the Singleton instance.
00295   static ACE_DLL_Singleton_T<TYPE, ACE_LOCK> *singleton_;
00296 #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */
00297 
00298   /// Get pointer to the singleton instance.
00299   static ACE_DLL_Singleton_T<TYPE, ACE_LOCK> *&instance_i (void);
00300 };
00301 
00302 template <class TYPE>
00303 class ACE_DLL_Singleton_Adapter_T : public TYPE
00304 {
00305 public:
00306   const ACE_TCHAR *dll_name (void);
00307 };
00308 
00309 #if defined (__ACE_INLINE__)
00310 #include "ace/Singleton.i"
00311 #endif /* __ACE_INLINE__ */
00312 
00313 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
00314 #include "ace/Singleton.cpp"
00315 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
00316 
00317 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
00318 #pragma implementation ("Singleton.cpp")
00319 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
00320 
00321 #include "ace/post.h"
00322 #endif /* ACE_SINGLETON_H */

Generated on Mon Jun 16 11:21:17 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002