include/vcl/vclptr.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_VCL_PTR_HXX
  21 #define INCLUDED_VCL_PTR_HXX
  22
  23 #include <sal/config.h>
  24
  25 #include <rtl/ref.hxx>
  26
  27 #include <utility>
  28 #include <type_traits>
  29
  30 #ifdef DBG_UTIL
  31 #ifndef WNT
  32 #include <vcl/vclmain.hxx>
  33 #endif
  34 #endif
  35
  36 class VclReferenceBase;
  37
  38 namespace vcl { namespace detail {
  39
  40 template<typename>
  41 constexpr bool isIncompleteOrDerivedFromVclReferenceBase(...) { return true; }
  42
  43 template<typename T> constexpr bool isIncompleteOrDerivedFromVclReferenceBase(
  44     int (*)[sizeof(T)])
  45 { return std::is_base_of<VclReferenceBase, T>::value; }
  46
  47 }; }; // namespace detail, namespace vcl
  48
  49 /**
  50  * A thin wrapper around rtl::Reference to implement the acquire and dispose semantics we want for references to vcl::Window subclasses.
  51  *
  52  * For more details on the design please see vcl/README.lifecycle
  53  *
  54  * @param reference_type must be a subclass of vcl::Window
  55  */
  56 template <class reference_type>
  57 class VclPtr
  58 {
  59     static_assert(
  60         vcl::detail::isIncompleteOrDerivedFromVclReferenceBase<reference_type>(
  61             nullptr),
  62         "template argument type must be derived from VclReferenceBase");
  63
  64     ::rtl::Reference<reference_type> m_rInnerRef;
  65
  66 public:
  67     /** Constructor...
  68      */
  69     VclPtr()
  70         : m_rInnerRef()
  71     {}
  72
  73     /** Constructor...
  74      */
  75     VclPtr (reference_type * pBody)
  76         : m_rInnerRef(pBody)
  77     {}
  78
  79     /** Constructor... that doesn't take a ref.
  80      */
  81     VclPtr (reference_type * pBody, __sal_NoAcquire)
  82         : m_rInnerRef(pBody, SAL_NO_ACQUIRE)
  83     {}
  84
  85     /** Up-casting conversion constructor: Copies interface reference.
  86
  87         Does not work for up-casts to ambiguous bases.  For the special case of
  88         up-casting to Reference< XInterface >, see the corresponding conversion
  89         operator.
  90
  91         @param rRef another reference
  92     */
  93     template< class derived_type >
  94     VclPtr(
  95         const VclPtr< derived_type > & rRef,
  96         typename std::enable_if<
  97             std::is_base_of<reference_type, derived_type>::value, int>::type
  98             = 0 )
  99         : m_rInnerRef( static_cast<reference_type*>(rRef) )
 100     {
 101     }
 102
 103 #if defined(DBG_UTIL) && !defined(WNT)
 104     virtual ~VclPtr()
 105     {
 106         assert(m_rInnerRef.get() == nullptr || vclmain::isAlive());
 107         // We can be one of the intermediate counts, but if we are the last
 108         // VclPtr keeping this object alive, then something forgot to call dispose().
 109         assert((!m_rInnerRef.get() || m_rInnerRef->isDisposed() || m_rInnerRef->getRefCount() > 1)
 110                 && "someone forgot to call dispose()");
 111     }
 112     VclPtr(VclPtr const &) = default;
 113     VclPtr(VclPtr &&) = default;
 114     VclPtr & operator =(VclPtr const &) = default;
 115     VclPtr & operator =(VclPtr &&) = default;
 116 #endif
 117
 118     /**
 119      * A construction helper for VclPtr. Since VclPtr types are created
 120      * with a reference-count of one - to help fit into the existing
 121      * code-flow; this helps us to construct them easily.
 122      *
 123      * For more details on the design please see vcl/README.lifecycle
 124      *
 125      * @tparam reference_type must be a subclass of vcl::Window
 126      */
 127     template<typename... Arg> [[nodiscard]] static VclPtr< reference_type > Create(Arg &&... arg)
 128     {
 129         return VclPtr< reference_type >( new reference_type(std::forward<Arg>(arg)...), SAL_NO_ACQUIRE );
 130     }
 131
 132     /** Probably most common used: handle->someBodyOp().
 133      */
 134     reference_type * operator->() const
 135     {
 136         return m_rInnerRef.get();
 137     }
 138
 139     /** Get the body. Can be used instead of operator->().
 140          I.e. handle->someBodyOp() and handle.get()->someBodyOp()
 141          are the same.
 142       */
 143     reference_type * get() const
 144     {
 145         return m_rInnerRef.get();
 146     }
 147
 148     void set(reference_type *pBody)
 149     {
 150         m_rInnerRef.set(pBody);
 151     }
 152
 153     void reset(reference_type *pBody)
 154     {
 155         m_rInnerRef.set(pBody);
 156     }
 157
 158     /** Up-casting copy assignment operator.
 159
 160         Does not work for up-casts to ambiguous bases.
 161
 162         @param rRef another reference
 163     */
 164     template<typename derived_type>
 165     typename std::enable_if<
 166         std::is_base_of<reference_type, derived_type>::value,
 167         VclPtr &>::type
 168     operator =(VclPtr<derived_type> const & rRef)
 169     {
 170         m_rInnerRef.set(rRef.get());
 171         return *this;
 172     }
 173
 174     VclPtr & operator =(reference_type * pBody)
 175     {
 176         m_rInnerRef.set(pBody);
 177         return *this;
 178     }
 179
 180     operator reference_type * () const
 181     {
 182         return m_rInnerRef.get();
 183     }
 184
 185     explicit operator bool () const
 186     {
 187         return m_rInnerRef.get() != nullptr;
 188     }
 189
 190     void clear()
 191     {
 192         m_rInnerRef.clear();
 193     }
 194
 195     void reset()
 196     {
 197         m_rInnerRef.clear();
 198     }
 199
 200     void disposeAndClear()
 201     {
 202         // hold it alive for the lifetime of this method
 203         ::rtl::Reference<reference_type> aTmp(m_rInnerRef);
 204         m_rInnerRef.clear(); // we should use some 'swap' method ideally ;-)
 205         if (aTmp.get()) {
 206             aTmp->disposeOnce();
 207         }
 208     }
 209
 210     /** Needed to place VclPtr's into STL collection.
 211      */
 212     bool operator< (const VclPtr<reference_type> & handle) const
 213     {
 214         return (m_rInnerRef < handle.m_rInnerRef);
 215     }
 216 }; // class VclPtr
 217
 218 template<typename T1, typename T2>
 219 inline bool operator ==(VclPtr<T1> const & p1, VclPtr<T2> const & p2) {
 220     return p1.get() == p2.get();
 221 }
 222
 223 template<typename T> inline bool operator ==(VclPtr<T> const & p1, T const * p2)
 224 {
 225     return p1.get() == p2;
 226 }
 227
 228 template<typename T> inline bool operator ==(VclPtr<T> const & p1, T * p2) {
 229     return p1.get() == p2;
 230 }
 231
 232 template<typename T> inline bool operator ==(T const * p1, VclPtr<T> const & p2)
 233 {
 234     return p1 == p2.get();
 235 }
 236
 237 template<typename T> inline bool operator ==(T * p1, VclPtr<T> const & p2) {
 238     return p1 == p2.get();
 239 }
 240
 241 template<typename T1, typename T2>
 242 inline bool operator !=(VclPtr<T1> const & p1, VclPtr<T2> const & p2) {
 243     return !(p1 == p2);
 244 }
 245
 246 template<typename T> inline bool operator !=(VclPtr<T> const & p1, T const * p2)
 247 {
 248     return !(p1 == p2);
 249 }
 250
 251 template<typename T> inline bool operator !=(VclPtr<T> const & p1, T * p2) {
 252     return !(p1 == p2);
 253 }
 254
 255 template<typename T> inline bool operator !=(T const * p1, VclPtr<T> const & p2)
 256 {
 257     return !(p1 == p2);
 258 }
 259
 260 template<typename T> inline bool operator !=(T * p1, VclPtr<T> const & p2) {
 261     return !(p1 == p2);
 262 }
 263
 264 /**
 265  * A construction helper for a temporary VclPtr. Since VclPtr types
 266  * are created with a reference-count of one - to help fit into
 267  * the existing code-flow; this helps us to construct them easily.
 268  * see also VclPtr::Create and ScopedVclPtr
 269  *
 270  * For more details on the design please see vcl/README.lifecycle
 271  *
 272  * @param reference_type must be a subclass of vcl::Window
 273  */
 274 template <class reference_type>
 275 class SAL_WARN_UNUSED VclPtrInstance final : public VclPtr<reference_type>
 276 {
 277 public:
 278     template<typename... Arg> VclPtrInstance(Arg &&... arg)
 279         : VclPtr<reference_type>( new reference_type(std::forward<Arg>(arg)...), SAL_NO_ACQUIRE )
 280     {
 281     }
 282
 283     /**
 284      * Override and disallow this, to prevent people accidentally calling it and actually
 285      * getting VclPtr::Create and getting a naked VclPtr<> instance
 286      */
 287     template<typename... Arg> static VclPtrInstance< reference_type > Create(Arg &&... ) = delete;
 288 };
 289
 290 template <class reference_type>
 291 class ScopedVclPtr : public VclPtr<reference_type>
 292 {
 293 public:
 294     /** Constructor...
 295      */
 296     ScopedVclPtr()
 297         : VclPtr<reference_type>()
 298     {}
 299
 300     /** Constructor
 301      */
 302     ScopedVclPtr (reference_type * pBody)
 303         : VclPtr<reference_type>(pBody)
 304     {}
 305
 306     /** Copy constructor...
 307      */
 308     ScopedVclPtr (const VclPtr<reference_type> & handle)
 309         : VclPtr<reference_type>(handle)
 310     {}
 311
 312     /**
 313        Assignment that releases the last reference.
 314      */
 315     void disposeAndReset(reference_type *pBody)
 316     {
 317         if (pBody != this->get()) {
 318             VclPtr<reference_type>::disposeAndClear();
 319             VclPtr<reference_type>::set(pBody);
 320         }
 321     }
 322
 323     /**
 324        Assignment that releases the last reference.
 325      */
 326     ScopedVclPtr<reference_type>& operator = (reference_type * pBody)
 327     {
 328         disposeAndReset(pBody);
 329         return *this;
 330     }
 331
 332     /** Up-casting conversion constructor: Copies interface reference.
 333
 334         Does not work for up-casts to ambiguous bases.  For the special case of
 335         up-casting to Reference< XInterface >, see the corresponding conversion
 336         operator.
 337
 338         @param rRef another reference
 339     */
 340     template< class derived_type >
 341     ScopedVclPtr(
 342         const VclPtr< derived_type > & rRef,
 343         typename std::enable_if<
 344             std::is_base_of<reference_type, derived_type>::value, int>::type
 345             = 0 )
 346         : VclPtr<reference_type>( rRef )
 347     {
 348     }
 349
 350     /** Up-casting assignment operator.
 351
 352         Does not work for up-casts to ambiguous bases.
 353
 354         @param rRef another VclPtr
 355     */
 356     template<typename derived_type>
 357     typename std::enable_if<
 358         std::is_base_of<reference_type, derived_type>::value,
 359         ScopedVclPtr &>::type
 360     operator =(VclPtr<derived_type> const & rRef)
 361     {
 362         disposeAndReset(rRef.get());
 363         return *this;
 364     }
 365
 366     /**
 367      * Override and disallow this, to prevent people accidentally calling it and actually
 368      * getting VclPtr::Create and getting a naked VclPtr<> instance
 369      */
 370     template<typename... Arg> static ScopedVclPtr< reference_type > Create(Arg &&... ) = delete;
 371
 372     ~ScopedVclPtr()
 373     {
 374         VclPtr<reference_type>::disposeAndClear();
 375         assert(VclPtr<reference_type>::get() == nullptr); // make sure there are no lingering references
 376     }
 377
 378 private:
 379     // Most likely we don't want this default copy-constructor.
 380     ScopedVclPtr (const ScopedVclPtr<reference_type> &) = delete;
 381     // And certainly we don't want a default assignment operator.
 382     ScopedVclPtr<reference_type>& operator = (const ScopedVclPtr<reference_type> &) = delete;
 383     // And disallow reset as that doesn't call disposeAndClear on the original reference
 384     void reset() = delete;
 385     void reset(reference_type *pBody) = delete;
 386
 387 protected:
 388     ScopedVclPtr (reference_type * pBody, __sal_NoAcquire)
 389         : VclPtr<reference_type>(pBody, SAL_NO_ACQUIRE)
 390     {}
 391 };
 392
 393 /**
 394  * A construction helper for ScopedVclPtr. Since VclPtr types are created
 395  * with a reference-count of one - to help fit into the existing
 396  * code-flow; this helps us to construct them easily.
 397  *
 398  * For more details on the design please see vcl/README.lifecycle
 399  *
 400  * @param reference_type must be a subclass of vcl::Window
 401  */
 402 #if defined _MSC_VER
 403 #pragma warning(push)
 404 #pragma warning(disable: 4521) // " multiple copy constructors specified"
 405 #endif
 406 template <class reference_type>
 407 class SAL_WARN_UNUSED ScopedVclPtrInstance final : public ScopedVclPtr<reference_type>
 408 {
 409 public:
 410     template<typename... Arg> ScopedVclPtrInstance(Arg &&... arg)
 411         : ScopedVclPtr<reference_type>( new reference_type(std::forward<Arg>(arg)...), SAL_NO_ACQUIRE )
 412     {
 413     }
 414
 415     /**
 416      * Override and disallow this, to prevent people accidentally calling it and actually
 417      * getting VclPtr::Create and getting a naked VclPtr<> instance
 418      */
 419     template<typename... Arg> static ScopedVclPtrInstance< reference_type > Create(Arg &&...) = delete;
 420
 421 private:
 422     // Prevent the above perfect forwarding ctor from hijacking (accidental)
 423     // attempts at ScopedVclPtrInstance copy construction (where the hijacking
 424     // would typically lead to somewhat obscure error messages); both non-const
 425     // and const variants are needed here, as the ScopedVclPtr base class has a
 426     // const--variant copy ctor, so the implicitly declared copy ctor for
 427     // ScopedVclPtrInstance would also be the const variant, so non-const copy
 428     // construction attempts would be hijacked by the perfect forwarding ctor;
 429     // but if we only declared a non-const variant here, the const variant would
 430     // no longer be implicitly declared (as there would already be an explicitly
 431     // declared copy ctor), so const copy construction attempts would then be
 432     // hijacked by the perfect forwarding ctor:
 433     ScopedVclPtrInstance(ScopedVclPtrInstance &) = delete;
 434     ScopedVclPtrInstance(ScopedVclPtrInstance const &) = delete;
 435 };
 436 #if defined _MSC_VER
 437 #pragma warning(pop)
 438 #endif
 439
 440 #endif // INCLUDED_VCL_PTR_HXX
 441
 442 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */