Contents

• Public Functions
• Related Non-Members
• Detailed Description
• Tracking QObject

Detailed Description

TheQWeakPointer class holds a weak reference to a shared pointer

TheQWeakPointer is an automatic weak reference to a pointer in C++. It cannot be used to dereference the pointer directly, but it can be used to verify if the pointer has been deleted or not in another context.

QWeakPointer objects can only be created by assignment from aQSharedPointer. The exception is pointers derived fromQObject: in that case,QWeakPointer serves as a replacement toQPointer.

It's important to note thatQWeakPointer provides no automatic casting operators to prevent mistakes from happening. Even thoughQWeakPointer tracks a pointer, it should not be considered a pointer itself, since it doesn't guarantee that the pointed object remains valid.

Therefore, to access the pointer thatQWeakPointer is tracking, you must first promote it toQSharedPointer and verify if the resulting object is null or not.QSharedPointer guarantees that the object isn't deleted, so if you obtain a non-null object, you may use the pointer. SeeQWeakPointer::toStrongRef() for an example.

QWeakPointer also provides theQWeakPointer::data() method that returns the tracked pointer without ensuring that it remains valid. This function is provided if you can guarantee by external means that the object will not get deleted (or if you only need the pointer value) and the cost of creating aQSharedPointer usingtoStrongRef() is too high.

That function can also be used to obtain the tracked pointer for QWeakPointers that cannot be promoted toQSharedPointer, such as those created directly from aQObject pointer (not viaQSharedPointer).

Tracking QObject

QWeakPointer can be used to track deletion of classes that derive fromQObject, even if they are not managed byQSharedPointer. When used in that role,QWeakPointer replaces the olderQPointer in all use-cases.QWeakPointer is also more efficient thanQPointer, so it should be preferred in all new code.

To do that,QWeakPointer provides a special constructor that is only available if the template parameterT is eitherQObject or a class deriving from it. Trying to use that constructor ifT does not derive fromQObject will result in compilation errors.

To obtain theQObject being tracked byQWeakPointer, you must use theQWeakPointer::data() function, but only if you can guarantee that the object cannot get deleted by another context. It should be noted thatQPointer had the same constraint, so use ofQWeakPointer forces you to consider whether the pointer is still valid.

QObject-derived classes can only be deleted in the thread they have affinity to (which is the thread they were created in or moved to, usingQObject::moveToThread()). In special,QWidget-derived classes cannot be created in non-GUI threads nor moved there. Therefore, guaranteeing that the trackedQObject has affinity to the current thread is enough to also guarantee that it won't be deleted asynchronously.

Note thatQWeakPointer's size and data layout do not matchQPointer, so it cannot replace that class in a binary-compatible manner.

Care must also be taken with QWeakPointers created directly fromQObject pointers when dealing with code that was compiled with Qt versions prior to 4.6. Those versions may not track the reference counters correctly, so QWeakPointers created fromQObject should never be passed to code that hasn't been recompiled.

Member Function Documentation

QWeakPointer::QWeakPointer()

Creates aQWeakPointer that points to nothing.

QWeakPointer::QWeakPointer(constQWeakPointer<T> & other)

Creates aQWeakPointer that holds a weak reference to the pointer referenced byother.

IfT is a derived type of the template parameter of this class,QWeakPointer will perform an automatic cast. Otherwise, you will get a compiler error.

QWeakPointer::QWeakPointer(constQSharedPointer<T> & other)

Creates aQWeakPointer that holds a weak reference to the pointer referenced byother.

IfT is a derived type of the template parameter of this class,QWeakPointer will perform an automatic cast. Otherwise, you will get a compiler error.

QWeakPointer::QWeakPointer(constQObject * obj)

Creates aQWeakPointer that holds a weak reference directly to theQObjectobj. This constructor is only available if the template typeT isQObject or derives from it (otherwise a compilation error will result).

You can use this constructor with anyQObject, even if they were not created withQSharedPointer.

Note that QWeakPointers created this way on arbitraryQObjects usually cannot be promoted toQSharedPointer.

This function was introduced in Qt 4.6.

See alsoQSharedPointer andQWeakPointer#tracking-qobject.

QWeakPointer::~QWeakPointer()

Destroys thisQWeakPointer object. The pointer referenced by this object will not be deleted.

