Internal doc: explain how QSharedPointer works

1 files changed, 39 insertions, 18 deletions

diff --git a/src/corelib/tools/qsharedpointer_impl.h b/src/corelib/tools/qsharedpointer_impl.h
index ba479f9cce..cbeb79ff3c 100644
--- a/src/corelib/tools/qsharedpointer_impl.h
+++ b/src/corelib/tools/qsharedpointer_impl.h
@@ -115,6 +115,9 @@ namespace QtSharedPointer {
     template <class T> struct RemovePointer<QSharedPointer<T> > { typedef T Type; };
     template <class T> struct RemovePointer<QWeakPointer<T> > { typedef T Type; };
 
+    // This class provides the basic functionality of a pointer wrapper.
+    // Its existence is mostly legacy, since originally QSharedPointer
+    // could also be used for internally-refcounted objects.
     template <class T>
     class Basic
     {
@@ -155,6 +158,12 @@ namespace QtSharedPointer {
         Type *value;
     };
 
+    // This class is the d-pointer of QSharedPointer and QWeakPointer.
+    //
+    // It is a reference-counted reference counter. "strongref" is the inner
+    // reference counter, and it tracks the lifetime of the pointer itself.
+    // "weakref" is the outer reference counter and it tracks the lifetime of
+    // the ExternalRefCountData object.
     struct ExternalRefCountData
     {
         QBasicAtomicInt weakref;
@@ -168,6 +177,9 @@ namespace QtSharedPointer {
         inline ExternalRefCountData(Qt::Initialization) { }
         virtual inline ~ExternalRefCountData() { Q_ASSERT(!weakref); Q_ASSERT(strongref <= 0); }
 
+        // overridden by derived classes
+        // returns false to indicate caller should delete the pointer
+        // returns true in case it has already done so
         virtual inline bool destroy() { return false; }
 
 #ifndef QT_NO_QOBJECT
@@ -178,18 +190,8 @@ namespace QtSharedPointer {
     };
     // sizeof(ExternalRefCount) = 12 (32-bit) / 16 (64-bit)
 
-    template <class T, typename Deleter>
-    struct CustomDeleter
-    {
-        Deleter deleter;
-        T *ptr;
-
-        inline CustomDeleter(T *p, Deleter d) : deleter(d), ptr(p) {}
-    };
-    // sizeof(CustomDeleter) = sizeof(Deleter) + sizeof(void*)
-    // for Deleter = function pointer:  8 (32-bit) / 16 (64-bit)
-    // for Deleter = PMF: 12 (32-bit) / 24 (64-bit)  (GCC)
-
+    // This class extends ExternalRefCountData with a pointer
+    // to a function, which is called by the destroy() function.
     struct ExternalRefCountWithDestroyFn: public ExternalRefCountData
     {
         typedef void (*DestroyerFn)(ExternalRefCountData *);
@@ -204,13 +206,26 @@ namespace QtSharedPointer {
     };
     // sizeof(ExternalRefCountWithDestroyFn) = 16 (32-bit) / 24 (64-bit)
 
+    // This class extends ExternalRefCountWithDestroyFn and implements
+    // the static function that deletes the object. The pointer and the
+    // custom deleter are kept in the "extra" member.
     template <class T, typename Deleter>
     struct ExternalRefCountWithCustomDeleter: public ExternalRefCountWithDestroyFn
     {
         typedef ExternalRefCountWithCustomDeleter Self;
-        typedef ExternalRefCountWithDestroyFn Parent;
-        typedef CustomDeleter<T, Deleter> Next;
-        Next extra;
+        typedef ExternalRefCountWithDestroyFn BaseClass;
+
+        struct CustomDeleter
+        {
+            Deleter deleter;
+            T *ptr;
+
+            inline CustomDeleter(T *p, Deleter d) : deleter(d), ptr(p) {}
+        };
+        CustomDeleter extra;
+        // sizeof(CustomDeleter) = sizeof(Deleter) + sizeof(void*)
+        // for Deleter = function pointer:  8 (32-bit) / 16 (64-bit)
+        // for Deleter = PMF: 12 (32-bit) / 24 (64-bit)  (GCC)
 
         static inline void deleter(ExternalRefCountData *self)
         {
@@ -218,7 +233,7 @@ namespace QtSharedPointer {
             executeDeleter(realself->extra.ptr, realself->extra.deleter);
 
             // delete the deleter too
-            realself->extra.~Next();
+            realself->extra.~CustomDeleter();
         }
         static void safetyCheckDeleter(ExternalRefCountData *self)
         {
@@ -236,8 +251,8 @@ namespace QtSharedPointer {
             Self *d = static_cast<Self *>(::operator new(sizeof(Self)));
 
             // initialize the two sub-objects
-            new (&d->extra) Next(ptr, userDeleter);
-            new (d) Parent(destroy); // can't throw
+            new (&d->extra) CustomDeleter(ptr, userDeleter);
+            new (d) BaseClass(destroy); // can't throw
 
             return d;
         }
@@ -247,6 +262,10 @@ namespace QtSharedPointer {
         ~ExternalRefCountWithCustomDeleter();
     };
 
+    // This class extends ExternalRefCountWithDestroyFn and adds a "T"
+    // member. That way, when the create() function is called, we allocate
+    // memory for both QSharedPointer's d-pointer and the actual object being
+    // tracked.
     template <class T>
     struct ExternalRefCountWithContiguousData: public ExternalRefCountWithDestroyFn
     {
@@ -289,6 +308,8 @@ namespace QtSharedPointer {
         ~ExternalRefCountWithContiguousData();
     };
 
+    // This is the main body of QSharedPointer. It implements the
+    // external reference counting functionality.
     template <class T>
     class ExternalRefCount: public Basic<T>
     {