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 | |
6 | QT_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 | |
676 | QT_END_NAMESPACE |
677 | |