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 _WIN32
  32 #include <vcl/vclmain.hxx>
  33 #endif
  34 #endif
  35
  36 class VclReferenceBase;
  37
  38 namespace vcl::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 vcl::detail
  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(_WIN32)
 104     ~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(std::move(m_rInnerRef));
 204         // coverity[use_after_move : SUPPRESS] - the move ctor above must take care of it
 205         assert(!m_rInnerRef);
 206         if (aTmp.get()) {
 207             aTmp->disposeOnce();
 208         }
 209     }
 210
 211     /** Needed to place VclPtr's into STL collection.
 212      */
 213     bool operator< (const VclPtr<reference_type> & handle) const
 214     {
 215         return (m_rInnerRef < handle.m_rInnerRef);
 216     }
 217 }; // class VclPtr
 218
 219 template<typename T1, typename T2>
 220 inline bool operator ==(VclPtr<T1> const & p1, VclPtr<T2> const & p2) {
 221     return p1.get() == p2.get();
 222 }
 223
 224 template<typename T> inline bool operator ==(VclPtr<T> const & p1, T const * p2)
 225 {
 226     return p1.get() == p2;
 227 }
 228
 229 template<typename T> inline bool operator ==(VclPtr<T> const & p1, T * p2) {
 230     return p1.get() == p2;
 231 }
 232
 233 template<typename T> inline bool operator ==(T const * p1, VclPtr<T> const & p2)
 234 {
 235     return p1 == p2.get();
 236 }
 237
 238 template<typename T> inline bool operator ==(T * p1, VclPtr<T> const & p2) {
 239     return p1 == p2.get();
 240 }
 241
 242 template<typename T1, typename T2>
 243 inline bool operator !=(VclPtr<T1> const & p1, VclPtr<T2> const & p2) {
 244     return !(p1 == p2);
 245 }
 246
 247 template<typename T> inline bool operator !=(VclPtr<T> const & p1, T const * p2)
 248 {
 249     return !(p1 == p2);
 250 }
 251
 252 template<typename T> inline bool operator !=(VclPtr<T> const & p1, T * p2) {
 253     return !(p1 == p2);
 254 }
 255
 256 template<typename T> inline bool operator !=(T const * p1, VclPtr<T> const & p2)
 257 {
 258     return !(p1 == p2);
 259 }
 260
 261 template<typename T> inline bool operator !=(T * p1, VclPtr<T> const & p2) {
 262     return !(p1 == p2);
 263 }
 264
 265 /**
 266  * A construction helper for a temporary VclPtr. Since VclPtr types
 267  * are created with a reference-count of one - to help fit into
 268  * the existing code-flow; this helps us to construct them easily.
 269  * see also VclPtr::Create and ScopedVclPtr
 270  *
 271  * For more details on the design please see vcl/README.lifecycle
 272  *
 273  * @param reference_type must be a subclass of vcl::Window
 274  */
 275 template <class reference_type>
 276 class SAL_WARN_UNUSED VclPtrInstance final : public VclPtr<reference_type>
 277 {
 278 public:
 279     template<typename... Arg> VclPtrInstance(Arg &&... arg)
 280         : VclPtr<reference_type>( new reference_type(std::forward<Arg>(arg)...), SAL_NO_ACQUIRE )
 281     {
 282     }
 283
 284     /**
 285      * Override and disallow this, to prevent people accidentally calling it and actually
 286      * getting VclPtr::Create and getting a naked VclPtr<> instance
 287      */
 288     template<typename... Arg> static VclPtrInstance< reference_type > Create(Arg &&... ) = delete;
 289 };
 290
 291 template <class reference_type>
 292 class ScopedVclPtr : public VclPtr<reference_type>
 293 {
 294 public:
 295     /** Constructor...
 296      */
 297     ScopedVclPtr()
 298         : VclPtr<reference_type>()
 299     {}
 300
 301     /** Constructor
 302      */
 303     ScopedVclPtr (reference_type * pBody)
 304         : VclPtr<reference_type>(pBody)
 305     {}
 306
 307     /** Copy constructor...
 308      */
 309     ScopedVclPtr (const VclPtr<reference_type> & handle)
 310         : VclPtr<reference_type>(handle)
 311     {}
 312
 313     /**
 314        Assignment that releases the last reference.
 315      */
 316     void disposeAndReset(reference_type *pBody)
 317     {
 318         if (pBody != this->get()) {
 319             VclPtr<reference_type>::disposeAndClear();
 320             VclPtr<reference_type>::set(pBody);
 321         }
 322     }
 323
 324     /**
 325        Assignment that releases the last reference.
 326      */
 327     ScopedVclPtr<reference_type>& operator = (reference_type * pBody)
 328     {
 329         disposeAndReset(pBody);
 330         return *this;
 331     }
 332
 333     /** Up-casting conversion constructor: Copies interface reference.
 334
 335         Does not work for up-casts to ambiguous bases.  For the special case of
 336         up-casting to Reference< XInterface >, see the corresponding conversion
 337         operator.
 338
 339         @param rRef another reference
 340     */
 341     template< class derived_type >
 342     ScopedVclPtr(
 343         const VclPtr< derived_type > & rRef,
 344         typename std::enable_if<
 345             std::is_base_of<reference_type, derived_type>::value, int>::type
 346             = 0 )
 347         : VclPtr<reference_type>( rRef )
 348     {
 349     }
 350
 351     /** Up-casting assignment operator.
 352
 353         Does not work for up-casts to ambiguous bases.
 354
 355         @param rRef another VclPtr
 356     */
 357     template<typename derived_type>
 358     typename std::enable_if<
 359         std::is_base_of<reference_type, derived_type>::value,
 360         ScopedVclPtr &>::type
 361     operator =(VclPtr<derived_type> const & rRef)
 362     {
 363         disposeAndReset(rRef.get());
 364         return *this;
 365     }
 366
 367     /**
 368      * Override and disallow this, to prevent people accidentally calling it and actually
 369      * getting VclPtr::Create and getting a naked VclPtr<> instance
 370      */
 371     template<typename... Arg> static ScopedVclPtr< reference_type > Create(Arg &&... ) = delete;
 372
 373     ~ScopedVclPtr()
 374     {
 375         VclPtr<reference_type>::disposeAndClear();
 376         assert(VclPtr<reference_type>::get() == nullptr); // make sure there are no lingering references
 377     }
 378
 379 private:
 380     // Most likely we don't want this default copy-constructor.
 381     ScopedVclPtr (const ScopedVclPtr<reference_type> &) = delete;
 382     // And certainly we don't want a default assignment operator.
 383     ScopedVclPtr<reference_type>& operator = (const ScopedVclPtr<reference_type> &) = delete;
 384     // And disallow reset as that doesn't call disposeAndClear on the original reference
 385     void reset() = delete;
 386     void reset(reference_type *pBody) = delete;
 387
 388 protected:
 389     ScopedVclPtr (reference_type * pBody, __sal_NoAcquire)
 390         : VclPtr<reference_type>(pBody, SAL_NO_ACQUIRE)
 391     {}
 392 };
 393
 394 /**
 395  * A construction helper for ScopedVclPtr. Since VclPtr types are created
 396  * with a reference-count of one - to help fit into the existing
 397  * code-flow; this helps us to construct them easily.
 398  *
 399  * For more details on the design please see vcl/README.lifecycle
 400  *
 401  * @param reference_type must be a subclass of vcl::Window
 402  */
 403 #if defined _MSC_VER
 404 #pragma warning(push)
 405 #pragma warning(disable: 4521) // " multiple copy constructors specified"
 406 #endif
 407 template <class reference_type>
 408 class SAL_WARN_UNUSED ScopedVclPtrInstance final : public ScopedVclPtr<reference_type>
 409 {
 410 public:
 411     template<typename... Arg> ScopedVclPtrInstance(Arg &&... arg)
 412         : ScopedVclPtr<reference_type>( new reference_type(std::forward<Arg>(arg)...), SAL_NO_ACQUIRE )
 413     {
 414     }
 415
 416     /**
 417      * Override and disallow this, to prevent people accidentally calling it and actually
 418      * getting VclPtr::Create and getting a naked VclPtr<> instance
 419      */
 420     template<typename... Arg> static ScopedVclPtrInstance< reference_type > Create(Arg &&...) = delete;
 421
 422 private:
 423     // Prevent the above perfect forwarding ctor from hijacking (accidental)
 424     // attempts at ScopedVclPtrInstance copy construction (where the hijacking
 425     // would typically lead to somewhat obscure error messages); both non-const
 426     // and const variants are needed here, as the ScopedVclPtr base class has a
 427     // const--variant copy ctor, so the implicitly declared copy ctor for
 428     // ScopedVclPtrInstance would also be the const variant, so non-const copy
 429     // construction attempts would be hijacked by the perfect forwarding ctor;
 430     // but if we only declared a non-const variant here, the const variant would
 431     // no longer be implicitly declared (as there would already be an explicitly
 432     // declared copy ctor), so const copy construction attempts would then be
 433     // hijacked by the perfect forwarding ctor:
 434     ScopedVclPtrInstance(ScopedVclPtrInstance &) = delete;
 435     ScopedVclPtrInstance(ScopedVclPtrInstance const &) = delete;
 436 };
 437 #if defined _MSC_VER
 438 #pragma warning(pop)
 439 #endif
 440
 441 #endif // INCLUDED_VCL_PTR_HXX
 442
 443 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */