← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to src/corelib/tools/qshareddata.cpp

  • Committer: Bazaar Package Importer
  • Author(s): Adam Conrad
  • Date: 2005-08-24 04:09:09 UTC
  • Revision ID: james.westby@ubuntu.com-20050824040909-xmxe9jfr4a0w5671
Tags: upstream-4.0.0
Import upstream version 4.0.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/corelib/tools/qshareddata.cpp
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 1992-2005 Trolltech AS. All rights reserved.
 
4
**
 
5
** This file is part of the core module of the Qt Toolkit.
 
6
**
 
7
** This file may be distributed under the terms of the Q Public License
 
8
** as defined by Trolltech AS of Norway and appearing in the file
 
9
** LICENSE.QPL included in the packaging of this file.
 
10
**
 
11
** This file may be distributed and/or modified under the terms of the
 
12
** GNU General Public License version 2 as published by the Free Software
 
13
** Foundation and appearing in the file LICENSE.GPL included in the
 
14
** packaging of this file.
 
15
**
 
16
** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
 
17
**   information about Qt Commercial License Agreements.
 
18
** See http://www.trolltech.com/qpl/ for QPL licensing information.
 
19
** See http://www.trolltech.com/gpl/ for GPL licensing information.
 
20
**
 
21
** Contact info@trolltech.com if any conditions of this licensing are
 
22
** not clear to you.
 
23
**
 
24
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
 
25
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 
26
**
 
27
****************************************************************************/
 
28
 
 
29
#include <qshareddata.h>
 
30
 
 
31
/*! \class QSharedData
 
32
    \brief The QSharedData class is a base class for shared data objects.
 
33
 
 
34
    \reentrant
 
35
    \ingroup misc
 
36
 
 
37
    QSharedData is designed to be used together with
 
38
    QSharedDataPointer to implement custom \l{implicitly shared}
 
39
    classes. It provides thread-safe reference counting.
 
40
 
 
41
    See the QSharedDataPointer documentation for details.
 
42
*/
 
43
 
 
44
/*! \fn QSharedData::QSharedData()
 
45
 
 
46
    Constructs a QSharedData object with a reference count of 0.
 
47
*/
 
48
 
 
49
/*! \fn QSharedData::QSharedData(const QSharedData &other)
 
50
 
 
51
    Constructs a QSharedData object with a reference count of 0. (\a
 
52
    other is ignored.)
 
53
*/
 
54
 
 
55
/*! \class QSharedDataPointer
 
56
    \brief The QSharedDataPointer class provides a pointer to a shared data object.
 
57
 
 
58
    \reentrant
 
59
    \ingroup misc
 
60
    \mainclass
 
61
 
 
62
    QSharedDataPointer\<T\> makes it easier to write your own
 
63
    implicitly shared classes. It handles reference counting behind
 
64
    the scenes in a thread-safe manner, ensuring that classes that use
 
65
    it can be \l{reentrant}.
 
66
 
 
67
    Implicit sharing is used throughout Qt to combine the memory and
 
68
    speed efficiency of pointers with the ease of use of value types.
 
69
    See the \l{Shared Classes} page for more information.
 
70
 
 
71
    Let's suppose that you want to make an \c Employee class
 
72
    implicitly shared. The procedure is:
 
73
 
 
74
    \list
 
75
    \i Define the \c Employee class with a single data member variable of
 
76
       type QSharedDataPointer<\c{EmployeeData}>.
 
77
    \i Define an \c EmployeeData class that derives from \l QSharedData
 
78
       and that contains all the variables that you would normally
 
79
       put in \c Employee.
 
80
    \endlist
 
81
 
 
82
    To show how this works in practice, we will review the entire
 
83
    source code for an implicitly shared \c Employee class. Here's the
 
84
    header file that defines the \c Employee class:
 
85
 
 
86
    \include snippets/sharedemployee/employee.h
 
87
 
 
88
    All accesses to the data in the setter and getter functions are
 
89
    made through the QSharedDataPointer object \c d. For non-const
 
90
    functions, operator->() automatically calls detach(), ensuring
 
91
    that modifications to one \c Employee object don't affect other
 
92
    \c Employee objects.
 
93
 
 
94
    In this example, the \c EmployeeData type is a simple class with a
 
95
    default constructor and a copy constructor provided by C++. If
 
96
    member-per-member copy isn't sufficient for your own data type,
 
97
    you must implement your own copy constructor.
 
98
 
 
99
    Let's now see how to implement the \c Employee constructors:
 
100
 
 
101
    \quotefile snippets/sharedemployee/employee.cpp
 
102
 
 
103
    \skipto ::Employee()
 
104
    \printuntil }
 
105
 
 
106
    In the default constructor, we create an object of type
 
107
    \c EmployeeData and assign it to the \c d pointer using operator=().
 
108
 
 
109
    \skipto ::Employee(int
 
110
    \printuntil }
 
111
 
 
112
    In the constructor that takes an ID and an employee's name, we
 
113
    also create an object of type \c EmployeeData and assign it to the
 
114
    \c d pointer.
 
115
 
 
116
    In this example, we don't need to provide a copy constructor, an
 
117
    assignment operator, or a destructor for \c Employee. The default
 
118
    implementations provided by C++, which invoke QSharedDataPointer's
 
119
    copy constructor, assignment operator, or destructor, are
 
120
    sufficient. And this is true in general, i.e. for any QSharedData
 
121
    subclass which only stores values (or implicitly shared classes),
 
122
    such as int, double, QString, QStringList, QList\<QWidget*\>, and
 
123
    so on.
 
124
 
 
125
    Behind the scenes, QSharedDataPointer automatically increments or
 
126
    decrements the reference count of the shared data object pointed
 
127
    to by \c d, and deletes shared objects when the reference count
 
128
    reaches 0.
 
129
 
 
130
    \sa QSharedData
 
131
*/
 
