Adding upstream version 4:24.2.0.upstream/4%24.2.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 643 insertions, 0 deletions

diff --git a/include/rtl/instance.hxx b/include/rtl/instance.hxx
new file mode 100644
index 0000000000..0d7d8f3fca
--- /dev/null
+++ b/include/rtl/instance.hxx
@@ -0,0 +1,643 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ *   Licensed to the Apache Software Foundation (ASF) under one or more
+ *   contributor license agreements. See the NOTICE file distributed
+ *   with this work for additional information regarding copyright
+ *   ownership. The ASF licenses this file to you under the Apache
+ *   License, Version 2.0 (the "License"); you may not use this file
+ *   except in compliance with the License. You may obtain a copy of
+ *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+/*
+ * This file is part of LibreOffice published API.
+ */
+
+#ifndef INCLUDED_RTL_INSTANCE_HXX
+#define INCLUDED_RTL_INSTANCE_HXX
+
+#include "sal/config.h"
+
+#include <cstddef>
+
+#include "osl/doublecheckedlocking.h"
+#include "osl/getglobalmutex.hxx"
+
+namespace {
+
+/** A non-broken version of the double-checked locking pattern.
+
+    See
+    <http://www.cs.umd.edu/~pugh/java/memoryModel/DoubleCheckedLocking.html>
+    for a description of double-checked locking, why it is broken, and how it
+    can be fixed.  Always use this template instead of spelling out the
+    double-checked locking pattern explicitly, and only in those rare cases
+    where that is not possible and you have to spell it out explicitly, at
+    least call OSL_DOUBLE_CHECKED_LOCKING_MEMORY_BARRIER() at the right
+    places.  That way, all platform-dependent code to make double-checked
+    locking work can be kept in one place.
+
+    Usage scenarios:
+
+    1  Static instance (most common case)
+
+    Pattern:
+
+      T * getInstance()
+      {
+          static T * pInstance = 0;
+          if (!pInstance)
+          {
+              ::osl::MutexGuard aGuard(::osl::Mutex::getGlobalMutex());
+              if (!pInstance)
+              {
+                  static T aInstance;
+                  pInstance = &aInstance;
+              }
+          }
+          return pInstance;
+      }
+
+    Code:
+
+      #include <rtl/instance.hxx>
+      #include <osl/getglobalmutex.hxx>
+
+      namespace {
+          struct Init
+          {
+              T * operator()()
+              {
+                  static T aInstance;
+                  return &aInstance;
+              }
+          };
+      }
+
+      T * getInstance()
+      {
+          return rtl_Instance< T, Init, ::osl::MutexGuard,
+                               ::osl::GetGlobalMutex >::create(
+              Init(), ::osl::GetGlobalMutex());
+      }
+
+    2  Dynamic instance
+
+    Pattern:
+
+      T * getInstance()
+      {
+          static T * pInstance = 0;
+          if (!pInstance)
+          {
+              ::osl::MutexGuard aGuard(::osl::Mutex::getGlobalMutex());
+              if (!pInstance)
+                  pInstance = new T;
+          }
+          return pInstance;
+      }
+
+    Code:
+
+      #include <rtl/instance.hxx>
+      #include <osl/getglobalmutex.hxx>
+
+      namespace {
+          struct Init
+          {
+              T * operator()()
+              {
+                  return new T;
+              }
+          };
+      }
+
+      T * getInstance()
+      {
+          return rtl_Instance< T, Init, ::osl::MutexGuard,
+                               ::osl::GetGlobalMutex >::create(
+              Init(), ::osl::GetGlobalMutex());
+      }
+
+    3  Other guard/mutex
+
+    Pattern:
+
+      T * getInstance()
+      {
+          static T * pInstance = 0;
+          if (!pInstance)
+          {
+              SomeGuard aGuard(pSomeMutex);
+              if (!pInstance)
+              {
+                  static T aInstance;
+                  pInstance = &aInstance;
+              }
+          }
+          return pInstance;
+      }
+
+    Code:
+
+      #include <rtl/instance.hxx>
+
+      namespace {
+          struct InitInstance
+          {
+              T * operator()()
+              {
+                  static T aInstance;
+                  return &aInstance;
+              }
+          };
+
+          struct InitGuard
+          {
+              SomeMutex * operator()()
+              {
+                  return pSomeMutex;
+              }
+          };
+      }
+
+      T * getInstance()
+      {
+          return rtl_Instance< T, InitInstance,
+                               SomeGuard, InitGuard >::create(
+              InitInstance(), InitMutex());
+      }
+
+    4  Calculate extra data
+
+    Pattern:
+
+      T * getInstance()
+      {
+          static T * pInstance = 0;
+          if (!pInstance)
+          {
+              Data aData(...);
+              ::osl::MutexGuard aGuard(::osl::Mutex::getGlobalMutex());
+              if (!pInstance)
+              {
+                  static T aInstance(aData);
+                  pInstance = &aInstance;
+              }
+          }
+          return pInstance;
+      }
+
+    Code:
+
+      #include <rtl/instance.hxx>
+      #include <osl/getglobalmutex.hxx>
+
+      namespace {
+          struct InitInstance
+          {
+              T * operator()()
+              {
+                  static T aInstance;
+                  return &aInstance;
+              }
+          }
+
+          struct InitData
+          {
+              Data const & operator()()
+              {
+                  return ...;
+              }
+          }
+      }
+
+      T * getInstance()
+      {
+          return rtl_Instance< T, InitInstance,
+                               ::osl::MutexGuard, ::osl::GetGlobalMutex,
+                               Data, InitData >::create(
+              InitInstance(), ::osl::GetGlobalMutex(), InitData());
+      }
+
+    Some comments:
+
+    For any instantiation of rtl_Instance, at most one call to a create method
+    may occur in the program code:  Each occurrence of a create method within
+    the program code is supposed to return a fresh object instance on the
+    first call, and that same object instance on subsequent calls; but
+    independent occurrences of create methods are supposed to return
+    independent object instances.  Since there is a one-to-one correspondence
+    between object instances and instantiations of rtl_Instance, the
+    requirement should be clear.  One measure to enforce the requirement is
+    that rtl_Instance lives in an unnamed namespace, so that instantiations of
+    rtl_Instance in different translation units will definitely be different
+    instantiations.  A drawback of that measure is that the name of the class
+    needs a funny "hand coded" prefix "rtl_" instead of a proper namespace
+    prefix like "::rtl::".
+
+    A known problem with this template is when two occurrences of calls to
+    create methods with identical template arguments appear in one translation
+    unit.  Those two places will share a single object instance.  This can be
+    avoided by using different Init structs (see the above code samples) in
+    the two places.
+
+    There is no need to make m_pInstance volatile, in order to avoid usage of
+    stale copies of m_pInstance:  At the first check, a thread will see that
+    m_pInstance contains either 0 or a valid pointer.  If it contains a valid
+    pointer, it cannot be stale, and that pointer is used.  If it contains 0,
+    acquiring the mutex will ensure that the second check sees a non-stale
+    value in all cases.
+
+    On some compilers, the create methods would not be inlined if they
+    contained any static variables, so m_pInstance is made a class member
+    instead (and the create methods are inlined).  But on MSC, the definition
+    of the class member m_pInstance would cause compilation to fail with an
+    internal compiler error.  Since MSC is able to inline methods containing
+    static variables, m_pInstance is moved into the methods there.  Note that
+    this only works well because for any instantiation of rtl_Instance at most
+    one call to a create method should be present, anyway.
+ */
+template< typename Inst, typename InstCtor,
+          typename Guard, typename GuardCtor,
+          typename Data = int, typename DataCtor = int >
+class rtl_Instance
+{
+public:
+    static Inst * create(InstCtor aInstCtor, GuardCtor aGuardCtor)
+    {
+#if defined _MSC_VER
+        static Inst * m_pInstance = NULL;
+#endif // _MSC_VER
+        Inst * p = m_pInstance;
+        if (!p)
+        {
+            Guard aGuard(aGuardCtor());
+            p = m_pInstance;
+            if (!p)
+            {
+                p = aInstCtor();
+                OSL_DOUBLE_CHECKED_LOCKING_MEMORY_BARRIER();
+                m_pInstance = p;
+            }
+        }
+        else
+        {
+            OSL_DOUBLE_CHECKED_LOCKING_MEMORY_BARRIER();
+        }
+        return p;
+    }
+
+    static Inst * create(InstCtor aInstCtor, GuardCtor aGuardCtor,
+                                DataCtor aDataCtor)
+    {
+#if defined _MSC_VER
+        static Inst * m_pInstance = NULL;
+#endif // _MSC_VER
+        Inst * p = m_pInstance;
+        if (!p)
+        {
+            Data aData(aDataCtor());
+            Guard aGuard(aGuardCtor());
+            p = m_pInstance;
+            if (!p)
+            {
+                p = aInstCtor(aData);
+                OSL_DOUBLE_CHECKED_LOCKING_MEMORY_BARRIER();
+                m_pInstance = p;
+            }
+        }
+        else
+        {
+            OSL_DOUBLE_CHECKED_LOCKING_MEMORY_BARRIER();
+        }
+        return p;
+    }
+
+    static Inst * create(InstCtor aInstCtor, GuardCtor aGuardCtor,
+                                const Data &rData)
+    {
+#if defined _MSC_VER
+        static Inst * m_pInstance = 0;
+#endif // _MSC_VER
+        Inst * p = m_pInstance;
+        if (!p)
+        {
+            Guard aGuard(aGuardCtor());
+            p = m_pInstance;
+            if (!p)
+            {
+                p = aInstCtor(rData);
+                OSL_DOUBLE_CHECKED_LOCKING_MEMORY_BARRIER();
+                m_pInstance = p;
+            }
+        }
+        else
+        {
+            OSL_DOUBLE_CHECKED_LOCKING_MEMORY_BARRIER();
+        }
+        return p;
+    }
+
+private:
+#if !defined _MSC_VER
+    static Inst * m_pInstance;
+#endif // _MSC_VER
+};
+
+#if !defined _MSC_VER
+template< typename Inst, typename InstCtor,
+          typename Guard, typename GuardCtor,
+          typename Data, typename DataCtor >
+Inst *
+rtl_Instance< Inst, InstCtor, Guard, GuardCtor, Data, DataCtor >::m_pInstance
+= NULL;
+#endif // _MSC_VER
+
+}
+
+namespace rtl {
+
+/** Helper base class for a late-initialized (default-constructed)
+    static variable, implementing the double-checked locking pattern correctly.
+
+    @derive
+    Derive from this class (common practice), e.g.
+    <pre>
+    struct MyStatic : public rtl::Static<MyType, MyStatic> {};
+    ...
+    MyType & rStatic = MyStatic::get();
+    ...
+    </pre>
+
+    @tparam T
+              variable's type
+    @tparam Unique
+              Implementation trick to make the inner static holder unique,
+              using the outer class
+              (the one that derives from this base class)
+*/
+#if defined LIBO_INTERNAL_ONLY
+template<typename T, typename Unique>
+class Static {
+public:
+    /** Gets the static.  Mutual exclusion is implied by a functional
+        -fthreadsafe-statics
+
+        @return
+                static variable
+    */
+    static T & get() {
+        static T instance;
+        return instance;
+    }
+};
+#else
+template<typename T, typename Unique>
+class Static {
+public:
+    /** Gets the static.  Mutual exclusion is performed using the
+        osl global mutex.
+
+        @return
+                static variable
+    */
+    static T & get() {
+        return *rtl_Instance<
+            T, StaticInstance,
+            ::osl::MutexGuard, ::osl::GetGlobalMutex >::create(
+                StaticInstance(), ::osl::GetGlobalMutex() );
+    }
+private:
+    struct StaticInstance {
+        T * operator () () {
+            static T instance;
+            return &instance;
+        }
+    };
+};
+#endif
+
+/** Helper base class for a late-initialized (default-constructed)
+    static variable, implementing the double-checked locking pattern correctly.
+
+    @derive
+    Derive from this class (common practice), e.g.
+    <pre>
+    struct MyStatic : public rtl::Static<MyType, MyStatic> {};
+    ...
+    MyType & rStatic = MyStatic::get();
+    ...
+    </pre>
+
+    @tparam T
+              variable's type
+    @tparam Unique
+              Implementation trick to make the inner static holder unique,
+              using the outer class
+              (the one that derives from this base class)
+*/
+#if defined LIBO_INTERNAL_ONLY
+template<typename T, typename Data, typename Unique>
+class StaticWithArg {
+public:
+    /** Gets the static.  Mutual exclusion is implied by a functional
+        -fthreadsafe-statics
+
+        @return
+                static variable
+    */
+    static T & get(const Data& rData) {
+        static T instance(rData);
+        return instance;
+    }
+
+    /** Gets the static.  Mutual exclusion is implied by a functional
+        -fthreadsafe-statics
+
+        @return
+                static variable
+    */
+    static T & get(Data& rData) {
+        static T instance(rData);
+        return instance;
+    }
+};
+#else
+template<typename T, typename Data, typename Unique>
+class StaticWithArg {
+public:
+    /** Gets the static.  Mutual exclusion is performed using the
+        osl global mutex.
+
+        @return
+                static variable
+    */
+    static T & get(const Data& rData) {
+        return *rtl_Instance<
+            T, StaticInstanceWithArg,
+            ::osl::MutexGuard, ::osl::GetGlobalMutex,
+            Data >::create( StaticInstanceWithArg(),
+                                      ::osl::GetGlobalMutex(),
+                                      rData );
+    }
+
+    /** Gets the static.  Mutual exclusion is performed using the
+        osl global mutex.
+
+        @return
+                static variable
+    */
+    static T & get(Data& rData) {
+        return *rtl_Instance<
+            T, StaticInstanceWithArg,
+            ::osl::MutexGuard, ::osl::GetGlobalMutex,
+            Data >::create( StaticInstanceWithArg(),
+                                      ::osl::GetGlobalMutex(),
+                                      rData );
+    }
+private:
+    struct StaticInstanceWithArg {
+        T * operator () (const Data& rData) {
+            static T instance(rData);
+            return &instance;
+        }
+
+        T * operator () (Data& rData) {
+            static T instance(rData);
+            return &instance;
+         }
+    };
+};
+#endif
+
+/** Helper class for a late-initialized static aggregate, e.g. an array,
+    implementing the double-checked locking pattern correctly.
+
+    @tparam T
+              aggregate's element type
+    @tparam InitAggregate
+              initializer functor class
+*/
+#if defined LIBO_INTERNAL_ONLY
+template<typename T, typename InitAggregate>
+class StaticAggregate {
+public:
+    /** Gets the static aggregate, late-initializing.
+        Mutual exclusion is implied by a functional
+        -fthreadsafe-statics
+
+        @return
+                aggregate
+    */
+    static T * get() {
+        static T *instance = InitAggregate()();
+        return instance;
+    }
+};
+#else
+template<typename T, typename InitAggregate>
+class StaticAggregate {
+public:
+    /** Gets the static aggregate, late-initializing.
+        Mutual exclusion is performed using the osl global mutex.
+
+        @return
+                aggregate
+    */
+    static T * get() {
+        return rtl_Instance<
+            T, InitAggregate,
+            ::osl::MutexGuard, ::osl::GetGlobalMutex >::create(
+                InitAggregate(), ::osl::GetGlobalMutex() );
+    }
+};
+#endif
+/** Helper base class for a late-initialized static variable,
+    implementing the double-checked locking pattern correctly.
+
+    @derive
+    Derive from this class (common practice),
+    providing an initializer functor class, e.g.
+    <pre>
+    struct MyStatic : public rtl::StaticWithInit<MyType, MyStatic> {
+        MyType operator () () {
+            ...
+            return MyType( ... );
+        }
+    };
+    ...
+    MyType & rStatic = MyStatic::get();
+    ...
+    </pre>
+
+    @tparam T
+              variable's type
+    @tparam InitData
+              initializer functor class
+    @tparam Unique
+              Implementation trick to make the inner static holder unique,
+              using the outer class
+              (the one that derives from this base class).
+              Default is InitData (common practice).
+    @tparam Data
+              Initializer functor's return type.
+              Default is T (common practice).
+*/
+#if defined LIBO_INTERNAL_ONLY
+template<typename T, typename InitData,
+         typename Unique = InitData, typename Data = T>
+class StaticWithInit {
+public:
+    /** Gets the static.  Mutual exclusion is implied by a functional
+        -fthreadsafe-statics
+
+        @return
+                static variable
+    */
+    static T & get() {
+        static T instance = InitData()();
+        return instance;
+    }
+};
+#else
+template<typename T, typename InitData,
+         typename Unique = InitData, typename Data = T>
+class StaticWithInit {
+public:
+    /** Gets the static.  Mutual exclusion is performed using the
+        osl global mutex.
+
+        @return
+                static variable
+    */
+    static T & get() {
+        return *rtl_Instance<
+            T, StaticInstanceWithInit,
+            ::osl::MutexGuard, ::osl::GetGlobalMutex,
+            Data, InitData >::create( StaticInstanceWithInit(),
+                                      ::osl::GetGlobalMutex(),
+                                      InitData() );
+    }
+private:
+    struct StaticInstanceWithInit {
+        T * operator () ( Data d ) {
+            static T instance(d);
+            return &instance;
+        }
+    };
+};
+#endif
+} // namespace rtl
+
+#endif // INCLUDED_RTL_INSTANCE_HXX
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */