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 | |
1364 | QT_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 | */ |
1371 | void 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 | */ |
1381 | void 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 | |
1387 | QtSharedPointer::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 | */ |
1422 | QSharedPointer<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 | */ |
1433 | QWeakPointer<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 | |
1439 | QT_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 | |
1461 | QT_BEGIN_NAMESPACE |
1462 | |
1463 | static inline QByteArray saveBacktrace() __attribute__((always_inline)); |
1464 | static 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 | |
1476 | static 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 | |
1524 | QT_END_NAMESPACE |
1525 | |
1526 | # endif // BACKTRACE_SUPPORTED |
1527 | |
1528 | namespace { |
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 | |
1546 | Q_GLOBAL_STATIC(KnownPointers, knownPointers) |
1547 | |
1548 | QT_BEGIN_NAMESPACE |
1549 | |
1550 | namespace QtSharedPointer { |
1551 | Q_AUTOTEST_EXPORT void internalSafetyCheckCleanCheck(); |
1552 | } |
1553 | |
1554 | /*! |
1555 | \internal |
1556 | */ |
1557 | void 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 | */ |
1591 | void 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 | */ |
1621 | void 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 | |
1635 | QT_END_NAMESPACE |
1636 | |