132
 
 
133
/*! \fn T &QSharedDataPointer::operator*()
 
134
 
 
135
    Provides access to the shared object's members.
 
136
 
 
137
    This function does a detach().
 
138
*/
 
139
 
 
140
/*! \fn const T &QSharedDataPointer::operator*() const
 
141
 
 
142
    \overload
 
143
 
 
144
    This function does not call detach().
 
145
*/
 
146
 
 
147
/*! \fn T *QSharedDataPointer::operator->()
 
148
 
 
149
    Provides access to the shared object's members.
 
150
 
 
151
    This function does a detach().
 
152
*/
 
153
 
 
154
/*! \fn const T *QSharedDataPointer::operator->() const
 
155
 
 
156
    \overload
 
157
 
 
158
    This function does not call detach().
 
159
*/
 
160
 
 
161
/*! \fn QSharedDataPointer::operator T *()
 
162
 
 
163
    Returns a pointer to the shared object.
 
164
 
 
165
    This function does a detach().
 
166
 
 
167
    \sa data(), constData()
 
168
*/
 
169
 
 
170
/*! \fn QSharedDataPointer::operator const T *() const
 
171
 
 
172
    Returns a pointer to the shared object.
 
173
 
 
174
    This function does not call detach().
 
175
*/
 
176
 
 
177
/*! \fn T * QSharedDataPointer::data()
 
178
 
 
179
    Returns a pointer to the shared object.
 
180
 
 
181
    This function does a detach().
 
182
 
 
183
    \sa constData()
 
184
*/
 
185
 
 
186
/*! \fn const T * QSharedDataPointer::data() const
 
187
 
 
188
    \overload
 
189
 
 
190
    This function does not call detach().
 
191
*/
 
192
 
 
193
/*! \fn const T * QSharedDataPointer::constData() const
 
194
 
 
195
    Returns a const pointer to the shared object.
 
196
 
 
197
    This function does not call detach().
 
198
 
 
199
    \sa data()
 
200
*/
 
201
 
 
202
/*! \fn bool QSharedDataPointer::operator==(const QSharedDataPointer<T> &other) const
 
203
 
 
204
    Returns a true if the pointer to the shared object in \a other is equal to
 
205
    to the pointer to the shared data in this else returns false.
 
206
 
 
207
    This function does not call detach().
 
208
*/
 
209
 
 
210
/*! \fn bool QSharedDataPointer::operator!=(const QSharedDataPointer<T> &other) const
 
211
 
 
212
    Returns a true if the pointer to the shared object in \a other is not equal to
 
213
    to the pointer to the shared data in this else returns false.
 
214
 
 
215
    This function does not call detach().
 
216
*/
 
217
 
 
218
/*! \fn QSharedDataPointer::QSharedDataPointer()
 
219
 
 
220
    Constructs a QSharedDataPointer initialized with a null pointer.
 
221
*/
 
222
 
 
223
/*! \fn QSharedDataPointer::~QSharedDataPointer()
 
224
 
 
225
    Destroys the QSharedDataPointer.
 
226
 
 
227
    This function automatically decrements the reference count of the
 
228
    shared object and deletes the object if the reference count
 
229
    reaches 0.
 
230
*/
 
231
 
 
232
/*! \fn QSharedDataPointer::QSharedDataPointer(T *sharedData)
 
233
 
 
234
    Constructs a QSharedDataPointer that points to \a sharedData.
 
235
 
 
236
    This function automatically increments \a{sharedData}'s reference
 
237
    count.
 
238
*/
 
239
 
 
240
/*! \fn QSharedDataPointer::QSharedDataPointer(const QSharedDataPointer &other)
 
241
 
 
242
    Constructs a copy of \a other.
 
243
 
 
244
    This function automatically increments the reference count of the
 
245
    shared data object pointed to by \a{other}.
 
246
*/
 
247
 
 
248
/*! \fn QSharedDataPointer &QSharedDataPointer::operator=(const QSharedDataPointer &other)
 
249
 
 
250
    Assigns \a other to this pointer.
 
251
 
 
252
    This function automatically increments the reference count of the
 
253
    shared data object pointed to by \a{other}, and decrements the
 
254
    reference count of the object previously pointed to by this
 
255
    QSharedDataPointer. If the reference count reaches 0, the shared
 
256
    data object is deleted.
 
257
*/
 
258
 
 
259
/*! \fn QSharedDataPointer &QSharedDataPointer::operator=(T *sharedData)
 
260
 
 
261
    \overload
 
262
 
 
263
    Sets this QSharedDataPointer to point to \a sharedData.
 
264
 
 
265
    This function automatically increments \a{sharedData}'s reference
 
266
    count, and decrements the reference count of the object
 
267
    previously pointed to by this QSharedDataPointer. If the
 
268
    reference count reaches 0, the shared data object is deleted.
 
269
*/
 
270
 
 
271
/*! \fn bool QSharedDataPointer::operator!() const
 
272
 
 
273
    Returns true if this pointer is null; otherwise returns false.
 
274
*/
 
275
 
 
276
/*! \fn void QSharedDataPointer::detach()
 
277
 
 
278
    If the shared data's reference count is greater than 1, creates a
 
279
    deep copy of the shared data.
 
280
 
 
281
    This function is automatically called by QSharedDataPointer when
 
282
    necessary. You should never need to call it yourself.
 
283
*/