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