QSharedDataPointer Class Reference
[QtCore module]

Suppose you want to make an Employee class implicitly shared. The procedure is:

• Define the class Employee to have a single data member of type QSharedDataPointer<EmployeeData>.
• Define the EmployeeData class derived from QSharedData to contain all the data members you would normally have put in the Employee class.

To show this in practice, we review the source code for the implicitly shared Employee class. In the header file we define the two classes Employee and EmployeeData.

 #include <QSharedData>
 #include <QString>

 class EmployeeData : public QSharedData
 {
   public:
     EmployeeData() : id(-1) { name.clear(); }
     EmployeeData(const EmployeeData &other)
         : QSharedData(other), id(other.id), name(other.name) { }
     ~EmployeeData() { }

     int id;
     QString name;
 };

 class Employee
 {
   public:
     Employee() { d = new EmployeeData; }
     Employee(int id, QString name) {
         d = new EmployeeData;
         setId(id);
         setName(name);
     }
     Employee(const Employee &other)
           : d (other.d)
     {
     }
     void setId(int id) { d->id = id; }
     void setName(QString name) { d->name = name; }

     int id() const { return d->id; }
     QString name() const { return d->name; }

   private:
     QSharedDataPointer<EmployeeData> d;
 };

In class Employee, note the single data member, a d pointer of type QSharedDataPointer<EmployeeData>. All accesses of employee data must go through the d pointer's operator->(). For write accesses, operator->() will automatically call detach(), which creates a copy of the shared data object if the shared data object's reference count is greater than 1. This ensures that writes to one Employee object don't affect any other Employee objects that share the same EmployeeData object.

Class EmployeeData inherits QSharedData, which provides the behind the scenes reference counter. EmployeeData has a default constructor, a copy constructor, and a destructor. Normally, trivial implementations of these are all that is needed in the data class for an implicitly shared class.

Implementing the two constructors for class Employee is also straightforward. Both create a new instance of EmployeeData and assign it to the d pointer .

     Employee() { d = new EmployeeData; }

     Employee(int id, QString name) {
         d = new EmployeeData;
         setId(id);
         setName(name);
     }

Note that class Employee also has a trivial copy constructor defined, which is not strictly required in this case.

     Employee(const Employee &other)
           : d (other.d)
     {
     }

The copy constructor is not strictly required here, because class EmployeeData is included in the same file as class Employee (employee.h). However, including the private subclass of QSharedData in the same file as the public class containing the QSharedDataPointer is not typical. Normally, the idea is to hide the private subclass of QSharedData from the user by putting it in a separate file which would not be included in the public file. In this case, we would normally put class EmployeeData in a separate file, which would not be included in employee.h. Instead, we would just predeclare the private subclass EmployeeData in employee.h this way:

 class EmployeeData;

If we had done it that way here, the copy constructor shown would be required. Since the copy constructor is trivial, you might as well just always include it.

Behind the scenes, QSharedDataPointer automatically increments the reference count whenever an Employee object is copied, assigned, or passed as a parameter. It decrements the reference count whenever an Employee object is deleted or goes out of scope. The shared EmployeeData object is deleted automatically if and when the reference count reaches 0.

In a non-const member function of Employee, whenever the d pointer is dereferenced, QSharedDataPointer automatically calls detach() to ensure that the function operates on its own copy of the data.

     void setId(int id) { d->id = id; }

     void setName(QString name) { d->name = name; }

Note that if detach() is called more than once in a member function due to multiple dereferences of the d pointer, detach() will only create a copy of the shared data the first time it is called, if at all, because on the second and subsequent calls of detach(), the reference count will be 1 again.

But note that in the second Employee constructor, which takes an employee ID and a name, both setId() and setName() are called, but they don't cause copy on write, because the reference count for the newly constructed EmployeeData object has just been set to 1.

In Employee's const member functions, dereferencing the d pointer does not cause detach() to be called.

     int id() const { return d->id; }

     QString name() const { return d->name; }

Notice that there is no need to implement a copy constructor or an assignment operator for the Employee class, because the copy constructor and assignment operator provided by the C++ compiler will do the member by member shallow copy required. The only member to copy is the d pointer, which is a QSharedDataPointer, whose operator=() just increments the reference count of the shared EmployeeData object.

 #include "employee.h"

 int main()
 {
     Employee e1(1001, "Albrecht Durer");
     Employee e2 = e1;
     e1.setName("Hans Holbein");
 }

 template<>
 EmployeeData *QSharedDataPointer<EmployeeData>::clone()
 {
     return d->clone();
 }