---

ACE_Singleton Class Template Reference

A Singleton Adapter uses the Adapter pattern to turn ordinary classes into Singletons optimized with the Double-Checked Locking optimization pattern. More...

#include <Singleton.h>

Inheritance diagram for ACE_Singleton:

[legend]Collaboration diagram for ACE_Singleton:

[legend]List of all members.

Public Methods
virtual void	cleanup (void *param=0)
	Cleanup method, used by <ace_cleanup_destroyer> to destroy the ACE_Singleton. More...
Static Public Methods
TYPE *	instance (void)
	Global access point to the Singleton. More...
void	dump (void)
	Dump the state of the object. More...
Protected Methods
	ACE_Singleton (void)
	Default constructor. More...
Static Protected Methods
ACE_Singleton< TYPE, ACE_LOCK > *&	instance_i (void)
	Get pointer to the Singleton instance. More...
Protected Attributes
TYPE	instance_
	Contained instance. More...
Static Protected Attributes
ACE_Singleton< TYPE, ACE_LOCK > *	singleton_ = 0
	Pointer to the Singleton (ACE_Cleanup) instance. More...

---

Detailed Description

template<class TYPE, class ACE_LOCK>
class ACE_Singleton< TYPE, ACE_LOCK >

A Singleton Adapter uses the Adapter pattern to turn ordinary classes into Singletons optimized with the Double-Checked Locking optimization pattern.

This implementation is a slight variation on the GoF Singleton pattern. In particular, a single <ACE_Singleton<TYPE, ACE_LOCK> > instance is allocated here, not a <TYPE> instance. The reason for this is to allow registration with the ACE_Object_Manager, so that the Singleton can be cleaned up when the process exits. For this scheme to work, a (static) cleanup() function must be provided. ACE_Singleton provides one so that TYPE doesn't need to. If you want to make sure that only the singleton instance of <T> is created, and that users cannot create their own instances of <T>, do the following to class <T>: (a) Make the constructor of <T> private (or protected) (b) Make Singleton a friend of <T> Here is an example:

 * class foo
 * {
 * friend class ACE_Singleton<foo, ACE_Null_Mutex>;
 * private:
 * foo () { cout << "foo constructed" << endl; }
 * ~foo () { cout << "foo destroyed" << endl; }
 * };
 * typedef ACE_Singleton<foo, ACE_Null_Mutex> FOO;
 * 

NOTE: the best types to use for ACE_LOCK are ACE_Recursive_Thread_Mutex and ACE_Null_Mutex. ACE_Recursive_Thread_Mutex should be used in multi-threaded programs in which it is possible for more than one thread to access the <ACE_Singleton<TYPE, ACE_LOCK>> instance. ACE_Null_Mutex can be used otherwise. The reason that these types of locks are best has to do with their allocation by the ACE_Object_Manager. Single ACE_Recursive_Thread_Mutex and ACE_Null_Mutex instances are used for all ACE_Singleton instantiations. However, other types of locks are allocated per ACE_Singleton instantiation.

Definition at line 76 of file Singleton.h.

---

Constructor & Destructor Documentation

template<class TYPE, class ACE_LOCK> ACE_INLINE ACE_Singleton< TYPE, ACE_LOCK >::ACE_Singleton (  void    )  [protected]

Default constructor. Definition at line 10 of file Singleton.i. { }

---

Member Function Documentation

template<class TYPE, class ACE_LOCK> void ACE_Singleton< TYPE, ACE_LOCK >::cleanup (  void *    param = 0 )  [virtual]

Cleanup method, used by <ace_cleanup_destroyer> to destroy the ACE_Singleton. Reimplemented from ACE_Cleanup. Definition at line 104 of file Singleton.cpp. References instance_i. Referenced by ACE_Unmanaged_Singleton::close. { delete this; ACE_Singleton<TYPE, ACE_LOCK>::instance_i () = 0; }

template<class TYPE, class ACE_LOCK> void ACE_Singleton< TYPE, ACE_LOCK >::dump (  void    )  [static]

