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