1 /**************************************************************************** 2 ** 3 ** Copyright (C) 2016 The Qt Company Ltd. 4 ** Contact: https://www.qt.io/licensing/ 5 ** 6 ** This file is part of the QtCore module of the Qt Toolkit. 7 ** 8 ** $QT_BEGIN_LICENSE:LGPL$ 9 ** Commercial License Usage 10 ** Licensees holding valid commercial Qt licenses may use this file in 11 ** accordance with the commercial license agreement provided with the 12 ** Software or, alternatively, in accordance with the terms contained in 13 ** a written agreement between you and The Qt Company. For licensing terms 14 ** and conditions see https://www.qt.io/terms-conditions. For further 15 ** information use the contact form at https://www.qt.io/contact-us. 16 ** 17 ** GNU Lesser General Public License Usage 18 ** Alternatively, this file may be used under the terms of the GNU Lesser 19 ** General Public License version 3 as published by the Free Software 20 ** Foundation and appearing in the file LICENSE.LGPL3 included in the 21 ** packaging of this file. Please review the following information to 22 ** ensure the GNU Lesser General Public License version 3 requirements 23 ** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. 24 ** 25 ** GNU General Public License Usage 26 ** Alternatively, this file may be used under the terms of the GNU 27 ** General Public License version 2.0 or (at your option) the GNU General 28 ** Public license version 3 or any later version approved by the KDE Free 29 ** Qt Foundation. The licenses are as published by the Free Software 30 ** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 31 ** included in the packaging of this file. Please review the following 32 ** information to ensure the GNU General Public License requirements will 33 ** be met: https://www.gnu.org/licenses/gpl-2.0.html and 34 ** https://www.gnu.org/licenses/gpl-3.0.html. 35 ** 36 ** $QT_END_LICENSE$ 37 ** 38 ****************************************************************************/ 39 40 #include "qscopedpointer.h" 41 42 QT_BEGIN_NAMESPACE 43 44 /*! 45 \class QScopedPointer 46 \inmodule QtCore 47 \brief The QScopedPointer class stores a pointer to a dynamically allocated object, and deletes it upon destruction. 48 \since 4.6 49 \reentrant 50 \ingroup misc 51 52 Managing heap allocated objects manually is hard and error prone, with the 53 common result that code leaks memory and is hard to maintain. 54 QScopedPointer is a small utility class that heavily simplifies this by 55 assigning stack-based memory ownership to heap allocations, more generally 56 called resource acquisition is initialization(RAII). 57 58 QScopedPointer guarantees that the object pointed to will get deleted when 59 the current scope disappears. 60 61 Consider this function which does heap allocations, and has various exit points: 62 63 \snippet code/src_corelib_tools_qscopedpointer.cpp 0 64 65 It's encumbered by the manual delete calls. With QScopedPointer, the code 66 can be simplified to: 67 68 \snippet code/src_corelib_tools_qscopedpointer.cpp 1 69 70 The code the compiler generates for QScopedPointer is the same as when 71 writing it manually. Code that makes use of \a delete are candidates for 72 QScopedPointer usage (and if not, possibly another type of smart pointer 73 such as QSharedPointer). QScopedPointer intentionally has no copy 74 constructor or assignment operator, such that ownership and lifetime is 75 clearly communicated. 76 77 The const qualification on a regular C++ pointer can also be expressed with 78 a QScopedPointer: 79 80 \snippet code/src_corelib_tools_qscopedpointer.cpp 2 81 82 \section1 Custom Cleanup Handlers 83 84 Arrays as well as pointers that have been allocated with \c malloc must 85 not be deleted using \c delete. QScopedPointer's second template parameter 86 can be used for custom cleanup handlers. 87 88 The following custom cleanup handlers exist: 89 90 \list 91 \li QScopedPointerDeleter - the default, deletes the pointer using \c delete 92 \li QScopedPointerArrayDeleter - deletes the pointer using \c{delete []}. Use 93 this handler for pointers that were allocated with \c{new []}. 94 \li QScopedPointerPodDeleter - deletes the pointer using \c{free()}. Use this 95 handler for pointers that were allocated with \c{malloc()}. 96 \li QScopedPointerDeleteLater - deletes a pointer by calling \c{deleteLater()} 97 on it. Use this handler for pointers to QObject's that are actively 98 participating in a QEventLoop. 99 \endlist 100 101 You can pass your own classes as handlers, provided that they have a public 102 static function \c{void cleanup(T *pointer)}. 103 104 \snippet code/src_corelib_tools_qscopedpointer.cpp 5 105 106 \section1 Forward Declared Pointers 107 108 Classes that are forward declared can be used within QScopedPointer, as 109 long as the destructor of the forward declared class is available whenever 110 a QScopedPointer needs to clean up. 111 112 Concretely, this means that all classes containing a QScopedPointer that 113 points to a forward declared class must have non-inline constructors, 114 destructors and assignment operators: 115 116 \snippet code/src_corelib_tools_qscopedpointer.cpp 4 117 118 Otherwise, the compiler outputs a warning about not being able to destruct 119 \c MyPrivateClass. 120 121 \sa QSharedPointer 122 */ 123 124 /*! \typedef QScopedPointer::pointer 125 \internal 126 */ 127 128 /*! 129 \fn template <typename T, typename Cleanup> QScopedPointer<T, Cleanup>::QScopedPointer(T *p = 0) 130 131 Constructs this QScopedPointer instance and sets its pointer to \a p. 132 */ 133 134 /*! 135 \fn template <typename T, typename Cleanup> QScopedPointer<T, Cleanup>::~QScopedPointer() 136 137 Destroys this QScopedPointer object. Delete the object its pointer points 138 to. 139 */ 140 141 /*! 142 \fn template <typename T, typename Cleanup> T *QScopedPointer<T, Cleanup>::data() const 143 144 Returns the value of the pointer referenced by this object. QScopedPointer 145 still owns the object pointed to. 146 */ 147 148 /*! 149 \fn template <typename T, typename Cleanup> T *QScopedPointer<T, Cleanup>::get() const 150 \since 5.11 151 152 Same as data(). 153 */ 154 155 /*! 156 \fn template <typename T, typename Cleanup> T &QScopedPointer<T, Cleanup>::operator*() const 157 158 Provides access to the scoped pointer's object. 159 160 If the contained pointer is \nullptr, behavior is undefined. 161 \sa isNull() 162 */ 163 164 /*! 165 \fn template <typename T, typename Cleanup> T *QScopedPointer<T, Cleanup>::operator->() const 166 167 Provides access to the scoped pointer's object. 168 169 If the contained pointer is \nullptr, behavior is undefined. 170 171 \sa isNull() 172 */ 173 174 /*! 175 \fn template <typename T, typename Cleanup> QScopedPointer<T, Cleanup>::operator bool() const 176 177 Returns \c true if the contained pointer is not \nullptr. 178 This function is suitable for use in \tt if-constructs, like: 179 180 \snippet code/src_corelib_tools_qscopedpointer.cpp 3 181 182 \sa isNull() 183 */ 184 185 /*! 186 \fn template <typename T, typename Cleanup> bool operator==(const QScopedPointer<T, Cleanup> &lhs, const QScopedPointer<T, Cleanup> &rhs) 187 188 Returns \c true if \a ptr1 and \a ptr2 refer to the same pointer. 189 */ 190 191 192 /*! 193 \fn template <typename T, typename Cleanup> bool operator!=(const QScopedPointer<T, Cleanup> &lhs, const QScopedPointer<T, Cleanup> &rhs) 194 195 Returns \c true if \a lhs and \a rhs refer to distinct pointers. 196 */ 197 198 /*! 199 \fn template <typename T, typename Cleanup> bool operator==(const QScopedPointer<T, Cleanup> &lhs, std::nullptr_t) 200 \relates QScopedPointer 201 \since 5.8 202 203 Returns \c true if \a lhs refers to \nullptr. 204 205 \sa QScopedPointer::isNull() 206 */ 207 208 /*! 209 \fn template <typename T, typename Cleanup> bool operator==(std::nullptr_t, const QScopedPointer<T, Cleanup> &rhs) 210 \relates QScopedPointer 211 \since 5.8 212 213 Returns \c true if \a rhs refers to \nullptr. 214 215 \sa QScopedPointer::isNull() 216 */ 217 218 /*! 219 \fn template <typename T, typename Cleanup> bool operator!=(const QScopedPointer<T, Cleanup> &lhs, std::nullptr_t) 220 \relates QScopedPointer 221 \since 5.8 222 223 Returns \c true if \a lhs refers to a valid (i.e. non-null) pointer. 224 225 \sa QScopedPointer::isNull() 226 */ 227 228 /*! 229 \fn template <typename T, typename Cleanup> bool operator!=(std::nullptr_t, const QScopedPointer<T, Cleanup> &rhs) 230 \relates QScopedPointer 231 \since 5.8 232 233 Returns \c true if \a rhs refers to a valid (i.e. non-null) pointer. 234 235 \sa QScopedPointer::isNull() 236 */ 237 238 /*! 239 \fn template <typename T, typename Cleanup> bool QScopedPointer<T, Cleanup>::isNull() const 240 241 Returns \c true if this object refers to \nullptr. 242 */ 243 244 /*! 245 \fn template <typename T, typename Cleanup> void QScopedPointer<T, Cleanup>::reset(T *other = 0) 246 247 Deletes the existing object it is pointing to (if any), and sets its pointer to 248 \a other. QScopedPointer now owns \a other and will delete it in its 249 destructor. 250 251 To clear the pointer held without deleting the object it points to (and hence take ownership 252 of the object), use \l take() instead. 253 */ 254 255 /*! 256 \fn template <typename T, typename Cleanup> T *QScopedPointer<T, Cleanup>::take() 257 258 Returns the value of the pointer referenced by this object. The pointer of this 259 QScopedPointer object will be reset to \nullptr. 260 261 Callers of this function take ownership of the pointer. 262 */ 263 264 /*! \fn template <typename T, typename Cleanup> bool QScopedPointer<T, Cleanup>::operator!() const 265 266 Returns \c true if this object refers to \nullptr. 267 268 \sa isNull() 269 */ 270 271 /*! \fn template <typename T, typename Cleanup> void QScopedPointer<T, Cleanup>::swap(QScopedPointer<T, Cleanup> &other) 272 Swap this pointer with \a other. 273 */ 274 275 /*! 276 \class QScopedArrayPointer 277 \inmodule QtCore 278 279 \brief The QScopedArrayPointer class stores a pointer to a 280 dynamically allocated array of objects, and deletes it upon 281 destruction. 282 283 \since 4.6 284 \reentrant 285 \ingroup misc 286 287 A QScopedArrayPointer is a QScopedPointer that defaults to 288 deleting the object it is pointing to with the delete[] operator. It 289 also features operator[] for convenience, so we can write: 290 291 \code 292 void foo() 293 { 294 QScopedArrayPointer<int> i(new int[10]); 295 i[2] = 42; 296 ... 297 return; // our integer array is now deleted using delete[] 298 } 299 \endcode 300 */ 301 302 /*! 303 \fn template <typename T, typename Cleanup> QScopedArrayPointer<T, Cleanup>::QScopedArrayPointer() 304 305 Constructs a QScopedArrayPointer instance. 306 */ 307 308 /*! 309 \fn template <typename T, typename Cleanup> template <typename D> QScopedArrayPointer<T, Cleanup>::QScopedArrayPointer(D * p) 310 311 Constructs a QScopedArrayPointer and stores the array of objects 312 pointed to by \a p. 313 */ 314 315 /*! 316 \fn template <typename T, typename Cleanup> T *QScopedArrayPointer<T, Cleanup>::operator[](int i) 317 318 Provides access to entry \a i of the scoped pointer's array of 319 objects. 320 321 If the contained pointer is \nullptr, behavior is undefined. 322 323 \sa isNull() 324 */ 325 326 /*! 327 \fn template <typename T, typename Cleanup> T *QScopedArrayPointer<T, Cleanup>::operator[](int i) const 328 329 Provides access to entry \a i of the scoped pointer's array of 330 objects. 331 332 If the contained pointer is \nullptr behavior is undefined. 333 334 \sa isNull() 335 */ 336 337 /*! \fn template <typename T, typename Cleanup> void QScopedArrayPointer<T, Cleanup>::swap(QScopedArrayPointer<T, Cleanup> &other) 338 Swap this pointer with \a other. 339 */ 340 341 QT_END_NAMESPACE 342