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

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