QSharedDataPointer Class | Qt Core 6.4.1

- Qt 6.4
- Qt Core
- C++ Classes
- QSharedDataPointer
- Qt 6.4.1 Reference Documentation

# QSharedDataPointer Class

template <typename T> class QSharedDataPointer

The QSharedDataPointer class represents a pointer to an implicitly shared object. More...

Header: | #include <QSharedDataPointer>
CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: | QT += core

- List of all members, including inherited members

Note: All functions in this class are reentrant.

## Public Types

| Type

## Public Functions

| QSharedDataPointer(QSharedDataPointer<T> &&o)
| QSharedDataPointer(const QSharedDataPointer<T> &o)
| QSharedDataPointer(T *data, QAdoptSharedDataTag)
| QSharedDataPointer(T *data)
| QSharedDataPointer()
QSharedDataPointer<T> & | operator=(QSharedDataPointer<T> &&other)
QSharedDataPointer<T> & | operator=(const QSharedDataPointer<T> &o)
| ~QSharedDataPointer()
const T * | constData() const
T * | data()
const T * | data() const
void | detach()
T * | get()
const T * | get() const
void | reset(T *ptr = nullptr)
void | swap(QSharedDataPointer<T> &other)
T * | take()
T * | operator T *()
const T * | operator const T *() const
bool | operator!() const
T & | operator*()
const T & | operator*() const
T * | operator->()
const T * | operator->() const
QSharedDataPointer<T> & | operator=(T *o)

## Protected Functions

T * | clone()

## Related Non-Members

bool | operator!=(const QSharedDataPointer<T> &lhs, const QSharedDataPointer<T> &rhs)
bool | operator!=(const T *ptr, const QSharedDataPointer<T> &rhs)
bool | operator==(const QSharedDataPointer<T> &lhs, const QSharedDataPointer<T> &rhs)
bool | operator==(const T *ptr, const QSharedDataPointer<T> &rhs)

## Detailed Description

QSharedDataPointer<T> makes writing your own implicitly shared classes easy. QSharedDataPointer implements thread-safe reference counting, ensuring that adding QSharedDataPointers to your reentrant classes won't make them non-reentrant.

