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 <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 instantiated 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 - especially operations
  48                 which needs a reference to the same singleton too.
  49
  50                 The only chance to suppress 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 can't 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         SingletonRef()
  93         {
  94             // GLOBAL SAFE ->
  95             ::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             ++m_nRef;
 100             if (m_nRef == 1)
 101                 m_pInstance = new SingletonClass();
 102
 103             OSL_ENSURE(m_nRef>0 && m_pInstance, "Race? Ref count of singleton >0, but instance is NULL!");
 104             // <- GLOBAL SAFE
 105         }
 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         ~SingletonRef()
 117         {
 118             // GLOBAL SAFE ->
 119             ::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             --m_nRef;
 124             if (m_nRef == 0)
 125             {
 126                 delete m_pInstance;
 127                 m_pInstance = 0;
 128             }
 129             // <- GLOBAL SAFE
 130         }
 131
 132
 133
 134         /** @short  Allows rSingle->someBodyOp().
 135          */
 136         SingletonClass* operator->() const
 137         {
 138             // GLOBAL SAFE ->
 139             ::osl::MutexGuard aLock(SingletonRef::ownStaticLock());
 140             return m_pInstance;
 141             // <- GLOBAL SAFE
 142         }
 143
 144
 145
 146         /** @short  Allows (*rSingle).someBodyOp().
 147          */
 148         SingletonClass& operator*() const
 149         {
 150             // GLOBAL SAFE ->
 151             ::osl::MutexGuard aLock(SingletonRef::ownStaticLock());
 152             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             ::osl::Mutex* operator()()
 172             {
 173                 static ::osl::Mutex aInstance;
 174                 return &aInstance;
 175             }
 176         };
 177
 178         ::osl::Mutex& ownStaticLock() const
 179         {
 180             return *rtl_Instance< ::osl::Mutex,
 181                                   SingletonLockInit,
 182                                   ::osl::MutexGuard,
 183                                   ::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: */