void QWeakPointer::clear()

Clears thisQWeakPointer object, dropping the reference that it may have had to the pointer.

T * QWeakPointer::data() const

Returns the value of the pointer being tracked by thisQWeakPointer,without ensuring that it cannot get deleted. To have that guarantee, usetoStrongRef(), which returns aQSharedPointer object. If this function can determine that the pointer has already been deleted, it returns 0.

It is ok to obtain the value of the pointer and using that value itself, like for example in debugging statements:

qDebug("Tracking %p", weakref.data());

However, dereferencing the pointer is only allowed if you can guarantee by external means that the pointer does not get deleted. For example, if you can be certain that no other thread can delete it, nor the functions that you may call.

If that is the case, then the following code is valid:

// this pointer cannot be used in another thread// so other threads cannot delete itQWeakPointer<int> weakref= obtainReference();Object*obj= weakref.data();if (obj) {// if the pointer wasn't deleted yet, we know it can't get// deleted by our own code here nor the functions we call    otherFunction(obj);}

Use this function with care.

This function was introduced in Qt 4.6.

See alsoisNull() andtoStrongRef().

bool QWeakPointer::isNull() const

Returns true if this object is holding a reference to a null pointer.

Note that, due to the nature of weak references, the pointer thatQWeakPointer references can become null at any moment, so the value returned from this function can change from false to true from one call to the next.

QSharedPointer<T> QWeakPointer::toStrongRef() const

Promotes this weak reference to a strong one and returns aQSharedPointer object holding that reference. When promoting toQSharedPointer, this function verifies if the object has been deleted already or not. If it hasn't, this function increases the reference count to the shared object, thus ensuring that it will not get deleted.

Since this function can fail to obtain a valid strong reference to the shared object, you should always verify if the conversion succeeded, by callingQSharedPointer::isNull() on the returned object.

For example, the following code promotes aQWeakPointer that was held to a strong reference and, if it succeeded, it prints the value of the integer that was held:

QWeakPointer<int> weakref;// ...QSharedPointer<int> strong= weakref.toStrongRef();if (strong)qDebug()<<"The value is:"<<*strong;elseqDebug()<<"The value has already been deleted";

See alsoQSharedPointer::QSharedPointer().

QWeakPointer::operator bool() const

Returns true if this object is not null. This function is suitable for use inif-constructs, like:

if (weakref) {... }

Note that, due to the nature of weak references, the pointer thatQWeakPointer references can become null at any moment, so the value returned from this function can change from true to false from one call to the next.

See alsoisNull().

bool QWeakPointer::operator!() const

Returns true if this object is null. This function is suitable for use inif-constructs, like:

if (!weakref) {... }

Note that, due to the nature of weak references, the pointer thatQWeakPointer references can become null at any moment, so the value returned from this function can change from false to true from one call to the next.

See alsoisNull().

QWeakPointer<T> QWeakPointer::operator=(constQWeakPointer<T> & other)

Makes this object shareother's pointer. The current pointer reference is discarded but is not deleted.

IfT is a derived type of the template parameter of this class,QWeakPointer will perform an automatic cast. Otherwise, you will get a compiler error.

QWeakPointer<T> QWeakPointer::operator=(constQSharedPointer<T> & other)

Makes this object shareother's pointer. The current pointer reference is discarded but is not deleted.

IfT is a derived type of the template parameter of this class,QWeakPointer will perform an automatic cast. Otherwise, you will get a compiler error.

QWeakPointer<T> QWeakPointer::operator=(constQObject * obj)

Makes thisQWeakPointer hold a weak reference directly to theQObjectobj. This function is only available if the template typeT isQObject or derives from it.

This function was introduced in Qt 4.6.

See alsoQWeakPointer#tracking-qobject.

Related Non-Members

QSharedPointer<X>qSharedPointerCast(constQWeakPointer<T> & other)

Returns a shared pointer to the pointer held byother, cast to typeX. The typesT andX must belong to one hierarchy for thestatic_cast to succeed.

