From dbfa6518890f4e6c4af6da92df45803ecfe0309a Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Fri, 21 Dec 2012 10:35:20 -0800 Subject: 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 --- src/corelib/tools/qsharedpointer.cpp | 55 ++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 31 deletions(-) (limited to 'src/corelib/tools/qsharedpointer.cpp') 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 -- cgit v1.2.3