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

QSharedPointer<T> create()
QSharedPointer<T> create(...)

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.