1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include <qshareddata.h>
5
6QT_BEGIN_NAMESPACE
7
8/*!
9 \class QSharedData
10 \inmodule QtCore
11 \brief The QSharedData class is a base class for shared data objects.
12 \reentrant
13
14 QSharedData is designed to be used with QSharedDataPointer or
15 QExplicitlySharedDataPointer to implement custom \l{implicitly
16 shared} or explicitly shared classes. QSharedData provides
17 \l{thread-safe} reference counting.
18
19 See QSharedDataPointer and QExplicitlySharedDataPointer for details.
20*/
21
22/*! \fn QSharedData::QSharedData()
23 Constructs a QSharedData object with a reference count of 0.
24*/
25
26/*! \fn QSharedData::QSharedData(const QSharedData& )
27 Constructs a QSharedData object with reference count 0.
28 The parameter is ignored.
29*/
30
31/*!
32 \class QAdoptSharedDataTag
33 \inmodule QtCore
34 \threadsafe
35 \brief The QAdoptSharedDataTag is a helper tag class.
36 \since 6.0
37
38 QAdoptSharedDataTag objects are used in QSharedDataPointer
39 and QExplicitlySharedDataPointer to adopt a pointer to
40 shared data.
41
42 See QSharedDataPointer and QExplicitlySharedDataPointer for details.
43*/
44
45/*!
46 \class QSharedDataPointer
47 \inmodule QtCore
48 \brief The QSharedDataPointer class represents a pointer to an implicitly shared object.
49 \since 4.0
50 \reentrant
51
52 \compares strong
53 \compareswith strong T* std::nullptr_t
54 \endcompareswith
55
56 QSharedDataPointer\<T\> makes writing your own \l {implicitly
57 shared} classes easy. QSharedDataPointer implements \l {thread-safe}
58 reference counting, ensuring that adding QSharedDataPointers to your
59 \l {reentrant} classes won't make them non-reentrant.
60
61 \l {Implicit sharing} is used by many Qt classes to combine the
62 speed and memory efficiency of pointers with the ease of use of
63 classes. See the \l{Shared Classes} page for more information.
64
65 \target Employee example
66 Suppose you want to make an \c Employee class implicitly shared. The
67 procedure is:
68
69 \list
70
71 \li Define the class \c Employee to have a single data member of
72 type \c {QSharedDataPointer<EmployeeData>}.
73
74 \li Define the \c EmployeeData class derived from \l QSharedData to
75 contain all the data members you would normally have put in the
76 \c Employee class.
77
78 \endlist
79
80 To show this in practice, we review the source code for the
81 implicitly shared \c Employee class. In the header file we define the
82 two classes \c Employee and \c EmployeeData.
83
84 \snippet sharedemployee/employee.h 0
85
86 In class \c Employee, note the single data member, a \e {d pointer}
87 of type \c {QSharedDataPointer<EmployeeData>}. All accesses of
88 employee data must go through the \e {d pointer's} \c
89 {operator->()}. For write accesses, \c {operator->()} will
90 automatically call detach(), which creates a copy of the shared data
91 object if the shared data object's reference count is greater than
92 1. This ensures that writes to one \c Employee object don't affect
93 any other \c Employee objects that share the same \c EmployeeData
94 object.
95
96 Class \c EmployeeData inherits QSharedData, which provides the
97 \e{behind the scenes} reference counter. \c EmployeeData has a default
98 constructor, a copy constructor, and a destructor. Normally, trivial
99 implementations of these are all that is needed in the \e {data}
100 class for an implicitly shared class.
101
102 Implementing the two constructors for class \c Employee is also
103 straightforward. Both create a new instance of \c EmployeeData
104 and assign it to the \e{d pointer} .
105
106 \snippet sharedemployee/employee.h 1
107 \codeline
108 \snippet sharedemployee/employee.h 2
109
110 Note that class \c Employee also has a trivial copy constructor
111 defined, which is not strictly required in this case.
112
113 \snippet sharedemployee/employee.h 7
114
115 The copy constructor is not strictly required here, because class \c
116 EmployeeData is included in the same file as class \c Employee
117 (\c{employee.h}). However, including the private subclass of
118 QSharedData in the same file as the public class containing the
119 QSharedDataPointer is not typical. Normally, the idea is to hide the
120 private subclass of QSharedData from the user by putting it in a
121 separate file which would not be included in the public file. In
122 this case, we would normally put class \c EmployeeData in a separate
123 file, which would \e{not} be included in \c{employee.h}. Instead, we
124 would just predeclare the private subclass \c EmployeeData in \c
125 {employee.h} this way:
126
127 \snippet code/src_corelib_tools_qshareddata.cpp 0
128
129 If we had done it that way here, the copy constructor shown would be
130 required. Since the copy constructor is trivial, you might as well
131 just always include it.
132
133 Behind the scenes, QSharedDataPointer automatically increments the
134 reference count whenever an \c Employee object is copied, assigned,
135 or passed as a parameter. It decrements the reference count whenever
136 an \c Employee object is deleted or goes out of scope. The shared
137 \c EmployeeData object is deleted automatically if and when the
138 reference count reaches 0.
139
140 In a non-const member function of \c Employee, whenever the \e {d
141 pointer} is dereferenced, QSharedDataPointer automatically calls
142 detach() to ensure that the function operates on its own copy of the
143 data.
144
145 \snippet sharedemployee/employee.h 3
146 \codeline
147 \snippet sharedemployee/employee.h 4
148
149 Note that if detach() is called more than once in a member function
150 due to multiple dereferences of the \e {d pointer}, detach() will
151 only create a copy of the shared data the first time it is called,
152 if at all, because on the second and subsequent calls of detach(),
153 the reference count will be 1 again.
154
155 But note that in the second \c Employee constructor, which takes an
156 employee ID and a name, both setId() and setName() are called, but
157 they don't cause \e{copy on write}, because the reference count for
158 the newly constructed \c EmployeeData object has just been set to 1.
159
160 In \c Employee's \e const member functions, dereferencing the \e {d
161 pointer} does \e not cause detach() to be called.
162
163 \snippet sharedemployee/employee.h 5
164 \codeline
165 \snippet sharedemployee/employee.h 6
166
167 Notice that there is no need to implement a copy constructor or an
168 assignment operator for the \c Employee class, because the copy
169 constructor and assignment operator provided by the C++ compiler
170 will do the \e{member by member} shallow copy required. The only
171 member to copy is the \e {d pointer}, which is a QSharedDataPointer,
172 whose \c {operator=()} just increments the reference count of the
173 shared \c EmployeeData object.
174
175 \target Implicit vs Explicit Sharing
176 \section1 Implicit vs Explicit Sharing
177
178 Implicit sharing might not be right for the \c Employee class.
179 Consider a simple example that creates two instances of the
180 implicitly shared \c Employee class.
181
182 \snippet sharedemployee/main.cpp 0
183
184 After the second employee e2 is created and e1 is assigned to it,
185 both \c e1 and \c e2 refer to Albrecht Durer, employee 1001. Both \c
186 Employee objects point to the same instance of \c EmployeeData,
187 which has reference count 2. Then \c {e1.setName("Hans Holbein")} is
188 called to change the employee name, but because the reference count
189 is greater than 1, a \e{copy on write} is performed before the name
190 is changed. Now \c e1 and \c e2 point to different \c EmployeeData
191 objects. They have different names, but both have ID 1001, which is
192 probably not what you want. You can, of course, just continue with
193 \c {e1.setId(1002)}, if you really mean to create a second, unique
194 employee, but if you only want to change the employee's name
195 everywhere, consider using \l {QExplicitlySharedDataPointer}
196 {explicit sharing} in the \c Employee class instead of implicit
197 sharing.
198
199 If you declare the \e {d pointer} in the \c Employee class to be
200 \c {QExplicitlySharedDataPointer<EmployeeData>}, then explicit
201 sharing is used and \e{copy on write} operations are not performed
202 automatically (i.e. detach() is not called in non-const
203 functions). In that case, after \c {e1.setName("Hans Holbein")}, the
204 employee's name has been changed, but both e1 and e2 still refer to
205 the same instance of \c EmployeeData, so there is only one employee
206 with ID 1001.
207
208 In the member function documentation, \e{d pointer} always refers
209 to the internal pointer to the shared data object.
210
211 \section1 Optimize Performance for Usage in Qt Containers
212
213 You should consider marking your implicitly shared class as a movable type
214 using the Q_DECLARE_TYPEINFO() macro if it resembles the \c Employee class
215 above and uses a QSharedDataPointer or QExplicitlySharedDataPointer as the
216 only member. This can improve performance and memory efficiency when using
217 Qt's \l{container classes}.
218
219 \sa QSharedData, QExplicitlySharedDataPointer, QScopedPointer, QSharedPointer
220*/
221
222/*! \typedef QSharedDataPointer::Type
223 This is the type of the shared data object. The \e{d pointer}
224 points to an object of this type.
225 */
226
227/*! \typedef QSharedDataPointer::pointer
228 \internal
229 */
230
231/*! \fn template <class T> T& QSharedDataPointer<T>::operator*()
232 Provides access to the shared data object's members.
233 This function calls detach().
234*/
235
236/*! \fn template <class T> const T& QSharedDataPointer<T>::operator*() const
237 Provides const access to the shared data object's members.
238 This function does \e not call detach().
239*/
240
241/*! \fn template <class T> T* QSharedDataPointer<T>::operator->()
242 Provides access to the shared data object's members.
243 This function calls detach().
244*/
245
246/*! \fn template <class T> const T* QSharedDataPointer<T>::operator->() const
247 Provides const access to the shared data object's members.
248 This function does \e not call detach().
249*/
250
251/*! \fn template <class T> QSharedDataPointer<T>::operator T*()
252 Returns a pointer to the shared data object.
253 This function calls detach().
254
255 \sa data(), constData()
256*/
257
258/*! \fn template <class T> QSharedDataPointer<T>::operator const T*() const
259 Returns a pointer to the shared data object.
260 This function does \e not call detach().
261*/
262
263/*! \fn template <class T> T* QSharedDataPointer<T>::data()
264 Returns a pointer to the shared data object.
265 This function calls detach().
266
267 \sa constData()
268*/
269
270/*! \fn template <class T> T* QSharedDataPointer<T>::get()
271 \since 6.0
272
273 Same as data(). This function is provided for STL compatibility.
274*/
275
276/*! \fn template <class T> const T* QSharedDataPointer<T>::data() const
277 Returns a pointer to the shared data object.
278 This function does \e not call detach().
279*/
280
281/*! \fn template <class T> const T* QSharedDataPointer<T>::get() const
282 \since 6.0
283
284 Same as data(). This function is provided for STL compatibility.
285*/
286
287/*! \fn template <class T> const T* QSharedDataPointer<T>::take()
288 \since 6.0
289
290 Returns a pointer to the shared object, and resets \e this to be \nullptr.
291 (That is, this function sets the \e{d pointer} of \e this to \nullptr.)
292
293 \note The reference count of the returned object will \b{not} be
294 decremented. This function can be used together with the
295 constructor that takes a QAdoptSharedDataTag tag object to transfer
296 the shared data object without intervening atomic operations.
297*/
298
299/*! \fn template <class T> const T* QSharedDataPointer<T>::constData() const
300 Returns a const pointer to the shared data object.
301 This function does \e not call detach().
302
303 \sa data()
304*/
305
306/*! \fn template <class T> void QSharedDataPointer<T>::reset(T *ptr = nullptr)
307 \since 6.0
308
309 Sets the \e{d pointer} of \e this to \a ptr and increments \a{ptr}'s reference
310 count if \a ptr is not \nullptr.
311 The reference count of the old shared data object is decremented,
312 and the object deleted if the reference count reaches 0.
313 */
314
315/*! \fn template <class T> void QSharedDataPointer<T>::swap(QSharedDataPointer &other)
316 \memberswap{shared data pointer}
317 */
318
319/*!
320 \fn template <class T> QSharedDataPointer<T> &QSharedDataPointer<T>::operator=(QSharedDataPointer<T> &&other)
321
322 Move-assigns \a other to this QSharedDataPointer instance.
323
324 \since 5.2
325*/
326
327/*! \fn template <class T> bool QSharedDataPointer<T>::operator==(const QSharedDataPointer<T>& lhs, const QSharedDataPointer<T>& rhs)
328 Returns \c true if \a lhs and \a rhs have the same \e{d pointer}.
329 This function does \e not call detach().
330*/
331
332/*! \fn template <class T> bool QSharedDataPointer<T>::operator!=(const QSharedDataPointer<T>& lhs, const QSharedDataPointer<T>& rhs)
333 Returns \c true if \a lhs and \a rhs do \e not have the same
334 \e{d pointer}. This function does \e not call detach().
335*/
336
337/*! \fn template <class T> bool QSharedDataPointer<T>::operator==(T* const &lhs, const QSharedDataPointer<T>& rhs)
338 Returns \c true if the \e{d pointer} of \a rhs is \a lhs.
339 This function does \e not call detach().
340*/
341
342/*! \fn template <class T> bool QSharedDataPointer<T>::operator!=(T* const &lhs, const QSharedDataPointer<T>& rhs)
343 Returns \c true if the \e{d pointer} of \a rhs is \e not \a lhs.
344 \e{d pointer}. This function does \e not call detach().
345*/
346
347/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer()
348 Constructs a QSharedDataPointer initialized with \nullptr as \e{d pointer}.
349*/
350
351/*!
352 \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(QSharedDataPointer &&o)
353
354 Move-constructs a QSharedDataPointer instance, making it point at the same
355 object that \a o was pointing to.
356
357 \since 5.2
358*/
359
360/*! \fn template <class T> QSharedDataPointer<T>::~QSharedDataPointer()
361 Decrements the reference count of the shared data object.
362 If the reference count becomes 0, the shared data object
363 is deleted. \e This is then destroyed.
364*/
365
366/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(T* data)
367 Constructs a QSharedDataPointer with \e{d pointer} set to
368 \a data and increments \a{data}'s reference count.
369*/
370
371/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(T* data, QAdoptSharedDataTag)
372 \since 6.0
373 Constructs a QSharedDataPointer with \e{d pointer} set to
374 \a data. \a data's reference counter is \b{not} incremented;
375 this can be used to adopt pointers obtained from take().
376
377 \sa take()
378*/
379
380/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(const QSharedDataPointer<T>& o)
381 Sets the \e{d pointer} of \e this to the \e{d pointer} in
382 \a o and increments the reference count of the shared
383 data object.
384*/
385
386/*! \fn template <class T> QSharedDataPointer<T>& QSharedDataPointer<T>::operator=(const QSharedDataPointer<T>& o)
387 Sets the \e{d pointer} of \e this to the \e{d pointer} of
388 \a o and increments the reference count of the shared
389 data object. The reference count of the old shared data
390 object of \e this is decremented. If the reference count
391 of the old shared data object becomes 0, the old shared
392 data object is deleted.
393*/
394
395/*! \fn template <class T> QSharedDataPointer& QSharedDataPointer<T>::operator=(T* o)
396 Sets the \e{d pointer} og \e this to \a o and increments
397 \a{o}'s reference count. The reference count of the old
398 shared data object of \e this is decremented. If the reference
399 count of the old shared data object becomes 0, the old shared data
400 object is deleted.
401*/
402
403/*! \fn template <class T> bool QSharedDataPointer<T>::operator!() const
404 Returns \c true if the \e{d pointer} of \e this is \nullptr.
405*/
406
407/*! \fn template <class T> void QSharedDataPointer<T>::detach()
408 If the shared data object's reference count is greater than 1, this
409 function creates a deep copy of the shared data object and sets the
410 \e{d pointer} of \e this to the copy.
411
412 This function is called automatically by non-const member
413 functions of QSharedDataPointer if \e{copy on write} is
414 required. You don't need to call it yourself.
415*/
416
417/*! \fn template <class T> T *QSharedDataPointer<T>::clone()
418 \since 4.5
419
420 Creates and returns a deep copy of the current data. This function
421 is called by detach() when the reference count is greater than 1 in
422 order to create the new copy. This function uses the \e {operator
423 new} and calls the copy constructor of the type T.
424
425 This function is provided so that you may support "virtual copy
426 constructors" for your own types. In order to so, you should declare
427 a template-specialization of this function for your own type, like
428 the example below:
429
430 \snippet code/src_corelib_tools_qshareddata.cpp 1
431
432 In the example above, the template specialization for the clone()
433 function calls the \e {EmployeeData::clone()} virtual function. A
434 class derived from EmployeeData could override that function and
435 return the proper polymorphic type.
436*/
437
438/*!
439 \class QExplicitlySharedDataPointer
440 \inmodule QtCore
441 \brief The QExplicitlySharedDataPointer class represents a pointer to an explicitly shared object.
442 \since 4.4
443 \reentrant
444
445 \compares strong
446 \compareswith strong T* std::nullptr_t
447 \endcompareswith
448
449 QExplicitlySharedDataPointer\<T\> makes writing your own explicitly
450 shared classes easy. QExplicitlySharedDataPointer implements
451 \l {thread-safe} reference counting, ensuring that adding
452 QExplicitlySharedDataPointers to your \l {reentrant} classes won't
453 make them non-reentrant.
454
455 Except for one big difference, QExplicitlySharedDataPointer is just
456 like QSharedDataPointer. The big difference is that member functions
457 of QExplicitlySharedDataPointer \e{do not} do the automatic
458 \e{copy on write} operation (detach()) that non-const members of
459 QSharedDataPointer do before allowing the shared data object to be
460 modified. There is a detach() function available, but if you really
461 want to detach(), you have to call it yourself. This means that
462 QExplicitlySharedDataPointers behave like regular C++ pointers,
463 except that by doing reference counting and not deleting the shared
464 data object until the reference count is 0, they avoid the dangling
465 pointer problem.
466
467 It is instructive to compare QExplicitlySharedDataPointer with
468 QSharedDataPointer by way of an example. Consider the \l {Employee
469 example} in QSharedDataPointer, modified to use explicit sharing as
470 explained in the discussion \l {Implicit vs Explicit Sharing}.
471
472 Note that if you use this class but find you are calling detach() a
473 lot, you probably should be using QSharedDataPointer instead.
474
475 In the member function documentation, \e{d pointer} always refers
476 to the internal pointer to the shared data object.
477
478 \sa QSharedData, QSharedDataPointer
479*/
480
481/*! \fn template <class T> T& QExplicitlySharedDataPointer<T>::operator*() const
482 Provides access to the shared data object's members.
483*/
484
485/*! \fn template <class T> T* QExplicitlySharedDataPointer<T>::operator->()
486 Provides access to the shared data object's members.
487*/
488
489/*! \fn template <class T> const T* QExplicitlySharedDataPointer<T>::operator->() const
490 Provides const access to the shared data object's members.
491*/
492
493/*! \fn template <class T> T* QExplicitlySharedDataPointer<T>::data() const
494 Returns a pointer to the shared data object.
495*/
496
497/*! \fn template <class T> T* QExplicitlySharedDataPointer<T>::get() const
498 \since 6.0
499
500 Same as data(). This function is provided for STL compatibility.
501*/
502
503/*! \fn template <class T> const T* QExplicitlySharedDataPointer<T>::constData() const
504 Returns a const pointer to the shared data object.
505
506 \sa data()
507*/
508
509/*! \fn template <class T> void QExplicitlySharedDataPointer<T>::swap(QExplicitlySharedDataPointer &other)
510 \memberswap{explicitly-shared data pointer}
511 */
512
513/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator==(const QExplicitlySharedDataPointer<T>& lhs, const QExplicitlySharedDataPointer<T>& rhs)
514 Returns \c true if \a lhs and \a rhs have the same \e{d pointer}.
515*/
516
517/*!
518 \fn template <class T> QExplicitlySharedDataPointer<T> &QExplicitlySharedDataPointer<T>::operator=(QExplicitlySharedDataPointer<T> &&other)
519
520 Move-assigns \a other to this QExplicitlySharedDataPointer instance.
521
522 \since 5.2
523*/
524
525/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator==(const T* const &lhs, const QExplicitlySharedDataPointer<T>& rhs)
526 Returns \c true if the \e{d pointer} of \a rhs is \a lhs.
527 */
528
529/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator!=(const QExplicitlySharedDataPointer<T>& lhs, const QExplicitlySharedDataPointer<T>& rhs)
530 Returns \c true if \a lhs and \a rhs do \e not have the same
531 \e{d pointer}.
532*/
533
534/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator!=(const T* const &lhs, const QExplicitlySharedDataPointer<T>& rhs)
535 Returns \c true if the \e{d pointer} of \a rhs is \e not \a lhs.
536 */
537
538/*! \fn template <class T> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer()
539 Constructs a QExplicitlySharedDataPointer initialized with \nullptr
540 as \e{d pointer}.
541*/
542
543/*! \fn template <class T> QExplicitlySharedDataPointer<T>::~QExplicitlySharedDataPointer()
544 Decrements the reference count of the shared data object.
545 If the reference count becomes 0, the shared data object
546 is deleted. \e This is then destroyed.
547*/
548
549/*!
550 \fn template <class T> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer(QExplicitlySharedDataPointer &&o)
551
552 Move-constructs a QExplicitlySharedDataPointer instance, making it point at the same
553 object that \a o was pointing to.
554
555 \since 5.2
556*/
557
558/*! \fn template <class T> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer(T* data)
559 Constructs a QExplicitlySharedDataPointer with \e{d pointer}
560 set to \a data and increments \a{data}'s reference
561 count.
562*/
563
564/*! \fn template <class T> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer(const QExplicitlySharedDataPointer<T>& o)
565 This standard copy constructor sets the \e {d pointer} of \e this to
566 the \e {d pointer} in \a o and increments the reference count of
567 the shared data object.
568*/
569
570/*! \fn template <class T> template <class X> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer(const QExplicitlySharedDataPointer<X>& o)
571 This copy constructor is different in that it allows \a o to be
572 a different type of explicitly shared data pointer but one that has
573 a compatible shared data object.
574
575 By default, the \e{d pointer} of \a o (of type \c{X *}) gets
576 implicitly converted to the type \c{T *}; the result of this
577 conversion is set as the \e{d pointer} of \e{this}, and the
578 reference count of the shared data object is incremented.
579*/
580
581/*! \fn template <class T> QExplicitlySharedDataPointer<T>& QExplicitlySharedDataPointer<T>::operator=(const QExplicitlySharedDataPointer<T>& o)
582 Sets the \e{d pointer} of \e this to the \e{d pointer} of
583 \a o and increments the reference count of the shared
584 data object. The reference count of the old shared data
585 object of \e this is decremented. If the reference count
586 of the old shared data object becomes 0, the old shared
587 data object is deleted.
588*/
589
590/*! \fn template <class T> QExplicitlySharedDataPointer& QExplicitlySharedDataPointer<T>::operator=(T* o)
591 Sets the \e{d pointer} of \e this to \a o and
592 increments \a{o}'s reference count. The reference
593 count of the old shared data object of \e this is decremented.
594 If the reference count of the old shared data object becomes
595 0, the old shared data object is deleted.
596*/
597
598/*! \fn template <class T> void QExplicitlySharedDataPointer<T>::reset(T *ptr = nullptr)
599 \since 6.0
600
601 Sets the \e{d pointer} of \e this to \a ptr and increments \a{ptr}'s reference
602 count if \a ptr is not \nullptr.
603 The reference count of the old shared data object is decremented,
604 and the object deleted if the reference count reaches 0.
605 */
606
607/*! \fn template <class T> T *QExplicitlySharedDataPointer<T>::take()
608 \since 5.12
609
610 Returns a pointer to the shared object, and resets \e this to be \nullptr.
611 (That is, this function sets the \e{d pointer} of \e this to \nullptr.)
612
613 \note The reference count of the returned object will \b{not} be
614 decremented. This function can be used together with the
615 constructor that takes a QAdoptSharedDataTag tag object to transfer
616 the shared data object without intervening atomic operations.
617 */
618
619/*! \fn template <class T> QExplicitlySharedDataPointer<T>::operator bool () const
620 Returns \c true if the \e{d pointer} of \e this is \e not null.
621 */
622
623/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator!() const
624 Returns \c true if the \e{d pointer} of \e this is \nullptr.
625*/
626
627/*! \fn template <class T> void QExplicitlySharedDataPointer<T>::detach()
628 If the shared data object's reference count is greater than 1, this
629 function creates a deep copy of the shared data object and sets the
630 \e{d pointer} of \e this to the copy.
631
632 Because QExplicitlySharedDataPointer does not do the automatic
633 \e{copy on write} operations that members of QSharedDataPointer do,
634 detach() is \e not called automatically anywhere in the member
635 functions of this class. If you find that you are calling detach()
636 everywhere in your code, consider using QSharedDataPointer instead.
637*/
638
639/*! \fn template <class T> T *QExplicitlySharedDataPointer<T>::clone()
640 \since 4.5
641
642 Creates and returns a deep copy of the current data. This function
643 is called by detach() when the reference count is greater than 1 in
644 order to create the new copy. This function uses the \e {operator
645 new} and calls the copy constructor of the type T.
646
647 See QSharedDataPointer<T>::clone() for an explanation of how to use it.
648*/
649
650/*!
651 \typedef QExplicitlySharedDataPointer::Type
652
653 This is the type of the shared data object. The \e{d pointer}
654 points to an object of this type.
655*/
656
657/*! \typedef QExplicitlySharedDataPointer::pointer
658 \internal
659 */
660
661QT_END_NAMESPACE
662

source code of qtbase/src/corelib/tools/qshareddata.cpp