AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: Update the info on the QSharedPointer internals

Browse Source 
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>
This commit is contained in:
Thiago Macieira 2012-12-21 10:35:20 -08:00 committed by The Qt Project
parent 6b9545a980
commit dbfa651889
1 changed files with 24 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
src/corelib/tools/qsharedpointer.cpp
View File

@ -136,23 +136,11 @@
\omit \omit
\secton1 QSharedPointer internals \secton1 QSharedPointer internals
QSharedPointer is in reality implemented by two ancestor classes: QSharedPointer has two "private" members: the pointer itself being tracked
QtSharedPointer::Basic and QtSharedPointer::ExternalRefCount. The reason and a d-pointer. Those members are private to the class, but QSharedPointer
for having that split is now mostly legacy: in the beginning, is friends with QWeakPointer and other QSharedPointer with different
QSharedPointer was meant to support both internal reference counting and template arguments. (On some compilers, template friends are not supported,
external reference counting. so the members are technically public)
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.
The reason for keeping the pointer value itself outside the d-pointer is The reason for keeping the pointer value itself outside the d-pointer is
because of multiple inheritance needs. If you have two QSharedPointer because of multiple inheritance needs. If you have two QSharedPointer
@ -178,17 +166,19 @@
QSharedObject instances that are attached to this Data. QSharedObject instances that are attached to this Data.
When the strong reference count decreases to zero, the object is deleted When the strong reference count decreases to zero, the object is deleted
(see below for information on custom deleters). The strong reference (see below for information on custom deleters). The strong reference count
count can also exceptionally be -1, indicating that there are no can also exceptionally be -1, indicating that there are no QSharedPointers
QSharedPointers attached to an object, which is tracked too. The only attached to an object, which is tracked too. The only case where this is
case where this is possible is that of QWeakPointers tracking a QObject. 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. The weak reference count controls the lifetime of the d-pointer itself.
It can be thought of as an internal/intrusive reference count for It can be thought of as an internal/intrusive reference count for
ExternalRefCountData itself. This count is equal to the number of ExternalRefCountData itself. This count is equal to the number of
QSharedPointers and QWeakPointers that are tracking this object. (In case QSharedPointers and QWeakPointers that are tracking this object. In case
the object tracked derives from QObject, this number is increased by 1, the object is a QObject being tracked by QPointer, this number is increased
since QObjectPrivate tracks it too). by 1, since QObjectPrivate tracks it too.
The third member is a pointer to the function that is used to delete the 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. pointer being tracked. That happens when the destroy() function is called.
@ -199,18 +189,21 @@
\section3 QtSharedPointer::ExternalRefCountWithCustomDeleter \section3 QtSharedPointer::ExternalRefCountWithCustomDeleter
This class derives from ExternalRefCountData and is a This class derives from ExternalRefCountData and is a template class. As
template class. As template parameters, it has the type of the pointer template parameters, it has the type of the pointer being tracked (\tt T)
being tracked (\tt T) and a \tt Deleter, which is anything. It adds two and a \tt Deleter, which is anything. It adds two fields to its parent
fields to its parent class, matching those template parameters: a member class, matching those template parameters: a member of type \tt Deleter and
of type \tt Deleter and a member of type \tt T*. 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 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 deleter code along with the d-pointer. This allows the last strong
reference to call any arbitrary function that disposes of the object. For reference to call any arbitrary function that disposes of the object. For
example, this allows calling QObject::deleteLater() on a given object. 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 pointer to the object is kept here because it needs to match the actual
the deleter in the generic case. deleter function's parameters, regardless of what template argument the
last QSharedPointer instance had.
This class is never instantiated directly: the constructors and This class is never instantiated directly: the constructors and
destructor are private and, in C++11, deleted. Only the create() function destructor are private and, in C++11, deleted. Only the create() function