1 /****************************************************************************
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
6 ** This file is part of the QtCore module of the Qt Toolkit.
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 Digia. For licensing terms and
14 ** conditions see http://qt.digia.com/licensing. For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
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 2.1 as published by the Free Software
20 ** Foundation and appearing in the file LICENSE.LGPL included in the
21 ** packaging of this file. Please review the following information to
22 ** ensure the GNU Lesser General Public License version 2.1 requirements
23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 ** In addition, as a special exception, Digia gives you certain additional
26 ** rights. These rights are described in the Digia Qt LGPL Exception
27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 ** GNU General Public License Usage
30 ** Alternatively, this file may be used under the terms of the GNU
31 ** General Public License version 3.0 as published by the Free Software
32 ** Foundation and appearing in the file LICENSE.GPL included in the
33 ** packaging of this file. Please review the following information to
34 ** ensure the GNU General Public License version 3.0 requirements will be
35 ** met: http://www.gnu.org/copyleft/gpl.html.
40 ****************************************************************************/
42 #include <qshareddata.h>
49 \brief The QSharedData class is a base class for shared data objects.
52 QSharedData is designed to be used with QSharedDataPointer or
53 QExplicitlySharedDataPointer to implement custom \l{implicitly
54 shared} or explicitly shared classes. QSharedData provides
55 \l{thread-safe} reference counting.
57 See QSharedDataPointer and QExplicitlySharedDataPointer for details.
60 /*! \fn QSharedData::QSharedData()
61 Constructs a QSharedData object with a reference count of 0.
64 /*! \fn QSharedData::QSharedData(const QSharedData& other)
65 Constructs a QSharedData object with reference count 0.
70 \class QSharedDataPointer
72 \brief The QSharedDataPointer class represents a pointer to an implicitly shared object.
76 QSharedDataPointer\<T\> makes writing your own \l {implicitly
77 shared} classes easy. QSharedDataPointer implements \l {thread-safe}
78 reference counting, ensuring that adding QSharedDataPointers to your
79 \l {reentrant} classes won't make them non-reentrant.
81 \l {Implicit sharing} is used by many Qt classes to combine the
82 speed and memory efficiency of pointers with the ease of use of
83 classes. See the \l{Shared Classes} page for more information.
85 \target Employee example
86 Suppose you want to make an \c Employee class implicitly shared. The
91 \li Define the class \c Employee to have a single data member of
92 type \c {QSharedDataPointer<EmployeeData>}.
94 \li Define the \c EmployeeData class derived from \l QSharedData to
95 contain all the data members you would normally have put in the
100 To show this in practice, we review the source code for the
101 implicitly shared \c Employee class. In the header file we define the
102 two classes \c Employee and \c EmployeeData.
104 \snippet sharedemployee/employee.h 0
106 In class \c Employee, note the single data member, a \e {d pointer}
107 of type \c {QSharedDataPointer<EmployeeData>}. All accesses of
108 employee data must go through the \e {d pointer's} \c
109 {operator->()}. For write accesses, \c {operator->()} will
110 automatically call detach(), which creates a copy of the shared data
111 object if the shared data object's reference count is greater than
112 1. This ensures that writes to one \c Employee object don't affect
113 any other \c Employee objects that share the same \c EmployeeData
116 Class \c EmployeeData inherits QSharedData, which provides the
117 \e{behind the scenes} reference counter. \c EmployeeData has a default
118 constructor, a copy constructor, and a destructor. Normally, trivial
119 implementations of these are all that is needed in the \e {data}
120 class for an implicitly shared class.
122 Implementing the two constructors for class \c Employee is also
123 straightforward. Both create a new instance of \c EmployeeData
124 and assign it to the \e{d pointer} .
126 \snippet sharedemployee/employee.h 1
128 \snippet sharedemployee/employee.h 2
130 Note that class \c Employee also has a trivial copy constructor
131 defined, which is not strictly required in this case.
133 \snippet sharedemployee/employee.h 7
135 The copy constructor is not strictly required here, because class \c
136 EmployeeData is included in the same file as class \c Employee
137 (\c{employee.h}). However, including the private subclass of
138 QSharedData in the same file as the public class containing the
139 QSharedDataPointer is not typical. Normally, the idea is to hide the
140 private subclass of QSharedData from the user by putting it in a
141 separate file which would not be included in the public file. In
142 this case, we would normally put class \c EmployeeData in a separate
143 file, which would \e{not} be included in \c{employee.h}. Instead, we
144 would just predeclare the private subclass \c EmployeeData in \c
145 {employee.h} this way:
151 If we had done it that way here, the copy constructor shown would be
152 required. Since the copy constructor is trivial, you might as well
153 just always include it.
155 Behind the scenes, QSharedDataPointer automatically increments the
156 reference count whenever an \c Employee object is copied, assigned,
157 or passed as a parameter. It decrements the reference count whenever
158 an \c Employee object is deleted or goes out of scope. The shared
159 \c EmployeeData object is deleted automatically if and when the
160 reference count reaches 0.
162 In a non-const member function of \c Employee, whenever the \e {d
163 pointer} is dereferenced, QSharedDataPointer automatically calls
164 detach() to ensure that the function operates on its own copy of the
167 \snippet sharedemployee/employee.h 3
169 \snippet sharedemployee/employee.h 4
171 Note that if detach() is called more than once in a member function
172 due to multiple dereferences of the \e {d pointer}, detach() will
173 only create a copy of the shared data the first time it is called,
174 if at all, because on the second and subsequent calls of detach(),
175 the reference count will be 1 again.
177 But note that in the second \c Employee constructor, which takes an
178 employee ID and a name, both setId() and setName() are called, but
179 they don't cause \e{copy on write}, because the reference count for
180 the newly constructed \c EmployeeData object has just been set to 1.
182 In \c Employee's \e const member functions, dereferencing the \e {d
183 pointer} does \e not cause detach() to be called.
185 \snippet sharedemployee/employee.h 5
187 \snippet sharedemployee/employee.h 6
189 Notice that there is no need to implement a copy constructor or an
190 assignment operator for the \c Employee class, because the copy
191 constructor and assignment operator provided by the C++ compiler
192 will do the \e{member by member} shallow copy required. The only
193 member to copy is the \e {d pointer}, which is a QSharedDataPointer,
194 whose \c {operator=()} just increments the reference count of the
195 shared \c EmployeeData object.
197 \target Implicit vs Explicit Sharing
198 \section1 Implicit vs Explicit Sharing
200 Implicit sharing might not be right for the \c Employee class.
201 Consider a simple example that creates two instances of the
202 implicitly shared \c Employee class.
204 \snippet sharedemployee/main.cpp 0
206 After the second employee e2 is created and e1 is assigned to it,
207 both \c e1 and \c e2 refer to Albrecht Durer, employee 1001. Both \c
208 Employee objects point to the same instance of \c EmployeeData,
209 which has reference count 2. Then \c {e1.setName("Hans Holbein")} is
210 called to change the employee name, but because the reference count
211 is greater than 1, a \e{copy on write} is performed before the name
212 is changed. Now \c e1 and \c e2 point to different \c EmployeeData
213 objects. They have different names, but both have ID 1001, which is
214 probably not what you want. You can, of course, just continue with
215 \c {e1.setId(1002)}, if you really mean to create a second, unique
216 employee, but if you only want to change the employee's name
217 everywhere, consider using \l {QExplicitlySharedDataPointer}
218 {explicit sharing} in the \c Employee class instead of implicit
221 If you declare the \e {d pointer} in the \c Employee class to be
222 \c {QExplicitlySharedDataPointer<EmployeeData>}, then explicit
223 sharing is used and \e{copy on write} operations are not performed
224 automatically (i.e. detach() is not called in non-const
225 functions). In that case, after \c {e1.setName("Hans Holbein")}, the
226 employee's name has been changed, but both e1 and e2 still refer to
227 the same instance of \c EmployeeData, so there is only one employee
230 In the member function documentation, \e{d pointer} always refers
231 to the internal pointer to the shared data object.
233 \section1 Optimize performance for usage in Qt Containers
235 You should consider marking your implicitly shared class as a movable type
236 using the Q_DECLARE_TYPEINFO() macro if it resembles the \c Employee class
237 above and uses a QSharedDataPointer or QExplicitlySharedDataPointer as the
238 only member. This can improve performance and memory efficiency when using
239 Qt's \l{container classes}.
241 \sa QSharedData, QExplicitlySharedDataPointer, QScopedPointer, QSharedPointer
244 /*! \typedef QSharedDataPointer::Type
245 This is the type of the shared data object. The \e{d pointer}
246 points to an object of this type.
249 /*! \typedef QSharedDataPointer::pointer
253 /*! \fn T& QSharedDataPointer::operator*()
254 Provides access to the shared data object's members.
255 This function calls detach().
258 /*! \fn const T& QSharedDataPointer::operator*() const
259 Provides const access to the shared data object's members.
260 This function does \e not call detach().
263 /*! \fn T* QSharedDataPointer::operator->()
264 Provides access to the shared data object's members.
265 This function calls detach().
268 /*! \fn const T* QSharedDataPointer::operator->() const
269 Provides const access to the shared data object's members.
270 This function does \e not call detach().
273 /*! \fn QSharedDataPointer::operator T*()
274 Returns a pointer to the shared data object.
275 This function calls detach().
277 \sa data(), constData()
280 /*! \fn QSharedDataPointer::operator const T*() const
281 Returns a pointer to the shared data object.
282 This function does \e not call detach().
285 /*! \fn T* QSharedDataPointer::data()
286 Returns a pointer to the shared data object.
287 This function calls detach().
292 /*! \fn const T* QSharedDataPointer::data() const
293 Returns a pointer to the shared data object.
294 This function does \e not call detach().
297 /*! \fn const T* QSharedDataPointer::constData() const
298 Returns a const pointer to the shared data object.
299 This function does \e not call detach().
304 /*! \fn void QSharedDataPointer::swap(QSharedDataPointer &other)
305 Swap this instance's shared data pointer with the shared
306 data pointer in \a other.
309 /*! \fn bool QSharedDataPointer::operator==(const QSharedDataPointer<T>& other) const
310 Returns true if \a other and \e this have the same \e{d pointer}.
311 This function does \e not call detach().
314 /*! \fn bool QSharedDataPointer::operator!=(const QSharedDataPointer<T>& other) const
315 Returns true if \a other and \e this do \e not have the same
316 \e{d pointer}. This function does \e not call detach().
319 /*! \fn QSharedDataPointer::QSharedDataPointer()
320 Constructs a QSharedDataPointer initialized with a null \e{d pointer}.
323 /*! \fn QSharedDataPointer::~QSharedDataPointer()
324 Decrements the reference count of the shared data object.
325 If the reference count becomes 0, the shared data object
326 is deleted. \e This is then destroyed.
329 /*! \fn QSharedDataPointer::QSharedDataPointer(T* sharedData)
330 Constructs a QSharedDataPointer with \e{d pointer} set to
331 \a sharedData and increments \a{sharedData}'s reference count.
334 /*! \fn QSharedDataPointer::QSharedDataPointer(const QSharedDataPointer<T>& other)
335 Sets the \e{d pointer} of \e this to the \e{d pointer} in
336 \a other and increments the reference count of the shared
340 /*! \fn QSharedDataPointer<T>& QSharedDataPointer::operator=(const QSharedDataPointer<T>& other)
341 Sets the \e{d pointer} of \e this to the \e{d pointer} of
342 \a other and increments the reference count of the shared
343 data object. The reference count of the old shared data
344 object of \e this is decremented. If the reference count
345 of the old shared data object becomes 0, the old shared
346 data object is deleted.
349 /*! \fn QSharedDataPointer& QSharedDataPointer::operator=(T* sharedData)
350 Sets the \e{d pointer} og \e this to \a sharedData and increments
351 \a{sharedData}'s reference count. The reference count of the old
352 shared data object of \e this is decremented. If the reference
353 count of the old shared data object becomes 0, the old shared data
357 /*! \fn bool QSharedDataPointer::operator!() const
358 Returns true if the \e{d pointer} of \e this is null.
361 /*! \fn void QSharedDataPointer::detach()
362 If the shared data object's reference count is greater than 1, this
363 function creates a deep copy of the shared data object and sets the
364 \e{d pointer} of \e this to the copy.
366 This function is called automatically by non-const member
367 functions of QSharedDataPointer if \e{copy on write} is
368 required. You don't need to call it yourself.
371 /*! \fn T *QSharedDataPointer::clone()
374 Creates and returns a deep copy of the current data. This function
375 is called by detach() when the reference count is greater than 1 in
376 order to create the new copy. This function uses the \e {operator
377 new} and calls the copy constructor of the type T.
379 This function is provided so that you may support "virtual copy
380 constructors" for your own types. In order to so, you should declare
381 a template-specialization of this function for your own type, like
386 EmployeeData *QSharedDataPointer<EmployeeData>::clone()
392 In the example above, the template specialization for the clone()
393 function calls the \e {EmployeeData::clone()} virtual function. A
394 class derived from EmployeeData could override that function and
395 return the proper polymorphic type.
399 \class QExplicitlySharedDataPointer
401 \brief The QExplicitlySharedDataPointer class represents a pointer to an explicitly shared object.
405 QExplicitlySharedDataPointer\<T\> makes writing your own explicitly
406 shared classes easy. QExplicitlySharedDataPointer implements
407 \l {thread-safe} reference counting, ensuring that adding
408 QExplicitlySharedDataPointers to your \l {reentrant} classes won't
409 make them non-reentrant.
411 Except for one big difference, QExplicitlySharedDataPointer is just
412 like QSharedDataPointer. The big difference is that member functions
413 of QExplicitlySharedDataPointer \e{do not} do the automatic
414 \e{copy on write} operation (detach()) that non-const members of
415 QSharedDataPointer do before allowing the shared data object to be
416 modified. There is a detach() function available, but if you really
417 want to detach(), you have to call it yourself. This means that
418 QExplicitlySharedDataPointers behave like regular C++ pointers,
419 except that by doing reference counting and not deleting the shared
420 data object until the reference count is 0, they avoid the dangling
423 It is instructive to compare QExplicitlySharedDataPointer with
424 QSharedDataPointer by way of an example. Consider the \l {Employee
425 example} in QSharedDataPointer, modified to use explicit sharing as
426 explained in the discussion \l {Implicit vs Explicit Sharing}.
428 Note that if you use this class but find you are calling detach() a
429 lot, you probably should be using QSharedDataPointer instead.
431 In the member function documentation, \e{d pointer} always refers
432 to the internal pointer to the shared data object.
434 \sa QSharedData, QSharedDataPointer
437 /*! \fn T& QExplicitlySharedDataPointer::operator*() const
438 Provides access to the shared data object's members.
441 /*! \fn T* QExplicitlySharedDataPointer::operator->()
442 Provides access to the shared data object's members.
445 /*! \fn const T* QExplicitlySharedDataPointer::operator->() const
446 Provides const access to the shared data object's members.
449 /*! \fn T* QExplicitlySharedDataPointer::data() const
450 Returns a pointer to the shared data object.
453 /*! \fn const T* QExplicitlySharedDataPointer::constData() const
454 Returns a const pointer to the shared data object.
459 /*! \fn void QExplicitlySharedDataPointer::swap(QExplicitlySharedDataPointer &other)
460 Swap this instance's explicitly shared data pointer with
461 the explicitly shared data pointer in \a other.
464 /*! \fn bool QExplicitlySharedDataPointer::operator==(const QExplicitlySharedDataPointer<T>& other) const
465 Returns true if \a other and \e this have the same \e{d pointer}.
468 /*! \fn bool QExplicitlySharedDataPointer::operator==(const T* ptr) const
469 Returns true if the \e{d pointer} of \e this is \a ptr.
472 /*! \fn bool QExplicitlySharedDataPointer::operator!=(const QExplicitlySharedDataPointer<T>& other) const
473 Returns true if \a other and \e this do \e not have the same
477 /*! \fn bool QExplicitlySharedDataPointer::operator!=(const T* ptr) const
478 Returns true if the \e{d pointer} of \e this is \e not \a ptr.
481 /*! \fn QExplicitlySharedDataPointer::QExplicitlySharedDataPointer()
482 Constructs a QExplicitlySharedDataPointer initialized with a null
486 /*! \fn QExplicitlySharedDataPointer::~QExplicitlySharedDataPointer()
487 Decrements the reference count of the shared data object.
488 If the reference count becomes 0, the shared data object
489 is deleted. \e This is then destroyed.
492 /*! \fn QExplicitlySharedDataPointer::QExplicitlySharedDataPointer(T* sharedData)
493 Constructs a QExplicitlySharedDataPointer with \e{d pointer}
494 set to \a sharedData and increments \a{sharedData}'s reference
498 /*! \fn QExplicitlySharedDataPointer::QExplicitlySharedDataPointer(const QExplicitlySharedDataPointer<T>& other)
499 This standard copy constructor sets the \e {d pointer} of \e this to
500 the \e {d pointer} in \a other and increments the reference count of
501 the shared data object.
504 /*! \fn QExplicitlySharedDataPointer::QExplicitlySharedDataPointer(const QExplicitlySharedDataPointer<X>& other)
505 This copy constructor is different in that it allows \a other to be
506 a different type of explicitly shared data pointer but one that has
507 a compatible shared data object. It performs a static cast of the
508 \e{d pointer} in \a other and sets the \e {d pointer} of \e this to
509 the converted \e{d pointer}. It increments the reference count of
510 the shared data object.
513 /*! \fn QExplicitlySharedDataPointer<T>& QExplicitlySharedDataPointer::operator=(const QExplicitlySharedDataPointer<T>& other)
514 Sets the \e{d pointer} of \e this to the \e{d pointer} of
515 \a other and increments the reference count of the shared
516 data object. The reference count of the old shared data
517 object of \e this is decremented. If the reference count
518 of the old shared data object becomes 0, the old shared
519 data object is deleted.
522 /*! \fn QExplicitlySharedDataPointer& QExplicitlySharedDataPointer::operator=(T* sharedData)
523 Sets the \e{d pointer} of \e this to \a sharedData and
524 increments \a{sharedData}'s reference count. The reference
525 count of the old shared data object of \e this is decremented.
526 If the reference count of the old shared data object becomes
527 0, the old shared data object is deleted.
530 /*! \fn void QExplicitlySharedDataPointer::reset()
531 Resets \e this to be null. i.e., this function sets the
532 \e{d pointer} of \e this to 0, but first it decrements
533 the reference count of the shared data object and deletes
534 the shared data object if the reference count became 0.
537 /*! \fn QExplicitlySharedDataPointer::operator bool () const
538 Returns true if the \e{d pointer} of \e this is \e not null.
541 /*! \fn bool QExplicitlySharedDataPointer::operator!() const
542 Returns true if the \e{d pointer} of \e this is null.
545 /*! \fn void QExplicitlySharedDataPointer::detach()
546 If the shared data object's reference count is greater than 1, this
547 function creates a deep copy of the shared data object and sets the
548 \e{d pointer} of \e this to the copy.
550 Because QExplicitlySharedDataPointer does not do the automatic
551 \e{copy on write} operations that members of QSharedDataPointer do,
552 detach() is \e not called automatically anywhere in the member
553 functions of this class. If you find that you are calling detach()
554 everywhere in your code, consider using QSharedDataPointer instead.
557 /*! \fn T *QExplicitlySharedDataPointer::clone()
560 Creates and returns a deep copy of the current data. This function
561 is called by detach() when the reference count is greater than 1 in
562 order to create the new copy. This function uses the \e {operator
563 new} and calls the copy constructor of the type T.
565 See QSharedDataPointer::clone() for an explanation of how to use it.
569 \typedef QExplicitlySharedDataPointer::Type
571 This is the type of the shared data object. The \e{d pointer}
572 points to an object of this type.
575 /*! \typedef QExplicitlySharedDataPointer::pointer