QScopedPointer Class Reference
[QtCore module]

Detailed Description

The QScopedPointer class stores a pointer to a dynamically allocated object, and deletes it upon destruction.

Managing heap allocated objects manually is hard and error prone, with the common result that code leaks memory and is hard to maintain. QScopedPointer is a small utility class that heavily simplifies this by assigning stack-based memory ownership to heap allocations, more generally called resource acquisition is initialization(RAII).

QScopedPointer guarantees that the object pointed to will get deleted when the current scope disappears.

Consider this function which does heap allocations, and have various exit points:

 void myFunction(bool useSubClass)
 {
     MyClass *p = useSubClass ? new MyClass() : new MySubClass;
     QIODevice *device = handsOverOwnership();

     if (m_value > 3) {
         delete p;
         delete device;
         return;
     }

     try {
         process(device);
     }
     catch (...) {
         delete p;
         delete device;
         throw;
     }

     delete p;
     delete device;
 }

It's encumbered by the manual delete calls. With QScopedPointer, the code can be simplified to:

 void myFunction(bool useSubClass)
 {
     // assuming that MyClass has a virtual destructor
     QScopedPointer<MyClass> p(useSubClass ? new MyClass() : new MySubClass);
     QScopedPointer<QIODevice> device(handsOverOwnership());

     if (m_value > 3)
         return;

     process(device);
 }

The code the compiler generates for QScopedPointer is the same as when writing it manually. Code that makes use of delete are candidates for QScopedPointer usage (and if not, possibly another type of smart pointer such as QSharedPointer). QScopedPointer intentionally has no copy constructor or assignment operator, such that ownership and lifetime is clearly communicated.

The const qualification on a regular C++ pointer can also be expressed with a QScopedPointer:

     const QWidget *const p = new QWidget();
     // is equivalent to:
     const QScopedPointer<const QWidget> p(new QWidget());

     QWidget *const p = new QWidget();
     // is equivalent to:
     const QScopedPointer<QWidget> p(new QWidget());

     QWidget *const p = new QWidget();
     // is equivalent to:
     const QScopedPointer<QWidget> p(new QWidget());

     const QWidget *p = new QWidget();
     // is equivalent to:
     QScopedPointer<const QWidget> p(new QWidget());

 // this QScopedPointer deletes its data using the delete[] operator:
 QScopedPointer<int, QScopedPointerArrayDeleter<int> > arrayPointer(new int[42]);

 // this QScopedPointer frees its data using free():
 QScopedPointer<int, QScopedPointerPodDeleter> podPointer(reinterpret_cast<int *>(malloc(42)));

 // this struct calls "myCustomDeallocator" to delete the pointer
 struct ScopedPointerCustomDeleter
 {
     static inline void cleanup(MyCustomClass *pointer)
     {
         myCustomDeallocator(pointer);
     }
 };

 // QScopedPointer using a custom deleter:
 QScopedPointer<MyCustomClass, ScopedPointerCustomDeleter> customPointer(new MyCustomClass);

 class MyPrivateClass; // forward declare MyPrivateClass

 class MyClass
 {
 private:
     QScopedPointer<MyPrivateClass> privatePtr; // QScopedPointer to forward declared class

 public:
     MyClass(); // OK
     inline ~MyClass() {} // VIOLATION - Destructor must not be inline

 private:
     Q_DISABLE_COPY(MyClass) // OK - copy constructor and assignment operators
                              // are now disabled, so the compiler won't implicitely
                              // generate them.
 };

 if (scopedPointer) {
     ...
 }