Theother object is converted first to a strong reference. If that conversion fails (because the object it's pointing to has already been deleted), this function returns a nullQSharedPointer.

Note thatX must have the same cv-qualifiers (const andvolatile) thatT has, or the code will fail to compile. UseqSharedPointerConstCast to cast away the constness.

See alsoQWeakPointer::toStrongRef(),qSharedPointerDynamicCast(), andqSharedPointerConstCast().

QSharedPointer<X>qSharedPointerConstCast(constQWeakPointer<T> & other)

Returns a shared pointer to the pointer held byother, cast to typeX. The typesT andX must belong to one hierarchy for theconst_cast to succeed. Theconst andvolatile differences betweenT andX are ignored.

Theother object is converted first to a strong reference. If that conversion fails (because the object it's pointing to has already been deleted), this function returns a nullQSharedPointer.

See alsoQWeakPointer::toStrongRef(),qSharedPointerCast(), andqSharedPointerDynamicCast().

QSharedPointer<X>qSharedPointerDynamicCast(constQWeakPointer<T> & other)

Returns a shared pointer to the pointer held byother, using a dynamic cast to typeX to obtain an internal pointer of the appropriate type. If thedynamic_cast fails, the object returned will be null.

Theother object is converted first to a strong reference. If that conversion fails (because the object it's pointing to has already been deleted), this function also returns a nullQSharedPointer.

Note thatX must have the same cv-qualifiers (const andvolatile) thatT has, or the code will fail to compile. UseqSharedPointerConstCast to cast away the constness.

See alsoQWeakPointer::toStrongRef(),qSharedPointerCast(), andqSharedPointerConstCast().

QSharedPointer<X>qSharedPointerObjectCast(constQWeakPointer<T> & other)

TheqSharedPointerObjectCast function is for casting a shared pointer.

Returns a shared pointer to the pointer held byother, using aqobject_cast() to typeX to obtain an internal pointer of the appropriate type. If theqobject_cast fails, the object returned will be null.

Theother object is converted first to a strong reference. If that conversion fails (because the object it's pointing to has already been deleted), this function also returns a nullQSharedPointer.

Note thatX must have the same cv-qualifiers (const andvolatile) thatT has, or the code will fail to compile. UseqSharedPointerConstCast to cast away the constness.

This function was introduced in Qt 4.6.

See alsoQWeakPointer::toStrongRef(),qSharedPointerCast(), andqSharedPointerConstCast().

QWeakPointer<X>qWeakPointerCast(constQWeakPointer<T> & other)

Returns a weak pointer to the pointer held byother, cast to typeX. The typesT andX must belong to one hierarchy for thestatic_cast to succeed.

Note thatX must have the same cv-qualifiers (const andvolatile) thatT has, or the code will fail to compile. UseqSharedPointerConstCast to cast away the constness.

booloperator!=(constQWeakPointer<T> & ptr1, constQSharedPointer<X> & ptr2)

Returns true if the pointer referenced byptr1 is not the same pointer as that referenced byptr2.

Ifptr2's template parameter is different fromptr1's,QSharedPointer will attempt to perform an automaticstatic_cast to ensure that the pointers being compared are equal. Ifptr2's template parameter is not a base or a derived type fromptr1's, you will get a compiler error.

booloperator!=(constQSharedPointer<T> & ptr1, constQWeakPointer<X> & ptr2)

Returns true if the pointer referenced byptr1 is not the same pointer as that referenced byptr2.

Ifptr2's template parameter is different fromptr1's,QSharedPointer will attempt to perform an automaticstatic_cast to ensure that the pointers being compared are equal. Ifptr2's template parameter is not a base or a derived type fromptr1's, you will get a compiler error.

booloperator==(constQWeakPointer<T> & ptr1, constQSharedPointer<X> & ptr2)

Returns true if the pointer referenced byptr1 is the same pointer as that referenced byptr2.

Ifptr2's template parameter is different fromptr1's,QSharedPointer will attempt to perform an automaticstatic_cast to ensure that the pointers being compared are equal. Ifptr2's template parameter is not a base or a derived type fromptr1's, you will get a compiler error.

booloperator==(constQSharedPointer<T> & ptr1, constQWeakPointer<X> & ptr2)

Returns true if the pointer referenced byptr1 is the same pointer as that referenced byptr2.

Ifptr2's template parameter is different fromptr1's,QSharedPointer will attempt to perform an automaticstatic_cast to ensure that the pointers being compared are equal. Ifptr2's template parameter is not a base or a derived type fromptr1's, you will get a compiler error.