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 \memberswap{shared data pointer}
313 */
314
315/*!
316 \fn template <class T> QSharedDataPointer<T> &QSharedDataPointer<T>::operator=(QSharedDataPointer<T> &&other)
317
318 Move-assigns \a other to this QSharedDataPointer instance.
319
320 \since 5.2
321*/
322
323/*! \fn template <class T> bool QSharedDataPointer<T>::operator==(const QSharedDataPointer<T>& lhs, const QSharedDataPointer<T>& rhs)
324 Returns \c true if \a lhs and \a rhs have the same \e{d pointer}.
325 This function does \e not call detach().
326*/
327
328/*! \fn template <class T> bool QSharedDataPointer<T>::operator!=(const QSharedDataPointer<T>& lhs, const QSharedDataPointer<T>& rhs)
329 Returns \c true if \a lhs and \a rhs do \e not have the same
330 \e{d pointer}. This function does \e not call detach().
331*/
332
333/*! \fn template <class T> bool QSharedDataPointer<T>::operator==(const T *ptr, const QSharedDataPointer<T>& rhs)
334 Returns \c true if the \e{d pointer} of \a rhs is \a ptr.
335 This function does \e not call detach().
336*/
337
338/*! \fn template <class T> bool QSharedDataPointer<T>::operator!=(const T *ptr, const QSharedDataPointer<T>& rhs)
339 Returns \c true if the \e{d pointer} of \a rhs is \e not \a ptr.
340 \e{d pointer}. This function does \e not call detach().
341*/
342
343/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer()
344 Constructs a QSharedDataPointer initialized with \nullptr as \e{d pointer}.
345*/
346
347/*!
348 \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(QSharedDataPointer &&o)
349
350 Move-constructs a QSharedDataPointer instance, making it point at the same
351 object that \a o was pointing to.
352
353 \since 5.2
354*/
355
356/*! \fn template <class T> QSharedDataPointer<T>::~QSharedDataPointer()
357 Decrements the reference count of the shared data object.
358 If the reference count becomes 0, the shared data object
359 is deleted. \e This is then destroyed.
360*/
361
362/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(T* data)
363 Constructs a QSharedDataPointer with \e{d pointer} set to
364 \a data and increments \a{data}'s reference count.
365*/
366
367/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(T* data, QAdoptSharedDataTag)
368 \since 6.0
369 Constructs a QSharedDataPointer with \e{d pointer} set to
370 \a data. \a data's reference counter is \b{not} incremented;
371 this can be used to adopt pointers obtained from take().
372
373 \sa take()
374*/
375
376/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(const QSharedDataPointer<T>& o)
377 Sets the \e{d pointer} of \e this to the \e{d pointer} in
378 \a o and increments the reference count of the shared
379 data object.
380*/
381
382/*! \fn template <class T> QSharedDataPointer<T>& QSharedDataPointer<T>::operator=(const QSharedDataPointer<T>& o)
383 Sets the \e{d pointer} of \e this to the \e{d pointer} of
384 \a o and increments the reference count of the shared
385 data object. The reference count of the old shared data
386 object of \e this is decremented. If the reference count
387 of the old shared data object becomes 0, the old shared
388 data object is deleted.
389*/
390
391/*! \fn template <class T> QSharedDataPointer& QSharedDataPointer<T>::operator=(T* o)
392 Sets the \e{d pointer} og \e this to \a o and increments
393 \a{o}'s reference count. The reference count of the old
394 shared data object of \e this is decremented. If the reference
395 count of the old shared data object becomes 0, the old shared data
396 object is deleted.
397*/
398
399/*! \fn template <class T> bool QSharedDataPointer<T>::operator!() const
400 Returns \c true if the \e{d pointer} of \e this is \nullptr.
401*/
402
403/*! \fn template <class T> void QSharedDataPointer<T>::detach()
404 If the shared data object's reference count is greater than 1, this
405 function creates a deep copy of the shared data object and sets the
406 \e{d pointer} of \e this to the copy.
407
408 This function is called automatically by non-const member
409 functions of QSharedDataPointer if \e{copy on write} is
410 required. You don't need to call it yourself.
411*/
412
413/*! \fn template <class T> T *QSharedDataPointer<T>::clone()
414 \since 4.5
415
416 Creates and returns a deep copy of the current data. This function
417 is called by detach() when the reference count is greater than 1 in
418 order to create the new copy. This function uses the \e {operator
419 new} and calls the copy constructor of the type T.
420
421 This function is provided so that you may support "virtual copy
422 constructors" for your own types. In order to so, you should declare
423 a template-specialization of this function for your own type, like
424 the example below:
425
426 \snippet code/src_corelib_tools_qshareddata.cpp 1
427
428 In the example above, the template specialization for the clone()
429 function calls the \e {EmployeeData::clone()} virtual function. A
430 class derived from EmployeeData could override that function and
431 return the proper polymorphic type.
432*/
433
434/*!
435 \class QExplicitlySharedDataPointer
436 \inmodule QtCore
437 \brief The QExplicitlySharedDataPointer class represents a pointer to an explicitly shared object.
438 \since 4.4
439 \reentrant
440
441 QExplicitlySharedDataPointer\<T\> makes writing your own explicitly
442 shared classes easy. QExplicitlySharedDataPointer implements
443 \l {thread-safe} reference counting, ensuring that adding
444 QExplicitlySharedDataPointers to your \l {reentrant} classes won't
445 make them non-reentrant.
446
447 Except for one big difference, QExplicitlySharedDataPointer is just
448 like QSharedDataPointer. The big difference is that member functions
449 of QExplicitlySharedDataPointer \e{do not} do the automatic
450 \e{copy on write} operation (detach()) that non-const members of
451 QSharedDataPointer do before allowing the shared data object to be
452 modified. There is a detach() function available, but if you really
453 want to detach(), you have to call it yourself. This means that
454 QExplicitlySharedDataPointers behave like regular C++ pointers,
455 except that by doing reference counting and not deleting the shared
456 data object until the reference count is 0, they avoid the dangling
457 pointer problem.
458
459 It is instructive to compare QExplicitlySharedDataPointer with
460 QSharedDataPointer by way of an example. Consider the \l {Employee
461 example} in QSharedDataPointer, modified to use explicit sharing as
462 explained in the discussion \l {Implicit vs Explicit Sharing}.
463
464 Note that if you use this class but find you are calling detach() a
465 lot, you probably should be using QSharedDataPointer instead.
466
467 In the member function documentation, \e{d pointer} always refers
468 to the internal pointer to the shared data object.
469
470 \sa QSharedData, QSharedDataPointer
471*/
472
473/*! \fn template <class T> T& QExplicitlySharedDataPointer<T>::operator*() const
474 Provides access to the shared data object's members.
475*/
476
477/*! \fn template <class T> T* QExplicitlySharedDataPointer<T>::operator->()
478 Provides access to the shared data object's members.
479*/
480
481/*! \fn template <class T> const T* QExplicitlySharedDataPointer<T>::operator->() const
482 Provides const access to the shared data object's members.
483*/
484
485/*! \fn template <class T> T* QExplicitlySharedDataPointer<T>::data() const
486 Returns a pointer to the shared data object.
487*/
488
489/*! \fn template <class T> T* QExplicitlySharedDataPointer<T>::get() const
490 \since 6.0
491
492 Same as data(). This function is provided for STL compatibility.
493*/
494
495/*! \fn template <class T> const T* QExplicitlySharedDataPointer<T>::constData() const
496 Returns a const pointer to the shared data object.
497
498 \sa data()
499*/
500
501/*! \fn template <class T> void QExplicitlySharedDataPointer<T>::swap(QExplicitlySharedDataPointer &other)
502 \memberswap{explicitly-shared data pointer}
503 */
504
505/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator==(const QExplicitlySharedDataPointer<T>& lhs, const QExplicitlySharedDataPointer<T>& rhs)
506 Returns \c true if \a lhs and \a rhs have the same \e{d pointer}.
507*/
508
509/*!
510 \fn template <class T> QExplicitlySharedDataPointer<T> &QExplicitlySharedDataPointer<T>::operator=(QExplicitlySharedDataPointer<T> &&other)
511
512 Move-assigns \a other to this QExplicitlySharedDataPointer instance.
513
514 \since 5.2
515*/
516
517/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator==(const T* ptr, const QExplicitlySharedDataPointer<T>& rhs)
518 Returns \c true if the \e{d pointer} of \a rhs is \a ptr.
519 */
520
521/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator!=(const QExplicitlySharedDataPointer<T>& lhs, const QExplicitlySharedDataPointer<T>& rhs)
522 Returns \c true if \a lhs and \a rhs do \e not have the same
523 \e{d pointer}.
524*/
525
526/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator!=(const T* ptr, const QExplicitlySharedDataPointer<T>& rhs)
527 Returns \c true if the \e{d pointer} of \a rhs is \e not \a ptr.
528 */
529
530/*! \fn template <class T> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer()
531 Constructs a QExplicitlySharedDataPointer initialized with \nullptr
532 as \e{d pointer}.
533*/
534
535/*! \fn template <class T> QExplicitlySharedDataPointer<T>::~QExplicitlySharedDataPointer()
536 Decrements the reference count of the shared data object.
537 If the reference count becomes 0, the shared data object
538 is deleted. \e This is then destroyed.
539*/
540
541/*!
542 \fn template <class T> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer(QExplicitlySharedDataPointer &&o)
543
544 Move-constructs a QExplicitlySharedDataPointer instance, making it point at the same
545 object that \a o was pointing to.
546
547 \since 5.2
548*/
549
550/*! \fn template <class T> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer(T* data)
551 Constructs a QExplicitlySharedDataPointer with \e{d pointer}
552 set to \a data and increments \a{data}'s reference
553 count.
554*/
555
556/*! \fn template <class T> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer(const QExplicitlySharedDataPointer<T>& o)
557 This standard copy constructor sets the \e {d pointer} of \e this to
558 the \e {d pointer} in \a o and increments the reference count of
559 the shared data object.
560*/
561
562/*! \fn template <class T> template <class X> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer(const QExplicitlySharedDataPointer<X>& o)
563 This copy constructor is different in that it allows \a o to be
564 a different type of explicitly shared data pointer but one that has
565 a compatible shared data object.
566
567 By default, the \e{d pointer} of \a o (of type \c{X *}) gets
568 implicitly converted to the type \c{T *}; the result of this
569 conversion is set as the \e{d pointer} of \e{this}, and the
570 reference count of the shared data object is incremented.
571
572 However, if the macro
573 \c{QT_ENABLE_QEXPLICITLYSHAREDDATAPOINTER_STATICCAST} is defined
574 before including the \c{QExplicitlySharedDataPointer} header, then
575 the \e{d pointer} of \a o undergoes a \c{static_cast} to the
576 type \c{T *}. The result of the cast is then set as the
577 \e{d pointer} of \e{this}, and the reference count of the shared data
578 object is incremented.
579
580 \warning relying on such \c{static_cast} is potentially dangerous,
581 because it allows code like this to compile:
582
583 \snippet code/src_corelib_tools_qshareddata.cpp 2
584
585 Starting from Qt 5.4 the cast is disabled by default. It is
586 possible to enable it back by defining the
587 \c{QT_ENABLE_QEXPLICITLYSHAREDDATAPOINTER_STATICCAST} macro, and
588 therefore to allow old code (that relied on this feature) to
589 compile without modifications.
590
591 \note Usage of the
592 \c{QT_ENABLE_QEXPLICITLYSHAREDDATAPOINTER_STATICCAST} macro is
593 deprecated. The macro will be removed in a future version of Qt.
594*/
595
596/*! \fn template <class T> QExplicitlySharedDataPointer<T>& QExplicitlySharedDataPointer<T>::operator=(const QExplicitlySharedDataPointer<T>& o)
597 Sets the \e{d pointer} of \e this to the \e{d pointer} of
598 \a o and increments the reference count of the shared
599 data object. The reference count of the old shared data
600 object of \e this is decremented. If the reference count
601 of the old shared data object becomes 0, the old shared
602 data object is deleted.
603*/
604
605/*! \fn template <class T> QExplicitlySharedDataPointer& QExplicitlySharedDataPointer<T>::operator=(T* o)
606 Sets the \e{d pointer} of \e this to \a o and
607 increments \a{o}'s reference count. The reference
608 count of the old shared data object of \e this is decremented.
609 If the reference count of the old shared data object becomes
610 0, the old shared data object is deleted.
611*/
612
613/*! \fn template <class T> void QExplicitlySharedDataPointer<T>::reset(T *ptr = nullptr)
614 \since 6.0
615
616 Sets the \e{d pointer} of \e this to \a ptr and increments \a{ptr}'s reference
617 count if \a ptr is not \nullptr.
618 The reference count of the old shared data object is decremented,
619 and the object deleted if the reference count reaches 0.
620 */
621
622/*! \fn template <class T> T *QExplicitlySharedDataPointer<T>::take()
623 \since 5.12
624
625 Returns a pointer to the shared object, and resets \e this to be \nullptr.
626 (That is, this function sets the \e{d pointer} of \e this to \nullptr.)
627
628 \note The reference count of the returned object will \b{not} be
629 decremented. This function can be used together with the
630 constructor that takes a QAdoptSharedDataTag tag object to transfer
631 the shared data object without intervening atomic operations.
632 */
633
634/*! \fn template <class T> QExplicitlySharedDataPointer<T>::operator bool () const
635 Returns \c true if the \e{d pointer} of \e this is \e not null.
636 */
637
638/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator!() const
639 Returns \c true if the \e{d pointer} of \e this is \nullptr.
640*/
641
642/*! \fn template <class T> void QExplicitlySharedDataPointer<T>::detach()
643 If the shared data object's reference count is greater than 1, this
644 function creates a deep copy of the shared data object and sets the
645 \e{d pointer} of \e this to the copy.
646
647 Because QExplicitlySharedDataPointer does not do the automatic
648 \e{copy on write} operations that members of QSharedDataPointer do,
649 detach() is \e not called automatically anywhere in the member
650 functions of this class. If you find that you are calling detach()
651 everywhere in your code, consider using QSharedDataPointer instead.
652*/
653
654/*! \fn template <class T> T *QExplicitlySharedDataPointer<T>::clone()
655 \since 4.5
656
657 Creates and returns a deep copy of the current data. This function
658 is called by detach() when the reference count is greater than 1 in
659 order to create the new copy. This function uses the \e {operator
660 new} and calls the copy constructor of the type T.
661
662 See QSharedDataPointer<T>::clone() for an explanation of how to use it.
663*/
664
665/*!
666 \typedef QExplicitlySharedDataPointer::Type
667
668 This is the type of the shared data object. The \e{d pointer}
669 points to an object of this type.
670*/
671
672/*! \typedef QExplicitlySharedDataPointer::pointer
673 \internal
674 */
675
676QT_END_NAMESPACE
677

Provided by KDAB

Privacy Policy
Start learning QML with our Intro Training
Find out more

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