DOCUMENT:Q201321 28-JUN-2001 [visualc] TITLE :HOWTO: Alternative Implementation of ATL Singleton PRODUCT :Microsoft C Compiler PROD/VER:WINDOWS:3.0 OPER/SYS: KEYWORDS:kbActiveX kbCOMt kbVC600 kbATL300 kbGrpDSMFCATL kbArchitecture ====================================================================== ------------------------------------------------------------------------------- The information in this article applies to: - The Microsoft Active Template Library (ATL) 3.0, included with: - Microsoft Visual C++, 32-bit Enterprise Edition, version 6.0 - Microsoft Visual C++, 32-bit Professional Edition, version 6.0 - Microsoft Visual C++, 32-bit Learning Edition, version 6.0 ------------------------------------------------------------------------------- SUMMARY ======= This article shows an implementation of singletons that differs from the default ATL implementation in the following ways: - The lifetime of an ATL singleton is tied to the class factory; the singleton gets destroyed only when the class factory is destroyed, which is when the EXE/DLL unloads [CComModule::RevokeClassObject() and CComModule::Term()]. The singleton implementation in this article maintains a refcount and deletes itself when it goes to zero. - Implementing singletons in a DLL can be problematic. One scenario is if your singleton object marked "Apartment", is in a DLL. The client creates two STA threads, each one creates your singleton object. Both STA threads have the same raw pointer to your singleton, allowing them to simultaneously call into the singleton. You are probably not synchronizing access to instance data in your singleton object, because according to COM rules, you don't need to synchronize access to instance data for objects marked "Apartment". It's only a matter of time before data is corrupted. The singleton implementation in this article works around this problem by returning a marshaled pointer in IClassFactory::CreateInstance(). But marshaling the pointer introduces another potential problem. All calls are now marshaled to the first Apartment that calls IClassFactory::CreateInstance. If the first Apartment goes away, calls to the singleton from other Apartments will fail. If you use the singleton implementation in this article in a DLL marked "Apartment", you must ensure that the first Apartment that uses the component stays alive. Because of all these potential problems, you should only use singletons in a DLL when absolutely necessary. If you just want to share data in the DLL within the same process, an alternative is to create global/static variables to hold the data. You just need to synchronize access to this data. MORE INFORMATION ================ To use this version of a singleton, copy and paste the following into a header file in your project: /********** Start of singleton code **********/ template class CMyComObject: public CComObject { public: // Variable that lets class factory know COM object is deleted. CMyComObject** m_ppObj; STDMETHOD_(ULONG, Release)() { ULONG l = InternalRelease(); if (l == 0) { // Set to NULL so class factory knows to recreate us. *m_ppObj = NULL; delete this; } return l; } static HRESULT WINAPI CreateInstance(CMyComObject** pp) { ATLASSERT(pp != NULL); HRESULT hRes = E_OUTOFMEMORY; CMyComObject* p = NULL; ATLTRY(p = new CMyComObject()) if (p != NULL) { p->SetVoid(NULL); p->InternalFinalConstructAddRef(); hRes = p->FinalConstruct(); p->InternalFinalConstructRelease(); if (hRes != S_OK) { delete p; p = NULL; } } *pp = p; // Initialize m_ppObj to CComObject<> pointer in class factory. p->m_ppObj = pp; return hRes; } }; template class CMyComClassFactorySingleton : public CComClassFactory { public: CMyComObject* m_pObj; // actual COM object CComAutoCriticalSection m_sec; // A critical section is needed // because class factory is stored in CComObjectCached. All clients // get the same raw pointer to the class factory. Any instance // data in this class factory must be synchronized. // IClassFactory STDMETHOD(CreateInstance)(LPUNKNOWN pUnkOuter, REFIID riid, void** ppvObj) { if (NULL == ppvObj) return E_POINTER; *ppvObj = NULL; // Aggregation is not supported in Singletons. ATLASSERT(pUnkOuter == NULL); if (pUnkOuter != NULL) return CLASS_E_NOAGGREGATION; HRESULT hRes = E_FAIL; // Lock critical section. m_sec.Lock(); // Create COM object. if (NULL == m_pObj) { hRes = CMyComObject::CreateInstance(&m_pObj); if (SUCCEEDED(hRes)) { // Free marshaled interface and release stream. if (m_pStream) { AtlFreeMarshalStream(m_pStream); m_pStream = NULL; } // Marshal interface into a stream. // Can't use AtlMarshalPtrInProc since we need to use // MSHLFLAGS_TABLEWEAK. hRes = CreateStreamOnHGlobal(NULL, TRUE, &m_pStream); if (SUCCEEDED(hRes)) { hRes = CoMarshalInterface(m_pStream, IID_IUnknown, m_pObj, MSHCTX_INPROC, NULL, MSHLFLAGS_TABLEWEAK); if (FAILED(hRes)) { m_pStream->Release(); m_pStream = NULL; } } } if (FAILED(hRes)) { // Unlock critical section. m_sec.Unlock(); return hRes; } } CComPtr spUnk; // Unmarshal interface from stream. hRes = AtlUnmarshalPtr(m_pStream, IID_IUnknown, &spUnk); // unlock critical section m_sec.Unlock(); if (FAILED (hRes)) return hRes; // Call QI on unmarshaled interface. hRes = spUnk->QueryInterface(riid, ppvObj); return hRes; } LPSTREAM m_pStream; // IStream* used for storing marshaled interface. void FinalRelease() { // Free marshaled interface and release stream. if (m_pStream) AtlFreeMarshalStream (m_pStream); } CMyComClassFactorySingleton() : m_pObj(NULL), m_pStream(NULL) { } }; #define DECLARE_CLASSFACTORY_MYSINGLETON(obj) DECLARE_CLASSFACTORY_EX(CMyComClassFactorySingleton) /********** End of singleton code **********/ Instead of DECLARE_CLASSFACTORY_SINGLETON, use the DECLARE_CLASSFACTORY_MYSINGLETON() macro in your CComCoClass-derived class: class CMyComponent : public CComCoClass<...>, ... { DECLARE_CLASSFACTORY_MYSINGLETON(CMyComponent) ... } REFERENCES ========== (c) Microsoft Corporation 1999, All Rights Reserved. Contributions by Samson Tanrena, Microsoft Corporation. Additional query words: kbDSupport CComObjectGlobal CComObjectNoLock CComObject single instance CComClassFactorySingleton ====================================================================== Keywords : kbActiveX kbCOMt kbVC600 kbATL300 kbGrpDSMFCATL kbArchitecture Technology : kbVCsearch kbAudDeveloper kbATLsearch Version : WINDOWS:3.0 Issue type : kbhowto ============================================================================= THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. Copyright Microsoft Corporation 2001.