Implicit sharing is used by many Qt classes to combine the speed and memory efficiency of pointers with the ease of use of classes. See the Shared Classes page for more information.

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) { }
         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, const 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(const 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, const 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(const 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.

### Implicit vs Explicit Sharing

Implicit sharing might not be right for the `Employee` class. Consider a simple example that creates two instances of the implicitly shared `Employee` class.

     #include "employee.h"

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

After the second employee e2 is created and e1 is assigned to it, both `e1` and `e2` refer to Albrecht Durer, employee 1001. Both `Employee` objects point to the same instance of `EmployeeData`, which has reference count 2. Then `e1.setName("Hans Holbein")` is called to change the employee name, but because the reference count is greater than 1, a copy on write is performed before the name is changed. Now `e1` and `e2` point to different `EmployeeData` objects. They have different names, but both have ID 1001, which is probably not what you want. You can, of course, just continue with `e1.setId(1002)`, if you really mean to create a second, unique employee, but if you only want to change the employee's name everywhere, consider using explicit sharing in the `Employee` class instead of implicit sharing.

If you declare the d pointer in the `Employee` class to be `QExplicitlySharedDataPointer<EmployeeData>`, then explicit sharing is used and copy on write operations are not performed automatically (i.e. detach() is not called in non-const functions). In that case, after `e1.setName("Hans Holbein")`, the employee's name has been changed, but both e1 and e2 still refer to the same instance of `EmployeeData`, so there is only one employee with ID 1001.

In the member function documentation, d pointer always refers to the internal pointer to the shared data object.

### Optimize Performance for Usage in Qt Containers

You should consider marking your implicitly shared class as a movable type using the Q_DECLARE_TYPEINFO() macro if it resembles the `Employee` class above and uses a QSharedDataPointer or QExplicitlySharedDataPointer as the only member. This can improve performance and memory efficiency when using Qt's container classes.

See also QSharedData, QExplicitlySharedDataPointer, QScopedPointer, and QSharedPointer.

## Member Type Documentation

### QSharedDataPointer::Type

This is the type of the shared data object. The d pointer points to an object of this type.

## Member Function Documentation

### `[since 5.2]` QSharedDataPointer::QSharedDataPointer(QSharedDataPointer<T> &&o)

Move-constructs a QSharedDataPointer instance, making it point at the same object that o was pointing to.

This function was introduced in Qt 5.2.

### QSharedDataPointer::QSharedDataPointer(const QSharedDataPointer<T> &o)

Sets the d pointer of this to the d pointer in o and increments the reference count of the shared data object.

### `[since 6.0]` QSharedDataPointer::QSharedDataPointer(T *data, QAdoptSharedDataTag)

Constructs a QSharedDataPointer with d pointer set to data. data's reference counter is not incremented; this can be used to adopt pointers obtained from take().

This function was introduced in Qt 6.0.

See also take().

### QSharedDataPointer::QSharedDataPointer(T *data)

Constructs a QSharedDataPointer with d pointer set to data and increments data's reference count.

### QSharedDataPointer::QSharedDataPointer()

Constructs a QSharedDataPointer initialized with `nullptr` as d pointer.

### `[since 5.2]` QSharedDataPointer<T> &QSharedDataPointer::operator=(QSharedDataPointer<T> &&other)

Move-assigns other to this QSharedDataPointer instance.

This function was introduced in Qt 5.2.

### QSharedDataPointer<T> &QSharedDataPointer::operator=(const QSharedDataPointer<T> &o)

Sets the d pointer of this to the d pointer of o and increments the reference count of the shared data object. The reference count of the old shared data object of this is decremented. If the reference count of the old shared data object becomes 0, the old shared data object is deleted.

### QSharedDataPointer::~QSharedDataPointer()

Decrements the reference count of the shared data object. If the reference count becomes 0, the shared data object is deleted. This is then destroyed.

### `[protected]` T *QSharedDataPointer::clone()

Creates and returns a deep copy of the current data. This function is called by detach() when the reference count is greater than 1 in order to create the new copy. This function uses the operator new and calls the copy constructor of the type T.

This function is provided so that you may support "virtual copy constructors" for your own types. In order to so, you should declare a template-specialization of this function for your own type, like the example below:

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

In the example above, the template specialization for the clone() function calls the EmployeeData::clone() virtual function. A class derived from EmployeeData could override that function and return the proper polymorphic type.

### const T *QSharedDataPointer::constData() const

Returns a const pointer to the shared data object. This function does not call detach().

See also data().

### T *QSharedDataPointer::data()

Returns a pointer to the shared data object. This function calls detach().

See also constData().

### const T *QSharedDataPointer::data() const

Returns a pointer to the shared data object. This function does not call detach().

### void QSharedDataPointer::detach()

If the shared data object's reference count is greater than 1, this function creates a deep copy of the shared data object and sets the d pointer of this to the copy.

This function is called automatically by non-const member functions of QSharedDataPointer if copy on write is required. You don't need to call it yourself.

### `[since 6.0]` T *QSharedDataPointer::get()

Same as data(). This function is provided for STL compatibility.

This function was introduced in Qt 6.0.

### `[since 6.0]` const T *QSharedDataPointer::get() const

Same as data(). This function is provided for STL compatibility.

This function was introduced in Qt 6.0.

### `[since 6.0]` void QSharedDataPointer::reset(T *ptr = nullptr)

Sets the d pointer of this to ptr and increments ptr's reference count if ptr is not `nullptr`. The reference count of the old shared data object is decremented, and the object deleted if the reference count reaches 0.

This function was introduced in Qt 6.0.

### void QSharedDataPointer::swap(QSharedDataPointer<T> &other)

Swap this instance's shared data pointer with the shared data pointer in other.

### `[since 6.0]` T *QSharedDataPointer::take()

Returns a pointer to the shared object, and resets this to be `nullptr`. (That is, this function sets the d pointer of this to `nullptr`.)

Note: The reference count of the returned object will not be decremented. This function can be used together with the constructor that takes a QAdoptSharedDataTag tag object to transfer the shared data object without intervening atomic operations.

This function was introduced in Qt 6.0.

### T *QSharedDataPointer::operator T *()

Returns a pointer to the shared data object. This function calls detach().

See also data() and constData().

### const T *QSharedDataPointer::operator const T *() const

Returns a pointer to the shared data object. This function does not call detach().

### bool QSharedDataPointer::operator!() const

Returns `true` if the d pointer of this is `nullptr`.

### T &QSharedDataPointer::operator*()

Provides access to the shared data object's members. This function calls detach().

### const T &QSharedDataPointer::operator*() const

Provides const access to the shared data object's members. This function does not call detach().

### T *QSharedDataPointer::operator->()

Provides access to the shared data object's members. This function calls detach().

### const T *QSharedDataPointer::operator->() const

Provides const access to the shared data object's members. This function does not call detach().

### QSharedDataPointer<T> &QSharedDataPointer::operator=(T *o)

Sets the d pointer og this to o and increments o's reference count. The reference count of the old shared data object of this is decremented. If the reference count of the old shared data object becomes 0, the old shared data object is deleted.

## Related Non-Members

### bool operator!=(const QSharedDataPointer<T> &lhs, const QSharedDataPointer<T> &rhs)

Returns `true` if lhs and rhs do not have the same d pointer. This function does not call detach().

### bool operator!=(const T *ptr, const QSharedDataPointer<T> &rhs)

Returns `true` if the d pointer of rhs is not ptr. d pointer. This function does not call detach().

### bool operator==(const QSharedDataPointer<T> &lhs, const QSharedDataPointer<T> &rhs)

Returns `true` if lhs and rhs have the same d pointer. This function does not call detach().

### bool operator==(const T *ptr, const QSharedDataPointer<T> &rhs)

Returns `true` if the d pointer of rhs is ptr. This function does not call detach().