include/o3tl/heap_ptr.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_O3TL_HEAP_PTR_HXX
  21 #define INCLUDED_O3TL_HEAP_PTR_HXX
  22
  23
  24 #include <boost/assert.hpp>
  25 #include <boost/checked_delete.hpp>
  26
  27
  28 namespace o3tl
  29 {
  30 /** heap_ptr<> owns an object on the heap, which will be automatically
  31     deleted, when ~heap_ptr<>() is called.
  32
  33     Applicability
  34     -------------
  35     heap_ptr<> can be used for class members on the heap.
  36       - One cannot forget to delete them in the destructor.
  37       - Constness will be transfered from the owning instance.
  38
  39     heap_ptr<> can also be used as smart pointer in function bodies to
  40     ensure exception safety.
  41
  42     Special Characteristics
  43     -----------------------
  44       - heap_ptr<> transfers constness from the owning object to
  45         the pointed to object. Such it behaves like if *get() would be
  46         a normal member of the owning object, not a pointer member.
  47         This is preferable to the normal pointer behaviour, because
  48         if an object is owned by another one, it is normally part of
  49         its state.
  50
  51       - heap_ptr<> provides a ->release() function
  52
  53       - For reasons of simplicity and portability ->is()
  54         is preferred over the safe-bool idiom.
  55
  56     Copyability
  57     -----------
  58     heap_ptr is non copyable.
  59       - It forbids the copyconstructor and operator=(self).
  60
  61       - Owning classes will automatically be non copyable, if they do not
  62         redefine those two functions themselves.
  63
  64     Incomplete Types
  65     ----------------
  66     heap_ptr<> also works with incomplete types. You only need to write
  67         class T;
  68     but need not include <T>.hxx.
  69
  70     If you use heap_ptr<> with an incomplete type, the owning class
  71     needs to define a non-inline destructor. Else the compiler will
  72     complain.
  73 */
  74 template <class T>
  75 class heap_ptr
  76 {
  77   public:
  78     typedef T               element_type;       /// Provided for generic programming.
  79     typedef heap_ptr<T>     self;
  80
  81 #ifndef __SUNPRO_CC
  82     typedef T * (self::*    safe_bool )();
  83 #endif
  84
  85     /// Now, pass_heapObject is owned by this.
  86     explicit            heap_ptr(
  87                             T *                 pass_heapObject = 0 );
  88                         ~heap_ptr();
  89
  90
  91     /** Identical to reset(), except of the return value.
  92         @see heap_ptr<>::reset()
  93     */
  94     self &              operator=(
  95                             T *                 pass_heapObject );
  96     const T &           operator*() const;
  97     T &                 operator*();
  98     const T *           operator->() const;
  99     T *                 operator->();
 100
 101     /// True, if pHeapObject != 0.
 102 #ifndef __SUNPRO_CC
 103                         operator safe_bool() const;
 104 #else // workaround opt bug of Sun C++ compiler, when compiling with -xO3
 105                         operator bool() const;
 106 #endif
 107
 108
 109     /** This deletes any prevoiusly existing ->pHeapObject.
 110         Now, pass_heapObject, if != 0, is owned by this.
 111
 112         @onerror
 113         Ignores self-assignment.
 114         Such, multiple assignment of the same pointer to the same
 115         instance of heap_ptr<> is possible (though not recommended).
 116     */
 117     void                reset(
 118                             T *                 pass_heapObject );
 119     /** @return     An object on the heap that must be deleted by the caller,
 120                     or 0.
 121
 122         @postcond   get() == 0;
 123     */
 124     T *                 release();
 125     void                swap(
 126                             self &              io_other );
 127
 128     /// True, if pHeapObject != 0.
 129     bool                is() const;
 130     const T *           get() const;
 131     T *                 get();
 132
 133   private:
 134     // Forbidden functions:
 135                           heap_ptr( const self & );   /// Prevent copies.
 136     self &              operator=( const self & );  /// Prevent copies.
 137
 138     /// @attention Does not set ->pHeapObject = 0.
 139       void              internal_delete();
 140
 141   // DATA
 142     /// Will be deleted, when *this is destroyed.
 143     T *                 pHeapObject;
 144 };
 145
 146
 147 /** Supports the semantic of std::swap(). Provided as an aid to
 148     generic programming.
 149 */
 150 template<class T>
 151 inline void
 152 swap( heap_ptr<T> &       io_a,
 153       heap_ptr<T> &       io_b )
 154 {
 155     io_a.swap(io_b);
 156 }
 157
 158
 159
 160 // IMPLEMENTATION
 161
 162 template <class T>
 163 inline void
 164 heap_ptr<T>::internal_delete()
 165 {
 166     ::boost::checked_delete(pHeapObject);
 167
 168     // Do not set pHeapObject to 0, because
 169     //   that is reset to a value in all code
 170     //   where internal_delete() is used.
 171 }
 172
 173 template <class T>
 174 inline
 175 heap_ptr<T>::heap_ptr( T * pass_heapObject )
 176     : pHeapObject(pass_heapObject)
 177 {
 178 }
 179
 180 template <class T>
 181 inline
 182 heap_ptr<T>::~heap_ptr()
 183 {
 184     internal_delete();
 185 }
 186
 187 template <class T>
 188 inline heap_ptr<T> &
 189 heap_ptr<T>::operator=(T * pass_heapObject)
 190 {
 191     reset(pass_heapObject);
 192     return *this;
 193 }
 194
 195 template <class T>
 196 inline const T &
 197 heap_ptr<T>::operator*() const
 198 {
 199     BOOST_ASSERT( pHeapObject != 0
 200                   && "Accessing a heap_ptr<>(0)." );
 201     return *pHeapObject;
 202 }
 203
 204 template <class T>
 205 inline T &
 206 heap_ptr<T>::operator*()
 207 {
 208     BOOST_ASSERT( pHeapObject != 0
 209                   && "Accessing a heap_ptr<>(0)." );
 210     return *pHeapObject;
 211 }
 212
 213 template <class T>
 214 inline const T *
 215 heap_ptr<T>::operator->() const
 216 {
 217     return pHeapObject;
 218 }
 219
 220 template <class T>
 221 inline T *
 222 heap_ptr<T>::operator->()
 223 {
 224     return pHeapObject;
 225 }
 226
 227 #ifndef __SUNPRO_CC
 228
 229 template <class T>
 230 inline
 231 heap_ptr<T>::operator typename heap_ptr<T>::safe_bool() const
 232 {
 233     return is()
 234             ? safe_bool(&self::get)
 235             : safe_bool(0);
 236 }
 237
 238 #else
 239
 240 template <class T>
 241 inline heap_ptr<T>::operator bool() const
 242 {
 243     return is();
 244 }
 245
 246 #endif // !defined(__SUNPRO_CC)
 247
 248
 249
 250 template <class T>
 251 void
 252 heap_ptr<T>::reset(T * pass_heapObject)
 253 {
 254     if (    pHeapObject != 0
 255         &&  pHeapObject == pass_heapObject)
 256         return;
 257
 258     internal_delete();
 259     pHeapObject = pass_heapObject;
 260 }
 261
 262 template <class T>
 263 T *
 264 heap_ptr<T>::release()
 265 {
 266     T * ret = pHeapObject;
 267     pHeapObject = 0;
 268     return ret;
 269 }
 270
 271 template <class T>
 272 void
 273 heap_ptr<T>::swap(self & io_other)
 274 {
 275     T * temp = io_other.pHeapObject;
 276     io_other.pHeapObject = pHeapObject;
 277     pHeapObject = temp;
 278 }
 279
 280 template <class T>
 281 inline bool
 282 heap_ptr<T>::is() const
 283 {
 284     return pHeapObject != 0;
 285 }
 286
 287 template <class T>
 288 inline const T *
 289 heap_ptr<T>::get() const
 290 {
 291     return pHeapObject;
 292 }
 293
 294 template <class T>
 295 inline T *
 296 heap_ptr<T>::get()
 297 {
 298     return pHeapObject;
 299 }
 300
 301
 302 }   // namespace o3tl
 303 #endif
 304
 305 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */