1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Copyright (C) 2016 Intel Corporation.
5** Contact: https://www.qt.io/licensing/
6**
7** This file is part of the QtCore module of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial License Usage
11** Licensees holding valid commercial Qt licenses may use this file in
12** accordance with the commercial license agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and The Qt Company. For licensing terms
15** and conditions see https://www.qt.io/terms-conditions. For further
16** information use the contact form at https://www.qt.io/contact-us.
17**
18** GNU Lesser General Public License Usage
19** Alternatively, this file may be used under the terms of the GNU Lesser
20** General Public License version 3 as published by the Free Software
21** Foundation and appearing in the file LICENSE.LGPL3 included in the
22** packaging of this file. Please review the following information to
23** ensure the GNU Lesser General Public License version 3 requirements
24** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
25**
26** GNU General Public License Usage
27** Alternatively, this file may be used under the terms of the GNU
28** General Public License version 2.0 or (at your option) the GNU General
29** Public license version 3 or any later version approved by the KDE Free
30** Qt Foundation. The licenses are as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
32** included in the packaging of this file. Please review the following
33** information to ensure the GNU General Public License requirements will
34** be met: https://www.gnu.org/licenses/gpl-2.0.html and
35** https://www.gnu.org/licenses/gpl-3.0.html.
36**
37** $QT_END_LICENSE$
38**
39****************************************************************************/
40
41#include "qsharedpointer.h"
42
43// to be sure we aren't causing a namespace clash:
44#include "qshareddata.h"
45
46/*!
47 \class QSharedPointer
48 \inmodule QtCore
49 \brief The QSharedPointer class holds a strong reference to a shared pointer.
50 \since 4.5
51
52 \reentrant
53
54 The QSharedPointer is an automatic, shared pointer in C++. It
55 behaves exactly like a normal pointer for normal purposes,
56 including respect for constness.
57
58 QSharedPointer will delete the pointer it is holding when it goes
59 out of scope, provided no other QSharedPointer objects are
60 referencing it.
61
62 A QSharedPointer object can be created from a normal pointer,
63 another QSharedPointer object or by promoting a
64 QWeakPointer object to a strong reference.
65
66 \section1 Thread-Safety
67
68 QSharedPointer and QWeakPointer are reentrant classes. This means that, in
69 general, a given QSharedPointer or QWeakPointer object \b{cannot} be
70 accessed by multiple threads at the same time without synchronization.
71
72 Different QSharedPointer and QWeakPointer objects can safely be accessed
73 by multiple threads at the same time. This includes the case where they
74 hold pointers to the same object; the reference counting mechanism
75 is atomic, and no manual synchronization is required.
76
77 It should be noted that, while the pointer value can be accessed in this
78 manner (that is, by multiple threads at the same time, without
79 synchronization), QSharedPointer and QWeakPointer provide no guarantee
80 about the object being pointed to. The specific thread-safety and
81 reentrancy rules for that object still apply.
82
83 \section1 Other Pointer Classes
84
85 Qt also provides two other pointer wrapper classes: QPointer and
86 QSharedDataPointer. They are incompatible with one another, since
87 each has its very different use case.
88
89 QSharedPointer holds a shared pointer by means of an external
90 reference count (i.e., a reference counter placed outside the
91 object). Like its name indicates, the pointer value is shared
92 among all instances of QSharedPointer and QWeakPointer. The
93 contents of the object pointed to by the pointer should not be
94 considered shared, however: there is only one object. For that
95 reason, QSharedPointer does not provide a way to detach or make
96 copies of the pointed object.
97
98 QSharedDataPointer, on the other hand, holds a pointer to shared
99 data (i.e., a class derived from QSharedData). It does so by means
100 of an internal reference count, placed in the QSharedData base
101 class. This class can, therefore, detach based on the type of
102 access made to the data being guarded: if it's a non-const access,
103 it creates a copy atomically for the operation to complete.
104
105 QExplicitlySharedDataPointer is a variant of QSharedDataPointer, except
106 that it only detaches if QExplicitlySharedDataPointer::detach() is
107 explicitly called (hence the name).
108
109 QScopedPointer simply holds a pointer to a heap allocated object and
110 deletes it in its destructor. This class is useful when an object needs to
111 be heap allocated and deleted, but no more. QScopedPointer is lightweight,
112 it makes no use of additional structure or reference counting.
113
114 Finally, QPointer holds a pointer to a QObject-derived object, but it
115 does so weakly. QWeakPointer has the same functionality, but its use for
116 that function is deprecated.
117
118 \section1 Optional Pointer Tracking
119
120 A feature of QSharedPointer that can be enabled at compile-time for
121 debugging purposes is a pointer tracking mechanism. When enabled,
122 QSharedPointer registers in a global set all the pointers that it tracks.
123 This allows one to catch mistakes like assigning the same pointer to two
124 QSharedPointer objects.
125
126 This function is enabled by defining the \tt{QT_SHAREDPOINTER_TRACK_POINTERS}
127 macro before including the QSharedPointer header.
128
129 It is safe to use this feature even with code compiled without the
130 feature. QSharedPointer will ensure that the pointer is removed from the
131 tracker even from code compiled without pointer tracking.
132
133 Note, however, that the pointer tracking feature has limitations on
134 multiple- or virtual-inheritance (that is, in cases where two different
135 pointer addresses can refer to the same object). In that case, if a
136 pointer is cast to a different type and its value changes,
137 QSharedPointer's pointer tracking mechanism may fail to detect that the
138 object being tracked is the same.
139
140 \omit
141 \section1 QSharedPointer internals
142
143 QSharedPointer has two "private" members: the pointer itself being tracked
144 and a d-pointer. Those members are private to the class, but QSharedPointer
145 is friends with QWeakPointer and other QSharedPointer with different
146 template arguments. (On some compilers, template friends are not supported,
147 so the members are technically public)
148
149 The reason for keeping the pointer value itself outside the d-pointer is
150 because of multiple inheritance needs. If you have two QSharedPointer
151 objects of different pointer types, but pointing to the same object in
152 memory, it could happen that the pointer values are different. The \tt
153 differentPointers autotest exemplifies this problem. The same thing could
154 happen in the case of virtual inheritance: a pointer of class matching
155 the virtual base has different address compared to the pointer of the
156 complete object. See the \tt virtualBaseDifferentPointers autotest for
157 this problem.
158
159 The d pointer is a pointer to QtSharedPointer::ExternalRefCountData, but it
160 always points to one of the two classes derived from ExternalRefCountData.
161
162 \section2 d-pointer
163 \section3 QtSharedPointer::ExternalRefCountData
164
165 It is basically a reference-counted reference-counter plus a pointer to the
166 function to be used to delete the pointer. It has three members: \tt
167 strongref, \tt weakref, and \tt destroyer. The strong reference counter is
168 controlling the lifetime of the object tracked by QSharedPointer. A
169 positive value indicates that the object is alive. It's also the number of
170 QSharedObject instances that are attached to this Data.
171
172 When the strong reference count decreases to zero, the object is deleted
173 (see below for information on custom deleters). The strong reference count
174 can also exceptionally be -1, indicating that there are no QSharedPointers
175 attached to an object, which is tracked too. The only case where this is
176 possible is that of QWeakPointers and QPointers tracking a QObject. Note
177 that QWeakPointers tracking a QObject is a deprecated feature as of Qt 5.0,
178 kept only for compatibility with Qt 4.x.
179
180 The weak reference count controls the lifetime of the d-pointer itself.
181 It can be thought of as an internal/intrusive reference count for
182 ExternalRefCountData itself. This count is equal to the number of
183 QSharedPointers and QWeakPointers that are tracking this object. In case
184 the object is a QObject being tracked by QPointer, this number is increased
185 by 1, since QObjectPrivate tracks it too.
186
187 The third member is a pointer to the function that is used to delete the
188 pointer being tracked. That happens when the destroy() function is called.
189
190 The size of this class is the size of the two atomic ints plus the size of
191 a pointer. On 32-bit architectures, that's 12 bytes, whereas on 64-bit ones
192 it's 16 bytes. There is no padding.
193
194 \section3 QtSharedPointer::ExternalRefCountWithCustomDeleter
195
196 This class derives from ExternalRefCountData and is a template class. As
197 template parameters, it has the type of the pointer being tracked (\tt T)
198 and a \tt Deleter, which is anything. It adds two fields to its parent
199 class, matching those template parameters: a member of type \tt Deleter and
200 a member of type \tt T*. Those members are actually inside a template
201 struct of type CustomDeleter, which is partially-specialized for normal
202 deletion. See below for more details on that.
203
204 The purpose of this class is to store the pointer to be deleted and the
205 deleter code along with the d-pointer. This allows the last strong
206 reference to call any arbitrary function that disposes of the object. For
207 example, this allows calling QObject::deleteLater() on a given object.
208 The pointer to the object is kept here because it needs to match the actual
209 deleter function's parameters, regardless of what template argument the
210 last QSharedPointer instance had.
211
212 This class is never instantiated directly: the constructors and
213 destructor are private and, in C++11, deleted. Only the create() function
214 may be called to return an object of this type. See below for construction
215 details.
216
217 The size of this class depends on the size of \tt Deleter. If it's an empty
218 functor (i.e., no members), ABIs generally assign it the size of 1. But
219 given that it's followed by a pointer, padding bytes may be inserted so
220 that the alignment of the class and of the pointer are correct. In that
221 case, the size of this class is 12+4+4 = 20 bytes on 32-bit architectures,
222 or 16+8+8 = 40 bytes on 64-bit architectures. If \tt Deleter is a function
223 pointer, the size should be the same as the empty structure case. If \tt
224 Deleter is a pointer to a member function (PMF), the size will be bigger
225 and will depend on the ABI. For architectures using the Itanium C++ ABI, a
226 PMF is twice the size of a normal pointer. In that case, the size of this
227 structure will be 12+8+4 = 24 bytes on 32-bit architectures, 16+16+8 = 40
228 bytes on 64-bit ones.
229
230 If the deleter was not specified when creating the QSharedPointer object
231 (i.e., if a standard \tt delete call is expected), then there's an
232 optimization that avoids the need to store another function pointer in
233 ExternalRefCountWithCustomDeleter. Instead, a template specialization makes
234 a direct delete call. The size of the structure, in this case, is 12+4 = 16
235 bytes on 32-bit architectures, 16+8 = 24 bytes on 64-bit ones.
236
237 \section3 QtSharedPointer::ExternalRefCountWithContiguousData
238
239 This class also derives from ExternalRefCountData and it is
240 also a template class. The template parameter is the type \tt T of the
241 class which QSharedPointer tracks. It adds only one member to its parent,
242 which is of type \tt T (the actual type, not a pointer to it).
243
244 The purpose of this class is to lay the \tt T object out next to the
245 reference counts, saving one memory allocation per shared pointer. This
246 is particularly interesting for small \tt T or for the cases when there
247 are few if any QWeakPointer tracking the object. This class exists to
248 implement the QSharedPointer::create() call.
249
250 Like ExternalRefCountWithCustomDeleter, this class is never instantiated
251 directly. This class also provides a create() member that returns the
252 pointer, and hides its constructors and destructor. With C++11, they're
253 deleted.
254
255 The size of this class depends on the size of \tt T.
256
257 \section3 Instantiating ExternalRefCountWithCustomDeleter and ExternalRefCountWithContiguousData
258
259 Like explained above, these classes have private constructors. Moreover,
260 they are not defined anywhere, so trying to call \tt{new ClassType} would
261 result in a compilation or linker error. Instead, these classes must be
262 constructed via their create() methods.
263
264 Instead of instantiating the class by the normal way, the create() method
265 calls \tt{operator new} directly with the size of the class, then calls
266 the parent class's constructor only (that is, ExternalRefCountData's constructor).
267 This ensures that the inherited members are initialised properly.
268
269 After initialising the base class, the
270 ExternalRefCountWithCustomDeleter::create() function initialises the new
271 members directly, by using the placement \tt{operator new}. In the case
272 of the ExternalRefCountWithContiguousData::create() function, the address
273 to the still-uninitialised \tt T member is saved for the callee to use.
274 The member is only initialised in QSharedPointer::create(), so that we
275 avoid having many variants of the internal functions according to the
276 arguments in use for calling the constructor.
277
278 When initialising the parent class, the create() functions pass the
279 address of the static deleter() member function. That is, when the
280 destroy() function is called by QSharedPointer, the deleter() functions
281 are called instead. These functions static_cast the ExternalRefCountData*
282 parameter to their own type and execute their deletion: for the
283 ExternalRefCountWithCustomDeleter::deleter() case, it runs the user's
284 custom deleter, then destroys the deleter; for
285 ExternalRefCountWithContiguousData::deleter, it simply calls the \tt T
286 destructor directly.
287
288 Only one non-inline function is required per template, which is
289 the deleter() static member. All the other functions can be inlined.
290 What's more, the address of deleter() is calculated only in code, which
291 can be resolved at link-time if the linker can determine that the
292 function lies in the current application or library module (since these
293 classes are not exported, that is the case for Windows or for builds with
294 \tt{-fvisibility=hidden}).
295
296 \section3 Modifications due to pointer-tracking
297
298 To ensure that pointers created with pointer-tracking enabled get
299 un-tracked when destroyed, even if destroyed by code compiled without the
300 feature, QSharedPointer modifies slightly the instructions of the
301 previous sections.
302
303 When ExternalRefCountWithCustomDeleter or
304 ExternalRefCountWithContiguousData are used, their create() functions
305 will set the ExternalRefCountData::destroyer function
306 pointer to safetyCheckDeleter() instead. These static member functions
307 simply call internalSafetyCheckRemove() before passing control to the
308 normal deleter() function.
309
310 If neither custom deleter nor QSharedPointer::create() are used, then
311 QSharedPointer uses a custom deleter of its own: the normalDeleter()
312 function, which simply calls \tt delete. By using a custom deleter, the
313 safetyCheckDeleter() procedure described above kicks in.
314
315 \endomit
316
317 \sa QSharedDataPointer, QWeakPointer, QScopedPointer, QEnableSharedFromThis
318*/
319
320/*!
321 \class QWeakPointer
322 \inmodule QtCore
323 \brief The QWeakPointer class holds a weak reference to a shared pointer.
324 \since 4.5
325 \reentrant
326
327 The QWeakPointer is an automatic weak reference to a
328 pointer in C++. It cannot be used to dereference the pointer
329 directly, but it can be used to verify if the pointer has been
330 deleted or not in another context.
331
332 QWeakPointer objects can only be created by assignment from a
333 QSharedPointer.
334
335 It's important to note that QWeakPointer provides no automatic casting
336 operators to prevent mistakes from happening. Even though QWeakPointer
337 tracks a pointer, it should not be considered a pointer itself, since it
338 doesn't guarantee that the pointed object remains valid.
339
340 Therefore, to access the pointer that QWeakPointer is tracking, you must
341 first promote it to QSharedPointer and verify if the resulting object is
342 null or not. QSharedPointer guarantees that the object isn't deleted, so
343 if you obtain a non-null object, you may use the pointer. See
344 QWeakPointer::toStrongRef() for an example.
345
346 \omit
347 \section1 QWeakPointer internals
348
349 QWeakPointer shares most of its internal functionality with
350 \l{QSharedPointer#qsharedpointer-internals}{QSharedPointer}, so see that
351 class's internal documentation for more information.
352
353 QWeakPointer requires an external reference counter in order to operate.
354 Therefore, it is incompatible by design with \l QSharedData-derived
355 classes.
356
357 It has a special QObject constructor, which works by calling
358 QtSharedPointer::ExternalRefCountData::getAndRef, which retrieves the
359 d-pointer from QObjectPrivate. If one isn't set yet, that function
360 creates the d-pointer and atomically sets it.
361
362 If getAndRef needs to create a d-pointer, it sets the strongref to -1,
363 indicating that the QObject is not shared: QWeakPointer is used only to
364 determine whether the QObject has been deleted. In that case, it cannot
365 be upgraded to QSharedPointer (see the previous section).
366
367 \endomit
368
369 \sa QSharedPointer, QScopedPointer
370*/
371
372/*!
373 \class QEnableSharedFromThis
374 \inmodule QtCore
375 \brief A base class that allows obtaining a QSharedPointer for an object already managed by a shared pointer.
376 \since 5.4
377
378 You can inherit this class when you need to create a QSharedPointer
379 from any instance of a class; for instance, from within the
380 object itself. The key point is that the technique of
381 just returning QSharedPointer<T>(this) cannot be used, because
382 this winds up creating multiple distinct QSharedPointer objects
383 with separate reference counts. For this reason you must never
384 create more than one QSharedPointer from the same raw pointer.
385
386 QEnableSharedFromThis defines two member functions called
387 sharedFromThis() that return a QSharedPointer<T> and
388 QSharedPointer<const T>, depending on constness, to \c this:
389
390 \snippet code/src_corelib_tools_qsharedpointer.cpp 0
391
392 It is also possible to get a shared pointer from an object outside of
393 the class itself. This is especially useful in code that provides an
394 interface to scripts, where it is currently not possible to use shared
395 pointers. For example:
396
397 \snippet code/src_corelib_tools_qsharedpointer.cpp 1
398*/
399
400/*!
401 \fn template <class T> QSharedPointer<T>::QSharedPointer()
402
403 Creates a QSharedPointer that is null (the object is holding
404 a reference to \nullptr).
405*/
406
407/*!
408 \fn template <class T> QSharedPointer<T>::~QSharedPointer()
409
410 Destroys this QSharedPointer object. If it is the last reference to
411 the pointer stored, this will delete the pointer as well.
412*/
413
414/*!
415 \fn template <class T> template <typename X> QSharedPointer<T>::QSharedPointer(X *ptr)
416
417 Creates a QSharedPointer that points to \a ptr. The pointer \a ptr
418 becomes managed by this QSharedPointer and must not be passed to
419 another QSharedPointer object or deleted outside this object.
420
421 Since Qt 5.8, when the last reference to this QSharedPointer gets
422 destroyed, \a ptr will be deleted by calling \c X's destructor (even if \c
423 X is not the same as QSharedPointer's template parameter \c T). Previously,
424 the destructor for \c T was called.
425*/
426
427/*!
428 \fn template <class T> template <typename X, typename Deleter> QSharedPointer<T>::QSharedPointer(X *ptr, Deleter d)
429
430 Creates a QSharedPointer that points to \a ptr. The pointer \a ptr
431 becomes managed by this QSharedPointer and must not be passed to
432 another QSharedPointer object or deleted outside this object.
433
434 The deleter parameter \a d specifies the custom deleter for this
435 object. The custom deleter is called, instead of the operator delete(),
436 when the strong reference count drops to 0. This is useful,
437 for instance, for calling \l {QObject::}{deleteLater()} on a QObject instead:
438
439 \snippet code/src_corelib_tools_qsharedpointer.cpp 2
440
441 Note that the custom deleter function will be called with a pointer to type
442 \c X, even if the QSharedPointer template parameter \c T is not the same.
443
444 It is also possible to specify a member function directly, as in:
445 \snippet code/src_corelib_tools_qsharedpointer.cpp 3
446
447 \sa clear()
448*/
449
450/*!
451 \fn template <class T> QSharedPointer<T>::QSharedPointer(std::nullptr_t)
452 \since 5.8
453
454 Creates a QSharedPointer that is null. This is equivalent to the
455 QSharedPointer default constructor.
456*/
457
458/*!
459 \fn template <class T> template <typename Deleter> QSharedPointer<T>::QSharedPointer(std::nullptr_t, Deleter d)
460 \since 5.8
461
462 Creates a QSharedPointer that is null. This is equivalent to the
463 QSharedPointer default constructor.
464
465 The deleter parameter \a d specifies the custom deleter for this
466 object. The custom deleter is called, instead of the operator
467 delete(), when the strong reference count drops to 0.
468*/
469
470/*!
471 \fn template <class T> QSharedPointer<T>::QSharedPointer(const QSharedPointer<T> &other)
472
473 Creates a QSharedPointer object that shares \a other's pointer.
474
475 If \tt T is a derived type of the template parameter of this class,
476 QSharedPointer will perform an automatic cast. Otherwise, you will
477 get a compiler error.
478*/
479
480/*!
481 \fn template <class T> QSharedPointer<T>::QSharedPointer(const QWeakPointer<T> &other)
482
483 Creates a QSharedPointer by promoting the weak reference \a other
484 to strong reference and sharing its pointer.
485
486 If \tt T is a derived type of the template parameter of this
487 class, QSharedPointer will perform an automatic cast. Otherwise,
488 you will get a compiler error.
489
490 \sa QWeakPointer::toStrongRef()
491*/
492
493/*!
494 \fn template <class T> QSharedPointer &QSharedPointer<T>::operator=(const QSharedPointer<T> &other)
495
496 Makes this object share \a other's pointer. The current pointer
497 reference is discarded and, if it was the last, the pointer will
498 be deleted.
499
500 If \tt T is a derived type of the template parameter of this
501 class, QSharedPointer will perform an automatic cast. Otherwise,
502 you will get a compiler error.
503*/
504
505/*!
506 \fn template <class T> QSharedPointer &QSharedPointer<T>::operator=(const QWeakPointer<T> &other)
507
508 Promotes \a other to a strong reference and makes this object
509 share a reference to the pointer referenced by it. The current pointer
510 reference is discarded and, if it was the last, the pointer will
511 be deleted.
512
513 If \tt T is a derived type of the template parameter of this
514 class, QSharedPointer will perform an automatic cast. Otherwise,
515 you will get a compiler error.
516*/
517
518/*!
519 \fn template <class T> void QSharedPointer<T>::swap(QSharedPointer<T> &other);
520 \since 5.3
521
522 Swaps this shared pointer instance with \a other. This function is
523 very fast and never fails.
524*/
525
526/*!
527 \fn template <class T> T *QSharedPointer<T>::data() const
528
529 Returns the value of the pointer referenced by this object.
530
531 Note: do not delete the pointer returned by this function or pass
532 it to another function that could delete it, including creating
533 QSharedPointer or QWeakPointer objects.
534*/
535
536/*!
537 \fn template <class T> T *QSharedPointer<T>::get() const
538 \since 5.11
539
540 Same as data().
541
542 This function is provided for API compatibility with \c{std::shared_ptr}.
543*/
544
545/*!
546 \fn template <class T> T &QSharedPointer<T>::operator *() const
547
548 Provides access to the shared pointer's members.
549
550 If the contained pointer is \nullptr, behavior is undefined.
551 \sa isNull()
552*/
553
554/*!
555 \fn template <class T> T *QSharedPointer<T>::operator ->() const
556
557 Provides access to the shared pointer's members.
558
559 If the contained pointer is \nullptr, behavior is undefined.
560 \sa isNull()
561*/
562
563/*!
564 \fn template <class T> bool QSharedPointer<T>::isNull() const
565
566 Returns \c true if this object refers to \nullptr.
567*/
568
569/*!
570 \fn template <class T> QSharedPointer<T>::operator bool() const
571
572 Returns \c true if the contained pointer is not \nullptr.
573 This function is suitable for use in \tt if-constructs, like:
574
575 \snippet code/src_corelib_tools_qsharedpointer.cpp 4
576
577 \sa isNull()
578*/
579
580/*!
581 \fn template <class T> bool QSharedPointer<T>::operator !() const
582
583 Returns \c true if this object refers to \nullptr.
584 This function is suitable for use in \tt if-constructs, like:
585
586 \snippet code/src_corelib_tools_qsharedpointer.cpp 5
587
588 \sa isNull()
589*/
590
591/*!
592 \fn template <class T> template <class X> QSharedPointer<X> QSharedPointer<T>::staticCast() const
593
594 Performs a static cast from this pointer's type to \tt X and returns
595 a QSharedPointer that shares the reference. This function can be
596 used for up- and for down-casting, but is more useful for
597 up-casting.
598
599 Note: the template type \c X must have the same const and volatile
600 qualifiers as the template of this object, or the cast will
601 fail. Use constCast() if you need to drop those qualifiers.
602
603 \sa dynamicCast(), constCast(), qSharedPointerCast()
604*/
605
606/*!
607 \fn template <class T> template <class X> QSharedPointer<X> QSharedPointer<T>::dynamicCast() const
608
609 Performs a dynamic cast from this pointer's type to \tt X and
610 returns a QSharedPointer that shares the reference. If this
611 function is used to up-cast, then QSharedPointer will perform a \tt
612 dynamic_cast, which means that if the object being pointed by this
613 QSharedPointer is not of type \tt X, the returned object will be
614 null.
615
616 Note: the template type \c X must have the same const and volatile
617 qualifiers as the template of this object, or the cast will
618 fail. Use constCast() if you need to drop those qualifiers.
619
620 \sa qSharedPointerDynamicCast()
621*/
622
623/*!
624 \fn template <class T> template <class X> QSharedPointer<X> QSharedPointer<T>::constCast() const
625
626 Performs a \tt const_cast from this pointer's type to \tt X and returns
627 a QSharedPointer that shares the reference. This function can be
628 used for up- and for down-casting, but is more useful for
629 up-casting.
630
631 \sa isNull(), qSharedPointerConstCast()
632*/
633
634/*!
635 \fn template <class T> template <class X> QSharedPointer<X> QSharedPointer<T>::objectCast() const
636 \since 4.6
637
638 Performs a \l qobject_cast() from this pointer's type to \tt X and
639 returns a QSharedPointer that shares the reference. If this
640 function is used to up-cast, then QSharedPointer will perform a \tt
641 qobject_cast, which means that if the object being pointed by this
642 QSharedPointer is not of type \tt X, the returned object will be
643 null.
644
645 Note: the template type \c X must have the same const and volatile
646 qualifiers as the template of this object, or the cast will
647 fail. Use constCast() if you need to drop those qualifiers.
648
649 \sa qSharedPointerObjectCast()
650*/
651
652/*!
653 \fn template <class T> template <typename... Args> QSharedPointer<T> QSharedPointer<T>::create(Args &&... args)
654 \overload
655 \since 5.1
656
657 Creates a QSharedPointer object and allocates a new item of type \tt T. The
658 QSharedPointer internals and the object are allocated in one single memory
659 allocation, which could help reduce memory fragmentation in a long-running
660 application.
661
662 This function will attempt to call a constructor for type \tt T that can
663 accept all the arguments passed (\a args). Arguments will be perfectly-forwarded.
664*/
665
666/*!
667 \fn template <class T> QWeakPointer<T> QSharedPointer<T>::toWeakRef() const
668
669 Returns a weak reference object that shares the pointer referenced
670 by this object.
671
672 \sa QWeakPointer::QWeakPointer()
673*/
674
675/*!
676 \fn template <class T> void QSharedPointer<T>::clear()
677
678 Clears this QSharedPointer object, dropping the reference that it
679 may have had to the pointer. If this was the last reference, then
680 the pointer itself will be deleted.
681*/
682
683/*!
684 \fn template <class T> void QSharedPointer<T>::reset()
685 \since 5.0
686
687 Same as clear(). For std::shared_ptr compatibility.
688*/
689
690/*!
691 \fn template <class T> void QSharedPointer<T>::reset(T *t)
692 \since 5.0
693
694 Resets this QSharedPointer object to point to \a t
695 instead. Equivalent to:
696 \snippet code/src_corelib_tools_qsharedpointer.cpp 6
697*/
698
699/*!
700 \fn template <class T> template <typename Deleter> void QSharedPointer<T>::reset(T *t, Deleter deleter)
701 \since 5.0
702
703 Resets this QSharedPointer object to point to \a t
704 instead, with the Deleter \a deleter. Equivalent to:
705 \snippet code/src_corelib_tools_qsharedpointer.cpp 7
706*/
707
708/*!
709 \fn template <class T> QWeakPointer<T>::QWeakPointer()
710
711 Creates a QWeakPointer that points to nothing.
712*/
713
714/*!
715 \fn template <class T> QWeakPointer<T>::~QWeakPointer()
716
717 Destroys this QWeakPointer object. The pointer referenced
718 by this object will not be deleted.
719*/
720
721/*!
722 \fn template <class T> QWeakPointer<T>::QWeakPointer(const QWeakPointer<T> &other)
723
724 Creates a QWeakPointer that holds a weak reference to the
725 pointer referenced by \a other.
726
727 If \tt T is a derived type of the template parameter of this
728 class, QWeakPointer will perform an automatic cast. Otherwise,
729 you will get a compiler error.
730*/
731
732/*!
733 \fn template <class T> QWeakPointer<T>::QWeakPointer(const QSharedPointer<T> &other)
734
735 Creates a QWeakPointer that holds a weak reference to the
736 pointer referenced by \a other.
737
738 If \tt T is a derived type of the template parameter of this
739 class, QWeakPointer will perform an automatic cast. Otherwise,
740 you will get a compiler error.
741*/
742
743/*!
744 \fn template <class T> QWeakPointer<T>::QWeakPointer(const QObject *other)
745 \since 4.6
746 \deprecated
747
748 Creates a QWeakPointer that holds a weak reference directly to the
749 QObject \a other. This constructor is only available if the template type
750 \tt T is QObject or derives from it (otherwise a compilation error will
751 result).
752
753 You can use this constructor with any QObject, even if they were not
754 created with \l QSharedPointer.
755
756 Note that QWeakPointers created this way on arbitrary QObjects usually
757 cannot be promoted to QSharedPointer.
758
759 \sa QSharedPointer, QPointer
760*/
761
762/*!
763 \fn template <class T> QWeakPointer &QWeakPointer<T>::operator=(const QObject *other)
764 \since 4.6
765 \deprecated
766
767 Makes this QWeakPointer hold a weak reference directly to the QObject
768 \a other. This function is only available if the template type \tt T is
769 QObject or derives from it.
770
771 \sa QPointer
772*/
773
774/*!
775 \fn template <class T> QWeakPointer &QWeakPointer<T>::operator=(const QWeakPointer<T> &other)
776
777 Makes this object share \a other's pointer. The current pointer
778 reference is discarded but is not deleted.
779
780 If \tt T is a derived type of the template parameter of this
781 class, QWeakPointer will perform an automatic cast. Otherwise,
782 you will get a compiler error.
783*/
784
785/*!
786 \fn template <class T> QWeakPointer &QWeakPointer<T>::operator=(const QSharedPointer<T> &other)
787
788 Makes this object share \a other's pointer. The current pointer
789 reference is discarded but is not deleted.
790
791 If \tt T is a derived type of the template parameter of this
792 class, QWeakPointer will perform an automatic cast. Otherwise,
793 you will get a compiler error.
794*/
795
796/*!
797 \fn template <class T> void QWeakPointer<T>::swap(QWeakPointer<T> &other)
798 \since 5.4
799
800 Swaps this weak pointer instance with \a other. This function is
801 very fast and never fails.
802*/
803
804/*!
805 \fn template <class T> bool QWeakPointer<T>::isNull() const
806
807 Returns \c true if this object refers to \nullptr.
808
809 Note that, due to the nature of weak references, the pointer that
810 QWeakPointer references can become \nullptr at any moment, so
811 the value returned from this function can change from false to
812 true from one call to the next.
813*/
814
815/*!
816 \fn template <class T> QWeakPointer<T>::operator bool() const
817
818 Returns \c true if the contained pointer is not \nullptr.
819 This function is suitable for use in \tt if-constructs, like:
820
821 \snippet code/src_corelib_tools_qsharedpointer.cpp 8
822
823 Note that, due to the nature of weak references, the pointer that
824 QWeakPointer references can become \nullptr at any moment, so
825 the value returned from this function can change from true to
826 false from one call to the next.
827
828 \sa isNull()
829*/
830
831/*!
832 \fn template <class T> bool QWeakPointer<T>::operator !() const
833
834 Returns \c true if this object refers to \nullptr.
835 This function is suitable for use in \tt if-constructs, like:
836
837 \snippet code/src_corelib_tools_qsharedpointer.cpp 9
838
839 Note that, due to the nature of weak references, the pointer that
840 QWeakPointer references can become \nullptr at any moment, so
841 the value returned from this function can change from false to
842 true from one call to the next.
843
844 \sa isNull()
845*/
846
847/*!
848 \fn template <class T> T *QWeakPointer<T>::data() const
849 \since 4.6
850 \obsolete Use toStrongRef() instead, and data() on the returned QSharedPointer.
851
852 Returns the value of the pointer being tracked by this QWeakPointer,
853 \b without ensuring that it cannot get deleted. To have that guarantee,
854 use toStrongRef(), which returns a QSharedPointer object. If this
855 function can determine that the pointer has already been deleted, it
856 returns \nullptr.
857
858 It is ok to obtain the value of the pointer and using that value itself,
859 like for example in debugging statements:
860
861 \snippet code/src_corelib_tools_qsharedpointer.cpp 10
862
863 However, dereferencing the pointer is only allowed if you can guarantee
864 by external means that the pointer does not get deleted. For example,
865 if you can be certain that no other thread can delete it, nor the
866 functions that you may call.
867
868 If that is the case, then the following code is valid:
869
870 \snippet code/src_corelib_tools_qsharedpointer.cpp 11
871
872 Use this function with care.
873
874 \sa isNull(), toStrongRef()
875*/
876
877/*!
878 \fn template <class T> QSharedPointer<T> QWeakPointer<T>::toStrongRef() const
879
880 Promotes this weak reference to a strong one and returns a
881 QSharedPointer object holding that reference. When promoting to
882 QSharedPointer, this function verifies if the object has been deleted
883 already or not. If it hasn't, this function increases the reference
884 count to the shared object, thus ensuring that it will not get
885 deleted.
886
887 Since this function can fail to obtain a valid strong reference to the
888 shared object, you should always verify if the conversion succeeded,
889 by calling QSharedPointer::isNull() on the returned object.
890
891 For example, the following code promotes a QWeakPointer that was held
892 to a strong reference and, if it succeeded, it prints the value of the
893 integer that was held:
894
895 \snippet code/src_corelib_tools_qsharedpointer.cpp 12
896
897 \sa QSharedPointer::QSharedPointer()
898*/
899
900/*!
901 \fn template <class T> QSharedPointer<T> QWeakPointer<T>::lock() const
902 \since 5.4
903
904 Same as toStrongRef().
905
906 This function is provided for API compatibility with std::weak_ptr.
907*/
908
909/*!
910 \fn template <class T> void QWeakPointer<T>::clear()
911
912 Clears this QWeakPointer object, dropping the reference that it
913 may have had to the pointer.
914*/
915
916/*!
917 \fn template <class T> QSharedPointer<T> QEnableSharedFromThis<T>::sharedFromThis()
918 \since 5.4
919
920 If \c this (that is, the subclass instance invoking this method) is being
921 managed by a QSharedPointer, returns a shared pointer instance pointing to
922 \c this; otherwise returns a null QSharedPointer.
923*/
924
925/*!
926 \fn template <class T> QSharedPointer<const T> QEnableSharedFromThis<T>::sharedFromThis() const
927 \overload
928 \since 5.4
929
930 Const overload of sharedFromThis().
931*/
932
933/*!
934 \fn template <class T> template <class X> bool operator==(const QSharedPointer<T> &ptr1, const QSharedPointer<X> &ptr2)
935 \relates QSharedPointer
936
937 Returns \c true if \a ptr1 and \a ptr2 refer to the same pointer.
938
939 If \a ptr2's template parameter is different from \a ptr1's,
940 QSharedPointer will attempt to perform an automatic \tt static_cast
941 to ensure that the pointers being compared are equal. If \a ptr2's
942 template parameter is not a base or a derived type from
943 \a ptr1's, you will get a compiler error.
944*/
945
946/*!
947 \fn template <class T> template <class X> bool operator!=(const QSharedPointer<T> &ptr1, const QSharedPointer<X> &ptr2)
948 \relates QSharedPointer
949
950 Returns \c true if \a ptr1 and \a ptr2 refer to distinct pointers.
951
952 If \a ptr2's template parameter is different from \a ptr1's,
953 QSharedPointer will attempt to perform an automatic \tt static_cast
954 to ensure that the pointers being compared are equal. If \a ptr2's
955 template parameter is not a base or a derived type from
956 \a ptr1's, you will get a compiler error.
957*/
958
959/*!
960 \fn template <class T> template <class X> bool operator==(const QSharedPointer<T> &ptr1, const X *ptr2)
961 \relates QSharedPointer
962
963 Returns \c true if \a ptr1 and \a ptr2 refer to the same pointer.
964
965 If \a ptr2's type is different from \a ptr1's,
966 QSharedPointer will attempt to perform an automatic \tt static_cast
967 to ensure that the pointers being compared are equal. If \a ptr2's
968 type is not a base or a derived type from this
969 \a ptr1's, you will get a compiler error.
970*/
971
972/*!
973 \fn template <class T> template <class X> bool operator!=(const QSharedPointer<T> &ptr1, const X *ptr2)
974 \relates QSharedPointer
975
976 Returns \c true if \a ptr1 and \a ptr2 refer to distinct pointers.
977
978 If \a ptr2's type is different from \a ptr1's,
979 QSharedPointer will attempt to perform an automatic \tt static_cast
980 to ensure that the pointers being compared are equal. If \a ptr2's
981 type is not a base or a derived type from this
982 \a ptr1's, you will get a compiler error.
983*/
984
985/*!
986 \fn template <class T> template <class X> bool operator==(const T *ptr1, const QSharedPointer<X> &ptr2)
987 \relates QSharedPointer
988
989 Returns \c true if the pointer \a ptr1 is the
990 same pointer as that referenced by \a ptr2.
991
992 If \a ptr2's template parameter is different from \a ptr1's type,
993 QSharedPointer will attempt to perform an automatic \tt static_cast
994 to ensure that the pointers being compared are equal. If \a ptr2's
995 template parameter is not a base or a derived type from
996 \a ptr1's type, you will get a compiler error.
997*/
998
999/*!
1000 \fn template <class T> template <class X> bool operator!=(const T *ptr1, const QSharedPointer<X> &ptr2)
1001 \relates QSharedPointer
1002
1003 Returns \c true if the pointer \a ptr1 is not the
1004 same pointer as that referenced by \a ptr2.
1005
1006 If \a ptr2's template parameter is different from \a ptr1's type,
1007 QSharedPointer will attempt to perform an automatic \tt static_cast
1008 to ensure that the pointers being compared are equal. If \a ptr2's
1009 template parameter is not a base or a derived type from
1010 \a ptr1's type, you will get a compiler error.
1011*/
1012
1013/*!
1014 \fn template <class T> template <class X> bool operator==(const QSharedPointer<T> &ptr1, const QWeakPointer<X> &ptr2)
1015 \relates QWeakPointer
1016
1017 Returns \c true if \a ptr1 and \a ptr2 refer to the same pointer.
1018
1019 If \a ptr2's template parameter is different from \a ptr1's,
1020 QSharedPointer will attempt to perform an automatic \tt static_cast
1021 to ensure that the pointers being compared are equal. If \a ptr2's
1022 template parameter is not a base or a derived type from
1023 \a ptr1's, you will get a compiler error.
1024*/
1025
1026/*!
1027 \fn template <class T> template <class X> bool operator!=(const QSharedPointer<T> &ptr1, const QWeakPointer<X> &ptr2)
1028 \relates QWeakPointer
1029
1030 Returns \c true if \a ptr1 and \a ptr2 refer to distinct pointers.
1031
1032 If \a ptr2's template parameter is different from \a ptr1's,
1033 QSharedPointer will attempt to perform an automatic \tt static_cast
1034 to ensure that the pointers being compared are equal. If \a ptr2's
1035 template parameter is not a base or a derived type from
1036 \a ptr1's, you will get a compiler error.
1037*/
1038
1039/*!
1040 \fn template <class T> template <class X> bool operator==(const QWeakPointer<T> &ptr1, const QSharedPointer<X> &ptr2)
1041 \relates QWeakPointer
1042
1043 Returns \c true if \a ptr1 and \a ptr2 refer to the same pointer.
1044
1045 If \a ptr2's template parameter is different from \a ptr1's,
1046 QSharedPointer will attempt to perform an automatic \tt static_cast
1047 to ensure that the pointers being compared are equal. If \a ptr2's
1048 template parameter is not a base or a derived type from
1049 \a ptr1's, you will get a compiler error.
1050*/
1051
1052/*!
1053 \fn template <class T> bool operator==(const QSharedPointer<T> &lhs, std::nullptr_t)
1054 \relates QSharedPointer
1055 \since 5.8
1056
1057 Returns \c true if \a lhs refers to \nullptr.
1058
1059 \sa QSharedPointer::isNull()
1060*/
1061
1062/*!
1063 \fn template <class T> bool operator==(std::nullptr_t, const QSharedPointer<T> &rhs)
1064 \relates QSharedPointer
1065 \since 5.8
1066
1067 Returns \c true if \a rhs refers to \nullptr.
1068
1069 \sa QSharedPointer::isNull()
1070*/
1071
1072/*!
1073 \fn template <class T> bool operator!=(const QSharedPointer<T> &lhs, std::nullptr_t)
1074 \relates QSharedPointer
1075 \since 5.8
1076
1077 Returns \c true if \a lhs refers to a valid (i.e. non-null) pointer.
1078
1079 \sa QSharedPointer::isNull()
1080*/
1081
1082/*!
1083 \fn template <class T> bool operator!=(std::nullptr_t, const QSharedPointer<T> &rhs)
1084 \relates QSharedPointer
1085 \since 5.8
1086
1087 Returns \c true if \a rhs refers to a valid (i.e. non-null) pointer.
1088
1089 \sa QSharedPointer::isNull()
1090*/
1091
1092/*!
1093 \fn template <class T> bool operator==(const QWeakPointer<T> &lhs, std::nullptr_t)
1094 \relates QWeakPointer
1095 \since 5.8
1096
1097 Returns \c true if \a lhs refers to \nullptr.
1098
1099 \sa QWeakPointer::isNull()
1100*/
1101
1102/*!
1103 \fn template <class T> bool operator==(std::nullptr_t, const QWeakPointer<T> &rhs)
1104 \relates QWeakPointer
1105 \since 5.8
1106
1107 Returns \c true if \a rhs refers to \nullptr.
1108
1109 \sa QWeakPointer::isNull()
1110*/
1111
1112/*!
1113 \fn template <class T> bool operator!=(const QWeakPointer<T> &lhs, std::nullptr_t)
1114 \relates QWeakPointer
1115 \since 5.8
1116
1117 Returns \c true if \a lhs refers to a valid (i.e. non-null) pointer.
1118
1119 \sa QWeakPointer::isNull()
1120*/
1121
1122/*!
1123 \fn template <class T> bool operator!=(std::nullptr_t, const QWeakPointer<T> &rhs)
1124 \relates QWeakPointer
1125 \since 5.8
1126
1127 Returns \c true if \a rhs refers to a valid (i.e. non-null) pointer.
1128
1129 \sa QWeakPointer::isNull()
1130*/
1131
1132/*!
1133 \fn template <class T> template <class X> bool operator!=(const QWeakPointer<T> &ptr1, const QSharedPointer<X> &ptr2)
1134 \relates QWeakPointer
1135
1136 Returns \c true if \a ptr1 and \a ptr2 refer to distinct pointers.
1137
1138 If \a ptr2's template parameter is different from \a ptr1's,
1139 QSharedPointer will attempt to perform an automatic \tt static_cast
1140 to ensure that the pointers being compared are equal. If \a ptr2's
1141 template parameter is not a base or a derived type from
1142 \a ptr1's, you will get a compiler error.
1143*/
1144
1145/*!
1146 \fn template <class X> template <class T> QSharedPointer<X> qSharedPointerCast(const QSharedPointer<T> &other)
1147 \relates QSharedPointer
1148
1149 Returns a shared pointer to the pointer held by \a other, cast to
1150 type \tt X. The types \tt T and \tt X must belong to one
1151 hierarchy for the \tt static_cast to succeed.
1152
1153 Note that \tt X must have the same cv-qualifiers (\tt const and
1154 \tt volatile) that \tt T has, or the code will fail to
1155 compile. Use qSharedPointerConstCast to cast away the constness.
1156
1157 \sa QSharedPointer::staticCast(), qSharedPointerDynamicCast(), qSharedPointerConstCast()
1158*/
1159
1160/*!
1161 \fn template <class X> template <class T> QSharedPointer<X> qSharedPointerCast(const QWeakPointer<T> &other)
1162 \relates QSharedPointer
1163 \relates QWeakPointer
1164
1165 Returns a shared pointer to the pointer held by \a other, cast to
1166 type \tt X. The types \tt T and \tt X must belong to one
1167 hierarchy for the \tt static_cast to succeed.
1168
1169 The \a other object is converted first to a strong reference. If
1170 that conversion fails (because the object it's pointing to has
1171 already been deleted), this function returns a null
1172 QSharedPointer.
1173
1174 Note that \tt X must have the same cv-qualifiers (\tt const and
1175 \tt volatile) that \tt T has, or the code will fail to
1176 compile. Use qSharedPointerConstCast to cast away the constness.
1177
1178 \sa QWeakPointer::toStrongRef(), qSharedPointerDynamicCast(), qSharedPointerConstCast()
1179*/
1180
1181/*!
1182 \fn template <class X> template <class T> QSharedPointer<X> qSharedPointerDynamicCast(const QSharedPointer<T> &src)
1183 \relates QSharedPointer
1184
1185 Returns a shared pointer to the pointer held by \a src, using a
1186 dynamic cast to type \tt X to obtain an internal pointer of the
1187 appropriate type. If the \tt dynamic_cast fails, the object
1188 returned will be null.
1189
1190 Note that \tt X must have the same cv-qualifiers (\tt const and
1191 \tt volatile) that \tt T has, or the code will fail to
1192 compile. Use qSharedPointerConstCast to cast away the constness.
1193
1194 \sa QSharedPointer::dynamicCast(), qSharedPointerCast(), qSharedPointerConstCast()
1195*/
1196
1197/*!
1198 \fn template <class X> template <class T> QSharedPointer<X> qSharedPointerDynamicCast(const QWeakPointer<T> &src)
1199 \relates QSharedPointer
1200 \relates QWeakPointer
1201
1202 Returns a shared pointer to the pointer held by \a src, using a
1203 dynamic cast to type \tt X to obtain an internal pointer of the
1204 appropriate type. If the \tt dynamic_cast fails, the object
1205 returned will be null.
1206
1207 The \a src object is converted first to a strong reference. If
1208 that conversion fails (because the object it's pointing to has
1209 already been deleted), this function also returns a null
1210 QSharedPointer.
1211
1212 Note that \tt X must have the same cv-qualifiers (\tt const and
1213 \tt volatile) that \tt T has, or the code will fail to
1214 compile. Use qSharedPointerConstCast to cast away the constness.
1215
1216 \sa QWeakPointer::toStrongRef(), qSharedPointerCast(), qSharedPointerConstCast()
1217*/
1218
1219/*!
1220 \fn template <class X> template <class T> QSharedPointer<X> qSharedPointerConstCast(const QSharedPointer<T> &src)
1221 \relates QSharedPointer
1222
1223 Returns a shared pointer to the pointer held by \a src, cast to
1224 type \tt X. The types \tt T and \tt X must belong to one
1225 hierarchy for the \tt const_cast to succeed. The \tt const and \tt
1226 volatile differences between \tt T and \tt X are ignored.
1227
1228 \sa QSharedPointer::constCast(), qSharedPointerCast(), qSharedPointerDynamicCast()
1229*/
1230
1231/*!
1232 \fn template <class X> template <class T> QSharedPointer<X> qSharedPointerConstCast(const QWeakPointer<T> &src)
1233 \relates QSharedPointer
1234 \relates QWeakPointer
1235
1236 Returns a shared pointer to the pointer held by \a src, cast to
1237 type \tt X. The types \tt T and \tt X must belong to one
1238 hierarchy for the \tt const_cast to succeed. The \tt const and
1239 \tt volatile differences between \tt T and \tt X are ignored.
1240
1241 The \a src object is converted first to a strong reference. If
1242 that conversion fails (because the object it's pointing to has
1243 already been deleted), this function returns a null
1244 QSharedPointer.
1245
1246 \sa QWeakPointer::toStrongRef(), qSharedPointerCast(), qSharedPointerDynamicCast()
1247*/
1248
1249/*!
1250 \fn template <class X> template <class T> QSharedPointer<X> qSharedPointerObjectCast(const QSharedPointer<T> &src)
1251 \relates QSharedPointer
1252 \since 4.6
1253
1254 \brief The qSharedPointerObjectCast function is for casting a shared pointer.
1255
1256 Returns a shared pointer to the pointer held by \a src, using a
1257 \l qobject_cast() to type \tt X to obtain an internal pointer of the
1258 appropriate type. If the \tt qobject_cast fails, the object
1259 returned will be null.
1260
1261 Note that \tt X must have the same cv-qualifiers (\tt const and
1262 \tt volatile) that \tt T has, or the code will fail to
1263 compile. Use qSharedPointerConstCast to cast away the constness.
1264
1265 \sa QSharedPointer::objectCast(), qSharedPointerCast(), qSharedPointerConstCast()
1266*/
1267
1268/*!
1269 \fn template <class X, class T> std::shared_ptr<X> qSharedPointerObjectCast(const std::shared_ptr<T> &src)
1270 \relates QSharedPointer
1271 \since 5.14
1272
1273 Returns a shared pointer to the pointer held by \a src, using a
1274 \l qobject_cast() to type \tt X to obtain an internal pointer of the
1275 appropriate type. If the \tt qobject_cast fails, the object
1276 returned will be null.
1277
1278 Note that \tt X must have the same cv-qualifiers (\tt const and
1279 \tt volatile) that \tt T has, or the code will fail to
1280 compile. Use const_pointer_cast to cast away the constness.
1281*/
1282
1283/*!
1284 \fn template <class X, class T> std::shared_ptr<X> qobject_pointer_cast(const std::shared_ptr<T> &src)
1285 \relates QSharedPointer
1286 \since 5.14
1287
1288 Same as qSharedPointerObjectCast(). This function is provided for STL
1289 compatibility.
1290*/
1291
1292/*!
1293 \fn template <class X, class T> std::shared_ptr<X> qSharedPointerObjectCast(std::shared_ptr<T> &&src)
1294 \relates QSharedPointer
1295 \since 5.14
1296
1297 Returns a shared pointer to the pointer held by \a src, using a
1298 \l qobject_cast() to type \tt X to obtain an internal pointer of the
1299 appropriate type.
1300
1301 If the \tt qobject_cast succeeds, the function will return a valid shared
1302 pointer, and \a src is reset to null. If the \tt qobject_cast fails, the
1303 object returned will be null, and \a src will not be modified.
1304
1305 Note that \tt X must have the same cv-qualifiers (\tt const and
1306 \tt volatile) that \tt T has, or the code will fail to
1307 compile. Use const_pointer_cast to cast away the constness.
1308*/
1309
1310/*!
1311 \fn template <class X, class T> std::shared_ptr<X> qobject_pointer_cast(std::shared_ptr<T> &&src)
1312 \relates QSharedPointer
1313 \since 5.14
1314
1315 Same as qSharedPointerObjectCast(). This function is provided for STL
1316 compatibility.
1317*/
1318
1319/*!
1320 \fn template <class X> template <class T> QSharedPointer<X> qSharedPointerObjectCast(const QWeakPointer<T> &src)
1321 \relates QSharedPointer
1322 \relates QWeakPointer
1323 \since 4.6
1324
1325 \brief The qSharedPointerObjectCast function is for casting a shared pointer.
1326
1327 Returns a shared pointer to the pointer held by \a src, using a
1328 \l qobject_cast() to type \tt X to obtain an internal pointer of the
1329 appropriate type. If the \tt qobject_cast fails, the object
1330 returned will be null.
1331
1332 The \a src object is converted first to a strong reference. If
1333 that conversion fails (because the object it's pointing to has
1334 already been deleted), this function also returns a null
1335 QSharedPointer.
1336
1337 Note that \tt X must have the same cv-qualifiers (\tt const and
1338 \tt volatile) that \tt T has, or the code will fail to
1339 compile. Use qSharedPointerConstCast to cast away the constness.
1340
1341 \sa QWeakPointer::toStrongRef(), qSharedPointerCast(), qSharedPointerConstCast()
1342*/
1343
1344
1345/*!
1346 \fn template <class X> template <class T> QWeakPointer<X> qWeakPointerCast(const QWeakPointer<T> &src)
1347 \relates QWeakPointer
1348
1349 Returns a weak pointer to the pointer held by \a src, cast to
1350 type \tt X. The types \tt T and \tt X must belong to one
1351 hierarchy for the \tt static_cast to succeed.
1352
1353 Note that \tt X must have the same cv-qualifiers (\tt const and
1354 \tt volatile) that \tt T has, or the code will fail to
1355 compile. Use qSharedPointerConstCast to cast away the constness.
1356*/
1357
1358#include <qset.h>
1359#include <qmutex.h>
1360
1361#if !defined(QT_NO_QOBJECT)
1362#include "private/qobject_p.h"
1363
1364QT_BEGIN_NAMESPACE
1365
1366/*!
1367 \internal
1368 This function is called for a just-created QObject \a obj, to enable
1369 the use of QSharedPointer and QWeakPointer in the future.
1370 */
1371void QtSharedPointer::ExternalRefCountData::setQObjectShared(const QObject *, bool)
1372{}
1373
1374/*!
1375 \internal
1376 This function is called when a QSharedPointer is created from a QWeakPointer
1377
1378 We check that the QWeakPointer was really created from a QSharedPointer, and
1379 not from a QObject.
1380*/
1381void QtSharedPointer::ExternalRefCountData::checkQObjectShared(const QObject *)
1382{
1383 if (strongref.loadRelaxed() < 0)
1384 qWarning("QSharedPointer: cannot create a QSharedPointer from a QObject-tracking QWeakPointer");
1385}
1386
1387QtSharedPointer::ExternalRefCountData *QtSharedPointer::ExternalRefCountData::getAndRef(const QObject *obj)
1388{
1389 Q_ASSERT(obj);
1390 QObjectPrivate *d = QObjectPrivate::get(const_cast<QObject *>(obj));
1391 Q_ASSERT_X(!d->wasDeleted, "QWeakPointer", "Detected QWeakPointer creation in a QObject being deleted");
1392
1393 ExternalRefCountData *that = d->sharedRefcount.loadRelaxed();
1394 if (that) {
1395 that->weakref.ref();
1396 return that;
1397 }
1398
1399 // we can create the refcount data because it doesn't exist
1400 ExternalRefCountData *x = new ExternalRefCountData(Qt::Uninitialized);
1401 x->strongref.storeRelaxed(-1);
1402 x->weakref.storeRelaxed(2); // the QWeakPointer that called us plus the QObject itself
1403
1404 ExternalRefCountData *ret;
1405 if (d->sharedRefcount.testAndSetOrdered(nullptr, x, ret)) { // ought to be release+acquire; this is acq_rel+acquire
1406 ret = x;
1407 } else {
1408 // ~ExternalRefCountData has a Q_ASSERT, so we use this trick to
1409 // only execute this if Q_ASSERTs are enabled
1410 Q_ASSERT((x->weakref.storeRelaxed(0), true));
1411 delete x;
1412 ret->weakref.ref();
1413 }
1414 return ret;
1415}
1416
1417/**
1418 \internal
1419 Returns a QSharedPointer<QObject> if the variant contains
1420 a QSharedPointer<T> where T inherits QObject. Otherwise the behaviour is undefined.
1421*/
1422QSharedPointer<QObject> QtSharedPointer::sharedPointerFromVariant_internal(const QVariant &variant)
1423{
1424 Q_ASSERT(QMetaType::typeFlags(variant.userType()) & QMetaType::SharedPointerToQObject);
1425 return *reinterpret_cast<const QSharedPointer<QObject>*>(variant.constData());
1426}
1427
1428/**
1429 \internal
1430 Returns a QWeakPointer<QObject> if the variant contains
1431 a QWeakPointer<T> where T inherits QObject. Otherwise the behaviour is undefined.
1432*/
1433QWeakPointer<QObject> QtSharedPointer::weakPointerFromVariant_internal(const QVariant &variant)
1434{
1435 Q_ASSERT(QMetaType::typeFlags(variant.userType()) & QMetaType::WeakPointerToQObject || QMetaType::typeFlags(variant.userType()) & QMetaType::TrackingPointerToQObject);
1436 return *reinterpret_cast<const QWeakPointer<QObject>*>(variant.constData());
1437}
1438
1439QT_END_NAMESPACE
1440
1441#endif
1442
1443
1444
1445//# define QT_SHARED_POINTER_BACKTRACE_SUPPORT
1446# ifdef QT_SHARED_POINTER_BACKTRACE_SUPPORT
1447# if defined(__GLIBC__) && (__GLIBC__ >= 2) && !defined(__UCLIBC__) && !defined(QT_LINUXBASE)
1448# define BACKTRACE_SUPPORTED
1449# elif defined(Q_OS_MAC)
1450# define BACKTRACE_SUPPORTED
1451# endif
1452# endif
1453
1454# if defined(BACKTRACE_SUPPORTED)
1455# include <sys/types.h>
1456# include <execinfo.h>
1457# include <stdio.h>
1458# include <unistd.h>
1459# include <sys/wait.h>
1460
1461QT_BEGIN_NAMESPACE
1462
1463static inline QByteArray saveBacktrace() __attribute__((always_inline));
1464static inline QByteArray saveBacktrace()
1465{
1466 static const int maxFrames = 32;
1467
1468 QByteArray stacktrace;
1469 stacktrace.resize(sizeof(void*) * maxFrames);
1470 int stack_size = backtrace((void**)stacktrace.data(), maxFrames);
1471 stacktrace.resize(sizeof(void*) * stack_size);
1472
1473 return stacktrace;
1474}
1475
1476static void printBacktrace(QByteArray stacktrace)
1477{
1478 void *const *stack = (void *const *)stacktrace.constData();
1479 int stack_size = stacktrace.size() / sizeof(void*);
1480 char **stack_symbols = backtrace_symbols(stack, stack_size);
1481
1482 int filter[2];
1483 pid_t child = -1;
1484 if (pipe(filter) != -1)
1485 child = fork();
1486 if (child == 0) {
1487 // child process
1488 dup2(fileno(stderr), fileno(stdout));
1489 dup2(filter[0], fileno(stdin));
1490 close(filter[0]);
1491 close(filter[1]);
1492 execlp("c++filt", "c++filt", "-n", NULL);
1493
1494 // execlp failed
1495 execl("/bin/cat", "/bin/cat", NULL);
1496 _exit(127);
1497 }
1498
1499 // parent process
1500 close(filter[0]);
1501 FILE *output;
1502 if (child == -1) {
1503 // failed forking
1504 close(filter[1]);
1505 output = stderr;
1506 } else {
1507 output = fdopen(filter[1], "w");
1508 }
1509
1510 fprintf(stderr, "Backtrace of the first creation (most recent frame first):\n");
1511 for (int i = 0; i < stack_size; ++i) {
1512 if (strlen(stack_symbols[i]))
1513 fprintf(output, "#%-2d %s\n", i, stack_symbols[i]);
1514 else
1515 fprintf(output, "#%-2d %p\n", i, stack[i]);
1516 }
1517
1518 if (child != -1) {
1519 fclose(output);
1520 waitpid(child, 0, 0);
1521 }
1522}
1523
1524QT_END_NAMESPACE
1525
1526# endif // BACKTRACE_SUPPORTED
1527
1528namespace {
1529 QT_USE_NAMESPACE
1530 struct Data {
1531 const volatile void *pointer;
1532# ifdef BACKTRACE_SUPPORTED
1533 QByteArray backtrace;
1534# endif
1535 };
1536
1537 class KnownPointers
1538 {
1539 public:
1540 QMutex mutex;
1541 QHash<const void *, Data> dPointers;
1542 QHash<const volatile void *, const void *> dataPointers;
1543 };
1544}
1545
1546Q_GLOBAL_STATIC(KnownPointers, knownPointers)
1547
1548QT_BEGIN_NAMESPACE
1549
1550namespace QtSharedPointer {
1551 Q_AUTOTEST_EXPORT void internalSafetyCheckCleanCheck();
1552}
1553
1554/*!
1555 \internal
1556*/
1557void QtSharedPointer::internalSafetyCheckAdd(const void *d_ptr, const volatile void *ptr)
1558{
1559 KnownPointers *const kp = knownPointers();
1560 if (!kp)
1561 return; // end-game: the application is being destroyed already
1562
1563 QMutexLocker lock(&kp->mutex);
1564 Q_ASSERT(!kp->dPointers.contains(d_ptr));
1565
1566 //qDebug("Adding d=%p value=%p", d_ptr, ptr);
1567
1568 const void *other_d_ptr = kp->dataPointers.value(ptr, 0);
1569 if (Q_UNLIKELY(other_d_ptr)) {
1570# ifdef BACKTRACE_SUPPORTED
1571 printBacktrace(knownPointers()->dPointers.value(other_d_ptr).backtrace);
1572# endif
1573 qFatal("QSharedPointer: internal self-check failed: pointer %p was already tracked "
1574 "by another QSharedPointer object %p", ptr, other_d_ptr);
1575 }
1576
1577 Data data;
1578 data.pointer = ptr;
1579# ifdef BACKTRACE_SUPPORTED
1580 data.backtrace = saveBacktrace();
1581# endif
1582
1583 kp->dPointers.insert(d_ptr, data);
1584 kp->dataPointers.insert(ptr, d_ptr);
1585 Q_ASSERT(kp->dPointers.size() == kp->dataPointers.size());
1586}
1587
1588/*!
1589 \internal
1590*/
1591void QtSharedPointer::internalSafetyCheckRemove(const void *d_ptr)
1592{
1593 KnownPointers *const kp = knownPointers();
1594 if (!kp)
1595 return; // end-game: the application is being destroyed already
1596
1597 QMutexLocker lock(&kp->mutex);
1598
1599 const auto it = kp->dPointers.constFind(d_ptr);
1600 if (Q_UNLIKELY(it == kp->dPointers.cend())) {
1601 qFatal("QSharedPointer: internal self-check inconsistency: pointer %p was not tracked. "
1602 "To use QT_SHAREDPOINTER_TRACK_POINTERS, you have to enable it throughout "
1603 "in your code.", d_ptr);
1604 }
1605
1606 const auto it2 = kp->dataPointers.constFind(it->pointer);
1607 Q_ASSERT(it2 != kp->dataPointers.cend());
1608
1609 //qDebug("Removing d=%p value=%p", d_ptr, it->pointer);
1610
1611 // remove entries
1612 kp->dataPointers.erase(it2);
1613 kp->dPointers.erase(it);
1614 Q_ASSERT(kp->dPointers.size() == kp->dataPointers.size());
1615}
1616
1617/*!
1618 \internal
1619 Called by the QSharedPointer autotest
1620*/
1621void QtSharedPointer::internalSafetyCheckCleanCheck()
1622{
1623# ifdef QT_BUILD_INTERNAL
1624 KnownPointers *const kp = knownPointers();
1625 Q_ASSERT_X(kp, "internalSafetyCheckSelfCheck()", "Called after global statics deletion!");
1626
1627 if (Q_UNLIKELY(kp->dPointers.size() != kp->dataPointers.size()))
1628 qFatal("Internal consistency error: the number of pointers is not equal!");
1629
1630 if (Q_UNLIKELY(!kp->dPointers.isEmpty()))
1631 qFatal("Pointer cleaning failed: %d entries remaining", kp->dPointers.size());
1632# endif
1633}
1634
1635QT_END_NAMESPACE
1636