QSharedPointer Class
The QSharedPointer class holds a strong reference to a shared pointer. More...
Header: | #include <QSharedPointer> |
qmake: | QT += core |
Since: | Qt 4.5 |
Note: All functions in this class are reentrant.
Public Functions
QSharedPointer() | |
QSharedPointer(X *ptr) | |
QSharedPointer(X *ptr, Deleter d) | |
QSharedPointer(std::nullptr_t) | |
QSharedPointer(std::nullptr_t, Deleter d) | |
QSharedPointer(const QSharedPointer<T> &other) | |
QSharedPointer(const int &other) | |
~QSharedPointer() | |
void | clear() |
QSharedPointer<X> | constCast() const |
T * | data() const |
QSharedPointer<X> | dynamicCast() const |
T * | get() const |
bool | isNull() const |
QSharedPointer<X> | objectCast() const |
void | reset() |
void | reset(T *t) |
void | reset(T *t, Deleter deleter) |
QSharedPointer<X> | staticCast() const |
void | swap(QSharedPointer<T> &other) |
int | toWeakRef() const |
bool | operator bool() const |
bool | operator!() const |
T & | operator*() const |
T * | operator->() const |
QSharedPointer<T> & | operator=(const QSharedPointer<T> &other) |
QSharedPointer<T> & | operator=(const int &other) |
Static Public Members
Detailed Description
The QSharedPointer class holds a strong reference to a shared pointer.
The QSharedPointer is an automatic, shared pointer in C++. It behaves exactly like a normal pointer for normal purposes, including respect for constness.
QSharedPointer will delete the pointer it is holding when it goes out of scope, provided no other QSharedPointer objects are referencing it.
A QSharedPointer object can be created from a normal pointer, another QSharedPointer object or by promoting a QWeakPointer object to a strong reference.
Thread-Safety
QSharedPointer and QWeakPointer are thread-safe and operate atomically on the pointer value. Different threads can also access the QSharedPointer or QWeakPointer pointing to the same object at the same time without need for locking mechanisms.
It should be noted that, while the pointer value can be accessed in this manner, QSharedPointer and QWeakPointer provide no guarantee about the object being pointed to. Thread-safety and reentrancy rules for that object still apply.
Other Pointer Classes
Qt also provides two other pointer wrapper classes: QPointer and QSharedDataPointer. They are incompatible with one another, since each has its very different use case.
QSharedPointer holds a shared pointer by means of an external reference count (i.e., a reference counter placed outside the object). Like its name indicates, the pointer value is shared among all instances of QSharedPointer and QWeakPointer. The contents of the object pointed to by the pointer should not be considered shared, however: there is only one object. For that reason, QSharedPointer does not provide a way to detach or make copies of the pointed object.
QSharedDataPointer, on the other hand, holds a pointer to shared data (i.e., a class derived from QSharedData). It does so by means of an internal reference count, placed in the QSharedData base class. This class can, therefore, detach based on the type of access made to the data being guarded: if it's a non-const access, it creates a copy atomically for the operation to complete.
QExplicitlySharedDataPointer is a variant of QSharedDataPointer, except that it only detaches if QExplicitlySharedDataPointer::detach() is explicitly called (hence the name).
QScopedPointer simply holds a pointer to a heap allocated object and deletes it in its destructor. This class is useful when an object needs to be heap allocated and deleted, but no more. QScopedPointer is lightweight, it makes no use of additional structure or reference counting.
Finally, QPointer holds a pointer to a QObject-derived object, but it does so weakly. QWeakPointer has the same functionality, but its use for that function is deprecated.
Optional Pointer Tracking
A feature of QSharedPointer that can be enabled at compile-time for debugging purposes is a pointer tracking mechanism. When enabled, QSharedPointer registers in a global set all the pointers that it tracks. This allows one to catch mistakes like assigning the same pointer to two QSharedPointer objects.
This function is enabled by defining the QT_SHAREDPOINTER_TRACK_POINTERS
macro before including the QSharedPointer header.
It is safe to use this feature even with code compiled without the feature. QSharedPointer will ensure that the pointer is removed from the tracker even from code compiled without pointer tracking.
Note, however, that the pointer tracking feature has limitations on multiple- or virtual-inheritance (that is, in cases where two different pointer addresses can refer to the same object). In that case, if a pointer is cast to a different type and its value changes, QSharedPointer's pointer tracking mechanism may fail to detect that the object being tracked is the same.
See also QSharedDataPointer, QWeakPointer, QScopedPointer, and QEnableSharedFromThis.
Member Function Documentation
QSharedPointer::QSharedPointer()
Default constructs an instance of QSharedPointer.
QSharedPointer::QSharedPointer(X *ptr)
Default constructs an instance of QSharedPointer.
QSharedPointer::QSharedPointer(X *ptr, Deleter d)
Default constructs an instance of QSharedPointer.
QSharedPointer::QSharedPointer(std::nullptr_t)
Default constructs an instance of QSharedPointer.
QSharedPointer::QSharedPointer(std::nullptr_t, Deleter d)
Default constructs an instance of QSharedPointer.
QSharedPointer::QSharedPointer(const QSharedPointer<T> &other)
Default constructs an instance of QSharedPointer.
QSharedPointer::QSharedPointer(const int &other)
Default constructs an instance of QSharedPointer.
QSharedPointer::~QSharedPointer()
Destroys the instance of QSharedPointer.
void QSharedPointer::clear()
QSharedPointer<X> QSharedPointer::constCast() const
[static]
QSharedPointer<T> QSharedPointer::create()
[static]
QSharedPointer<T> QSharedPointer::create(...)
T *QSharedPointer::data() const
QSharedPointer<X> QSharedPointer::dynamicCast() const
T *QSharedPointer::get() const
bool QSharedPointer::isNull() const
QSharedPointer<X> QSharedPointer::objectCast() const
void QSharedPointer::reset()
void QSharedPointer::reset(T *t)
void QSharedPointer::reset(T *t, Deleter deleter)
QSharedPointer<X> QSharedPointer::staticCast() const
void QSharedPointer::swap(QSharedPointer<T> &other)
int QSharedPointer::toWeakRef() const
bool QSharedPointer::operator bool() const
bool QSharedPointer::operator!() const
T &QSharedPointer::operator*() const
T *QSharedPointer::operator->() const
QSharedPointer<T> &QSharedPointer::operator=(const QSharedPointer<T> &other)
Copy-assignment operator.
QSharedPointer<T> &QSharedPointer::operator=(const int &other)
Copy-assignment operator.