Dump the state of the object. Reimplemented in ACE_Unmanaged_Singleton. Definition at line 26 of file Singleton.cpp. References ACE_DEBUG, ACE_END_DUMP, ACE_LIB_TEXT, ACE_TRACE, instance_i, and LM_DEBUG. { ACE_TRACE ("ACE_Singleton<TYPE, ACE_LOCK>::dump"); #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES) ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("instance_ = %x"), ACE_Singleton<TYPE, ACE_LOCK>::instance_i ())); ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP)); #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */ }

template<class TYPE, class ACE_LOCK> TYPE * ACE_Singleton< TYPE, ACE_LOCK >::instance (  void    )  [static]

Global access point to the Singleton. Reimplemented in ACE_Unmanaged_Singleton. Definition at line 52 of file Singleton.cpp. References ACE_GUARD_RETURN, ACE_NEW_RETURN, ACE_TRACE, ACE_Object_Manager::at_exit, instance_, instance_i, ACE_Object_Manager::shutting_down, and ACE_Object_Manager::starting_up. Referenced by ACE_Based_Pointer_Basic::ACE_Based_Pointer_Basic, ACE_Remote_Token_Proxy::initiate_connection, ACE_Pagefile_Memory_Pool::map, ACE_MMAP_Memory_Pool::map_file, ACE_MMAP_Memory_Pool::release, ACE_Remote_Token_Proxy::request_reply, ACE_Remote_Token_Proxy::set_server_address, and ACE_Pagefile_Memory_Pool::unmap. { ACE_TRACE ("ACE_Singleton<TYPE, ACE_LOCK>::instance"); ACE_Singleton<TYPE, ACE_LOCK> *&singleton = ACE_Singleton<TYPE, ACE_LOCK>::instance_i (); // Perform the Double-Check pattern... if (singleton == 0) { if (ACE_Object_Manager::starting_up () || ACE_Object_Manager::shutting_down ()) { // The program is still starting up, and therefore assumed // to be single threaded. There's no need to double-check. // Or, the ACE_Object_Manager instance has been destroyed, // so the preallocated lock is not available. Either way, // don't register for destruction with the // ACE_Object_Manager: we'll have to leak this instance. ACE_NEW_RETURN (singleton, (ACE_Singleton<TYPE, ACE_LOCK>), 0); } else { #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) // Obtain a lock from the ACE_Object_Manager. The pointer // is static, so we only obtain one per ACE_Singleton // instantiation. static ACE_LOCK *lock = 0; if (ACE_Object_Manager::get_singleton_lock (lock) != 0) // Failed to acquire the lock! return 0; ACE_GUARD_RETURN (ACE_LOCK, ace_mon, *lock, 0); if (singleton == 0) { #endif /* ACE_MT_SAFE */ ACE_NEW_RETURN (singleton, (ACE_Singleton<TYPE, ACE_LOCK>), 0); // Register for destruction with ACE_Object_Manager. ACE_Object_Manager::at_exit (singleton); #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) } #endif /* ACE_MT_SAFE */ } } return &singleton->instance_; }

template<class TYPE, class ACE_LOCK> ACE_Singleton< TYPE, ACE_LOCK > *& ACE_Singleton< TYPE, ACE_LOCK >::instance_i (  void    )  [static, protected]

Get pointer to the Singleton instance. Reimplemented in ACE_Unmanaged_Singleton. Definition at line 38 of file Singleton.cpp. References singleton_. Referenced by cleanup, dump, and instance. { #if defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES) // Pointer to the Singleton instance. This works around a bug with // G++ and it's (mis-)handling of templates and statics... static ACE_Singleton<TYPE, ACE_LOCK> *singleton_ = 0; return singleton_; #else return ACE_Singleton<TYPE, ACE_LOCK>::singleton_; #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */ }

---

Member Data Documentation

template<class TYPE, class ACE_LOCK> TYPE ACE_Singleton::instance_ [protected]

Contained instance. Definition at line 94 of file Singleton.h. Referenced by ACE_Unmanaged_Singleton::instance, and instance.

template<class TYPE, class ACE_LOCK> ACE_Singleton< TYPE, ACE_LOCK > * ACE_Singleton< TYPE, ACE_LOCK >::singleton_ = 0 [static, protected]

Pointer to the Singleton (ACE_Cleanup) instance. Reimplemented in ACE_Unmanaged_Singleton. Definition at line 113 of file Singleton.cpp. Referenced by instance_i.

---

The documentation for this class was generated from the following files:

• Singleton.h
• Singleton.cpp
• Singleton.i

---