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