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