diff options
author | Thiago Macieira <thiago.macieira@intel.com> | 2012-12-21 10:35:20 -0800 |
---|---|---|
committer | The Qt Project <gerrit-noreply@qt-project.org> | 2013-01-15 03:29:15 +0100 |
commit | dbfa6518890f4e6c4af6da92df45803ecfe0309a (patch) | |
tree | 17be9325e8755e0d706c25ee4bd269ed968c9c1d /src/corelib/tools/qsharedpointer.cpp | |
parent | 6b9545a980f09d8fb034d930cfe67f6110357d0c (diff) |
Doc: Update the info on the QSharedPointer internals
Some of it still referred to classes that were cleaned up in Qt 5.0
Change-Id: Ief4ed4b4fce074884f755b0d18a526ac40ad1b0b
Reviewed-by: Olivier Goffart <ogoffart@woboq.com>
Diffstat (limited to 'src/corelib/tools/qsharedpointer.cpp')
-rw-r--r-- | src/corelib/tools/qsharedpointer.cpp | 55 |
1 files changed, 24 insertions, 31 deletions
diff --git a/src/corelib/tools/qsharedpointer.cpp b/src/corelib/tools/qsharedpointer.cpp index 5455904021..76f1cc69c4 100644 --- a/src/corelib/tools/qsharedpointer.cpp +++ b/src/corelib/tools/qsharedpointer.cpp @@ -136,23 +136,11 @@ \omit \secton1 QSharedPointer internals - QSharedPointer is in reality implemented by two ancestor classes: - QtSharedPointer::Basic and QtSharedPointer::ExternalRefCount. The reason - for having that split is now mostly legacy: in the beginning, - QSharedPointer was meant to support both internal reference counting and - external reference counting. - - QtSharedPointer::Basic implements the basic functionality that is shared - between internal- and external-reference counting. That is, it's mostly - the accessor functions into QSharedPointer. Those are all inherited by - QSharedPointer, which adds another level of shared functionality (the - constructors and assignment operators). The Basic class has one member - variable, which is the actual pointer being tracked. - - QtSharedPointer::ExternalRefCount implements the actual reference - counting and introduces the d-pointer for QSharedPointer. That d-pointer - itself is shared with other QSharedPointer objects as well as - QWeakPointer. + QSharedPointer has two "private" members: the pointer itself being tracked + and a d-pointer. Those members are private to the class, but QSharedPointer + is friends with QWeakPointer and other QSharedPointer with different + template arguments. (On some compilers, template friends are not supported, + so the members are technically public) The reason for keeping the pointer value itself outside the d-pointer is because of multiple inheritance needs. If you have two QSharedPointer @@ -178,17 +166,19 @@ QSharedObject instances that are attached to this Data. When the strong reference count decreases to zero, the object is deleted - (see below for information on custom deleters). The strong reference - count can also exceptionally be -1, indicating that there are no - QSharedPointers attached to an object, which is tracked too. The only - case where this is possible is that of QWeakPointers tracking a QObject. + (see below for information on custom deleters). The strong reference count + can also exceptionally be -1, indicating that there are no QSharedPointers + attached to an object, which is tracked too. The only case where this is + possible is that of QWeakPointers and QPointers tracking a QObject. Note + that QWeakPointers tracking a QObject is a deprecated feature as of Qt 5.0, + kept only for compatibility with Qt 4.x. The weak reference count controls the lifetime of the d-pointer itself. It can be thought of as an internal/intrusive reference count for ExternalRefCountData itself. This count is equal to the number of - QSharedPointers and QWeakPointers that are tracking this object. (In case - the object tracked derives from QObject, this number is increased by 1, - since QObjectPrivate tracks it too). + QSharedPointers and QWeakPointers that are tracking this object. In case + the object is a QObject being tracked by QPointer, this number is increased + by 1, since QObjectPrivate tracks it too. The third member is a pointer to the function that is used to delete the pointer being tracked. That happens when the destroy() function is called. @@ -199,18 +189,21 @@ \section3 QtSharedPointer::ExternalRefCountWithCustomDeleter - This class derives from ExternalRefCountData and is a - template class. As template parameters, it has the type of the pointer - being tracked (\tt T) and a \tt Deleter, which is anything. It adds two - fields to its parent class, matching those template parameters: a member - of type \tt Deleter and a member of type \tt T*. + This class derives from ExternalRefCountData and is a template class. As + template parameters, it has the type of the pointer being tracked (\tt T) + and a \tt Deleter, which is anything. It adds two fields to its parent + class, matching those template parameters: a member of type \tt Deleter and + a member of type \tt T*. Those members are actually inside a template + struct of type CustomDeleter, which is partially-specialized for normal + deletion. See below for more details on that. The purpose of this class is to store the pointer to be deleted and the deleter code along with the d-pointer. This allows the last strong reference to call any arbitrary function that disposes of the object. For example, this allows calling QObject::deleteLater() on a given object. - The pointer to the object is kept here to avoid the extra cost of keeping - the deleter in the generic case. + The pointer to the object is kept here because it needs to match the actual + deleter function's parameters, regardless of what template argument the + last QSharedPointer instance had. This class is never instantiated directly: the constructors and destructor are private and, in C++11, deleted. Only the create() function |