include/salhelper/singletonref.hxx

   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 "sal/config.h"
  24
  25 #include <cstddef>
  26
  27 #include "osl/mutex.hxx"
  28 #include "rtl/instance.hxx"
  29 #include "osl/diagnose.h"
  30 #include "osl/getglobalmutex.hxx"
  31
  32
  33 namespace salhelper{
  34
  35
  36 /** @short  template for implementing singleton classes.
  37
  38             Such classes can be instantiated every time they
  39             are needed. But the internal wrapped object will
  40             be created one times only. Of course it's used
  41             resources are referenced one times only too.
  42             This template hold it alive till the last
  43             reference is gone. Further all operations
  44             on this reference are threadsafe. Only
  45             calls directly to the internal object (which modify
  46             its state) must be made threadsafe by the object itself
  47             or from outside.
  48
  49     @attention  To prevent the code against race conditions, it's not
  50                 allowed to start operations inside the ctor
  51                 of the internal wrapped object - especially operations
  52                 which needs a reference to the same singleton too.
  53
  54                 The only chance to suppress such strange constellations
  55                 is a lazy-init mechanism.
  56
  57                 <ul>
  58                     <li>a) The singleton class can provide a special init()
  59                            method, which must be called as first after creation.</li>
  60                     <li>b) The singleton class can call a special impl_init()
  61                            method implicit for every called interface method.</li>
  62                 </ul>
  63
  64                 Note further that this singleton pattern can work only, if
  65                 all user of such singleton are located inside the same library!
  66                 Because static values can't be exported - e.g. from windows libraries.
  67  */
  68 template< class SingletonClass >
  69 class SingletonRef
  70 {
  71
  72     // member
  73
  74     private:
  75
  76         /** @short  pointer to the internal wrapped singleton. */
  77         static SingletonClass* m_pInstance;
  78
  79         /** @short  ref count, which regulate creation and removing of m_pInstance. */
  80         static sal_Int32 m_nRef;
  81
  82
  83     // interface
  84
  85     public:
  86
  87
  88         /** @short  standard ctor.
  89
  90                     The internal wrapped object is created only,
  91                     if its ref count was 0. Otherwise this method
  92                     does nothing ... except increasing of the internal
  93                     ref count!
  94          */
  95         SingletonRef()
  96         {
  97             // GLOBAL SAFE ->
  98             ::osl::MutexGuard aLock(SingletonRef::ownStaticLock());
  99
 100             // must be increased before(!) the check is done.
 101             // Otherwise this check can fail inside the same thread ...
 102             ++m_nRef;
 103             if (m_nRef == 1)
 104                 m_pInstance = new SingletonClass();
 105
 106             OSL_ENSURE(m_nRef>0 && m_pInstance, "Race? Ref count of singleton >0, but instance is NULL!");
 107             // <- GLOBAL SAFE
 108         }
 109
 110
 111         /** @short  standard dtor.
 112
 113                     The internal wrapped object is removed only,
 114                     if its ref count will be 0. Otherwise this method
 115                     does nothing ... except decreasing of the internal
 116                     ref count!
 117          */
 118         ~SingletonRef()
 119         {
 120             // GLOBAL SAFE ->
 121             ::osl::MutexGuard aLock(SingletonRef::ownStaticLock());
 122
 123             // must be decreased before(!) the check is done.
 124             // Otherwise this check can fail inside the same thread ...
 125             --m_nRef;
 126             if (m_nRef == 0)
 127             {
 128                 delete m_pInstance;
 129                 m_pInstance = NULL;
 130             }
 131             // <- GLOBAL SAFE
 132         }
 133
 134 #if defined LIBO_INTERNAL_ONLY
 135         SingletonRef & operator =(SingletonRef const &) = default;
 136 #endif
 137
 138         /** @short  Allows rSingle->someBodyOp().
 139          */
 140         SingletonClass* operator->() const
 141         {
 142             // GLOBAL SAFE ->
 143             ::osl::MutexGuard aLock(SingletonRef::ownStaticLock());
 144             return m_pInstance;
 145             // <- GLOBAL SAFE
 146         }
 147
 148
 149         /** @short  Allows (*rSingle).someBodyOp().
 150          */
 151         SingletonClass& operator*() const
 152         {
 153             // GLOBAL SAFE ->
 154             ::osl::MutexGuard aLock(SingletonRef::ownStaticLock());
 155             return *m_pInstance;
 156             // <- GLOBAL SAFE
 157         }
 158
 159
 160     // helper
 161
 162     private:
 163         SingletonRef(SingletonRef &) SAL_DELETED_FUNCTION;
 164
 165         /** @short  creates an own mutex for guarding static contents.
 166
 167                     The global mutex the osl library is used one times
 168                     only to create an own static mutex, which can be used
 169                     next time to guard own static member operations.
 170          */
 171         struct SingletonLockInit
 172         {
 173             ::osl::Mutex* operator()()
 174             {
 175                 static ::osl::Mutex aInstance;
 176                 return &aInstance;
 177             }
 178         };
 179
 180         ::osl::Mutex& ownStaticLock() const
 181         {
 182             return *rtl_Instance< ::osl::Mutex,
 183                                   SingletonLockInit,
 184                                   ::osl::MutexGuard,
 185                                   ::osl::GetGlobalMutex >::create(SingletonLockInit(), ::osl::GetGlobalMutex());
 186         }
 187 };
 188
 189 template< class SingletonClass >
 190 SingletonClass* SingletonRef< SingletonClass >::m_pInstance = NULL;
 191
 192 template< class SingletonClass >
 193 sal_Int32 SingletonRef< SingletonClass >::m_nRef = 0;
 194
 195 } // namespace salhelper
 196
 197 #endif // INCLUDED_SALHELPER_SINGLETONREF_HXX
 198
 199 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */