1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at http://qt.nokia.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/
#include "qscopedpointer.h"
QT_BEGIN_NAMESPACE
/*!
\class QScopedPointer
\brief The QScopedPointer class stores a pointer to a dynamically allocated object, and deletes it upon destruction.
\since 4.6
\reentrant
\ingroup misc
Managing heap allocated objects manually is hard and error prone, with the
common result that code leaks memory and is hard to maintain.
QScopedPointer is a small utility class that heavily simplifies this by
assigning stack-based memory ownership to heap allocations, more generally
called resource acquisition is initialization(RAII).
QScopedPointer guarantees that the object pointed to will get deleted when
the current scope dissapears.
Consider this function which does heap allocations, and have various exit points:
\snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 0
It's encumbered by the manual delete calls. With QScopedPointer, the code
can be simplified to:
\snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 1
The code the compiler generates for QScopedPointer is the same as when
writing it manually. Code that makes use of \a delete are candidates for
QScopedPointer usage (and if not, possibly another type of smart pointer
such as QSharedPointer). QScopedPointer intentionally has no copy
constructor or assignment operator, such that ownership and lifetime is
clearly communicated.
The const qualification on a regular C++ pointer can also be expressed with
a QScopedPointer:
\snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 2
\section1 Custom cleanup handlers
Arrays as well as pointers that have been allocated with \c malloc must
not be deleted using \c delete. QScopedPointer's second template parameter
can be used for custom cleanup handlers.
The following custom cleanup handlers exist:
\list
\i QScopedPointerDeleter - the default, deletes the pointer using \c delete
\i QScopedPointerArrayDeleter - deletes the pointer using \c{delete []}. Use
this handler for pointers that were allocated with \c{new []}.
\i QScopedPointerPodDeleter - deletes the pointer using \c{free()}. Use this
handler for pointers that were allocated with \c{malloc()}.
\endlist
You can pass your own classes as handlers, provided that they have a public
static function \c{void cleanup(T *pointer)}.
\snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 5
\section1 Forward Declared Pointers
Classes that are forward declared can be used within QScopedPointer, as
long as the destructor of the forward declared class is available whenever
a QScopedPointer needs to clean up.
Concretely, this means that all classes containing a QScopedPointer that
points to a forward declared class must have non-inline constructors,
destructors and assignment operators:
\snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 4
Otherwise, the compiler output a warning about not being able to destruct
\c MyPrivateClass.
\sa QSharedPointer
*/
/*!
\fn QScopedPointer::QScopedPointer(T *p = 0)
Constructs this QScopedPointer instance and sets its pointer to \a p.
*/
/*!
\fn QScopedPointer::~QScopedPointer()
Destroys this QScopedPointer object. Delete the object its pointer points
to.
*/
/*!
\fn T *QScopedPointer::data() const
Returns the value of the pointer referenced by this object. QScopedPointer
still owns the object pointed to.
*/
/*!
\fn T &QScopedPointer::operator*() const
Provides access to the scoped pointer's object.
If the contained pointer is \c null, behavior is undefined.
\sa isNull()
*/
/*!
\fn T *QScopedPointer::operator->() const
Provides access to the scoped pointer's object.
If the contained pointer is \c null, behavior is undefined.
\sa isNull()
*/
/*!
\fn QScopedPointer::operator bool() const
Returns \c true if this object is not \c null. This function is suitable
for use in \tt if-constructs, like:
\snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 3
\sa isNull()
*/
/*!
\fn bool QScopedPointer::operator==(const QScopedPointer<T, Cleanup> &other) const
Equality operator. Returns true if the scoped pointer \a other
is pointing to the same object as this pointer, otherwise returns false.
*/
/*!
\fn bool QScopedPointer::operator!=(const QScopedPointer<T, Cleanup> &other) const
Inequality operator. Returns true if the scoped pointer \a other
is not pointing to the same object as this pointer, otherwise returns false.
*/
/*!
\fn bool QScopedPointer::isNull() const
Returns \c true if this object is holding a pointer that is \c null.
*/
/*!
\fn void QScopedPointer::reset(T *other = 0)
Deletes the existing object it is pointing to if any, and sets its pointer to
\a other. QScopedPointer now owns \a other and will delete it in its
destructor.
*/
/*!
\fn T *QScopedPointer::take()
Returns the value of the pointer referenced by this object. The pointer of this
QScopedPointer object will be reset to \c null.
Callers of this function take ownership of the pointer.
*/
/*! \fn bool QScopedPointer::operator!() const
Returns \c true if the pointer referenced by this object is \c null, otherwise
returns \c false.
\sa isNull()
*/
QT_END_NAMESPACE
|
