LCOV - code coverage report
Current view: top level - include/salhelper - singletonref.hxx (source / functions) Hit Total Coverage
Test: commit e02a6cb2c3e2b23b203b422e4e0680877f232636 Lines: 23 26 88.5 %
Date: 2014-04-14 Functions: 5 36 13.9 %
Legend: Lines: hit not hit

          Line data    Source code
       1             : /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
       2             : /*
       3             :  * This file is part of the LibreOffice project.
       4             :  *
       5             :  * This Source Code Form is subject to the terms of the Mozilla Public
       6             :  * License, v. 2.0. If a copy of the MPL was not distributed with this
       7             :  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
       8             :  *
       9             :  * This file incorporates work covered by the following license notice:
      10             :  *
      11             :  *   Licensed to the Apache Software Foundation (ASF) under one or more
      12             :  *   contributor license agreements. See the NOTICE file distributed
      13             :  *   with this work for additional information regarding copyright
      14             :  *   ownership. The ASF licenses this file to you under the Apache
      15             :  *   License, Version 2.0 (the "License"); you may not use this file
      16             :  *   except in compliance with the License. You may obtain a copy of
      17             :  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
      18             :  */
      19             : 
      20             : #ifndef INCLUDED_SALHELPER_SINGLETONREF_HXX
      21             : #define INCLUDED_SALHELPER_SINGLETONREF_HXX
      22             : 
      23             : #include <osl/mutex.hxx>
      24             : #include <rtl/instance.hxx>
      25             : #include <osl/diagnose.h>
      26             : #include <osl/getglobalmutex.hxx>
      27             : 
      28             : 
      29             : namespace salhelper{
      30             : 
      31             : 
      32             : /** @short  template for implementing singleton classes.
      33             : 
      34             :             Such classes can be instanciated every time they
      35             :             are needed. But the internal wrapped object will
      36             :             be created one times only. Of course its used
      37             :             resources are referenced one times only too.
      38             :             This template hold it alive till the last
      39             :             reference is gone. Further all operations
      40             :             on this reference are threadsafe. Only
      41             :             calls directly to the internal object (which modify
      42             :             its state) must be made threadsafe by the object itself
      43             :             or from outside.
      44             : 
      45             :     @attention  To prevent the code against race conditions, its not
      46             :                 allowed to start operations inside the ctor
      47             :                 of the internal wrapped object - especialy operations
      48             :                 which needs a reference to the same singleton too.
      49             : 
      50             :                 The only chance to supress such strange constellations
      51             :                 is a lazy-init mechanism.
      52             : 
      53             :                 <ul>
      54             :                     <li>a) The singleton class can provide a special init()
      55             :                            method, which must be called as first after creation.</li>
      56             :                     <li>b) The singleton class can call a special impl_init()
      57             :                            method implicit for every called interface method.</li>
      58             :                 </ul>
      59             : 
      60             :                 Note further that this singleton pattern can work only, if
      61             :                 all user of such singleton are located inside the same library!
      62             :                 Because static values cant be exported - e.g. from windows libraries.
      63             :  */
      64             : template< class SingletonClass >
      65             : class SingletonRef
      66             : {
      67             : 
      68             :     // member
      69             : 
      70             :     private :
      71             : 
      72             :         /** @short  pointer to the internal wrapped singleton. */
      73             :         static SingletonClass* m_pInstance;
      74             : 
      75             :         /** @short  ref count, which regulate creation and removing of m_pInstance. */
      76             :         static sal_Int32 m_nRef;
      77             : 
      78             : 
      79             :     // interface
      80             : 
      81             :     public :
      82             : 
      83             : 
      84             : 
      85             :         /** @short  standard ctor.
      86             : 
      87             :                     The internal wrapped object is created only,
      88             :                     if its ref count was 0. Otherwise this method
      89             :                     does nothing ... except increasing of the internal
      90             :                     ref count!
      91             :          */
      92           1 :         SingletonRef()
      93             :         {
      94             :             // GLOBAL SAFE ->
      95           1 :             ::osl::MutexGuard aLock(SingletonRef::ownStaticLock());
      96             : 
      97             :             // must be increased before(!) the check is done.
      98             :             // Otherwise this check can fail inside the same thread ...
      99           1 :             ++m_nRef;
     100           1 :             if (m_nRef == 1)
     101           1 :                 m_pInstance = new SingletonClass();
     102             : 
     103           1 :             OSL_ENSURE(m_nRef>0 && m_pInstance, "Race? Ref count of singleton >0, but instance is NULL!");
     104             :             // <- GLOBAL SAFE
     105           1 :         }
     106             : 
     107             : 
     108             : 
     109             :         /** @short  standard dtor.
     110             : 
     111             :                     The internal wrapped object is removed only,
     112             :                     if its ref count wil be 0. Otherwise this method
     113             :                     does nothing ... except decreasing of the internal
     114             :                     ref count!
     115             :          */
     116           1 :         ~SingletonRef()
     117             :         {
     118             :             // GLOBAL SAFE ->
     119           1 :             ::osl::MutexGuard aLock(SingletonRef::ownStaticLock());
     120             : 
     121             :             // must be decreased before(!) the check is done.
     122             :             // Otherwise this check can fail inside the same thread ...
     123           1 :             --m_nRef;
     124           1 :             if (m_nRef == 0)
     125             :             {
     126           1 :                 delete m_pInstance;
     127           1 :                 m_pInstance = 0;
     128           1 :             }
     129             :             // <- GLOBAL SAFE
     130           1 :         }
     131             : 
     132             : 
     133             : 
     134             :         /** @short  Allows rSingle->someBodyOp().
     135             :          */
     136           1 :         SingletonClass* operator->() const
     137             :         {
     138             :             // GLOBAL SAFE ->
     139           1 :             ::osl::MutexGuard aLock(SingletonRef::ownStaticLock());
     140           1 :             return m_pInstance;
     141             :             // <- GLOBAL SAFE
     142             :         }
     143             : 
     144             : 
     145             : 
     146             :         /** @short  Allows (*rSingle).someBodyOp().
     147             :          */
     148           0 :         SingletonClass& operator*() const
     149             :         {
     150             :             // GLOBAL SAFE ->
     151           0 :             ::osl::MutexGuard aLock(SingletonRef::ownStaticLock());
     152           0 :             return *m_pInstance;
     153             :             // <- GLOBAL SAFE
     154             :         }
     155             : 
     156             : 
     157             :     // helper
     158             : 
     159             :     private :
     160             : 
     161             : 
     162             : 
     163             :         /** @short  creates an own mutex for guarding static contents.
     164             : 
     165             :                     The global mutex the osl library is used one times
     166             :                     only to create an own static mutex, which can be used
     167             :                     next time to guard own static member operations.
     168             :          */
     169             :         struct SingletonLockInit
     170             :         {
     171           1 :             ::osl::Mutex* operator()()
     172             :             {
     173           1 :                 static ::osl::Mutex aInstance;
     174           1 :                 return &aInstance;
     175             :             }
     176             :         };
     177             : 
     178           3 :         ::osl::Mutex& ownStaticLock() const
     179             :         {
     180             :             return *rtl_Instance< ::osl::Mutex,
     181             :                                   SingletonLockInit,
     182             :                                   ::osl::MutexGuard,
     183           3 :                                   ::osl::GetGlobalMutex >::create(SingletonLockInit(), ::osl::GetGlobalMutex());
     184             :         }
     185             : };
     186             : 
     187             : template< class SingletonClass >
     188             : SingletonClass* SingletonRef< SingletonClass >::m_pInstance = 0;
     189             : 
     190             : template< class SingletonClass >
     191             : sal_Int32 SingletonRef< SingletonClass >::m_nRef = 0;
     192             : 
     193             : } // namespace salhelper
     194             : 
     195             : #endif // INCLUDED_SALHELPER_SINGLETONREF_HXX
     196             : 
     197             : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */

Generated by: LCOV version 1.10