|  | Home · All Classes · Main Classes · Grouped Classes · Modules · Functions |

# QSharedDataPointer Class Reference
[QtCore module]

The QSharedDataPointer class provides a pointer to a shared data object. More...

     #include <QSharedDataPointer>

Note: All the functions in this class are reentrant.

- List of all members, including inherited members

### Public Functions

- QSharedDataPointer ()
- QSharedDataPointer ( T * sharedData )
- QSharedDataPointer ( const QSharedDataPointer<T> & other )
- ~QSharedDataPointer ()
- const T * constData () const
- T * data ()
- const T * data () const
- void detach ()
- operator T * ()
- operator const T * () const
- bool operator! () const
- bool operator!= ( const QSharedDataPointer<T> & other ) const
- T & operator* ()
- const T & operator* () const
- T * operator-> ()
- const T * operator-> () const
- QSharedDataPointer<T> & operator= ( const QSharedDataPointer<T> & other )
- QSharedDataPointer & operator= ( T * sharedData )
- bool operator== ( const QSharedDataPointer<T> & other ) const

## Detailed Description

The QSharedDataPointer class provides a pointer to a shared data object.

QSharedDataPointer<T> makes it easier to write your own implicitly shared classes. It handles reference counting behind the scenes in a thread-safe manner, ensuring that classes that use it can be reentrant.

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

Let's suppose that you want to make an `Employee` class implicitly shared. The procedure is:

- Define the `Employee` class with a single data member variable of type QSharedDataPointer<`EmployeeData`>.
- Define an `EmployeeData` class that derives from QSharedData and that contains all the variables that you would normally put in `Employee`.

To show how this works in practice, we will review the entire source code for an implicitly shared `Employee` class. Here's the header file that defines the `Employee` class:

     /****************************************************************************
     **
     ** Copyright (C) 2004-2007 Trolltech ASA. All rights reserved.
     **
     ** This file is part of the documentation of the Qt Toolkit.
     **
     ** This file may be used under the terms of the GNU General Public
     ** License version 2.0 as published by the Free Software Foundation
     ** and appearing in the file LICENSE.GPL included in the packaging of
     ** this file.  Please review the following information to ensure GNU
     ** General Public Licensing requirements will be met:
     ** http://trolltech.com/products/qt/licenses/licensing/opensource/
     **
     ** If you are unsure which license is appropriate for your use, please
     ** review the following information:
     ** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
     ** or contact the sales department at sales@trolltech.com.
     **
     ** In addition, as a special exception, Trolltech gives you certain
     ** additional rights. These rights are described in the Trolltech GPL
     ** Exception version 1.0, which can be found at
     ** http://www.trolltech.com/products/qt/gplexception/ and in the file
     ** GPL_EXCEPTION.txt in this package.
     **
     ** In addition, as a special exception, Trolltech, as the sole copyright
     ** holder for Qt Designer, grants users of the Qt/Eclipse Integration
     ** plug-in the right for the Qt/Eclipse Integration to link to
     ** functionality provided by Qt Designer and its related libraries.
     **
     ** Trolltech reserves all rights not expressly granted herein.
     **
     ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
     ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
     **
     ****************************************************************************/

     #ifndef EMPLOYEE_H
     #define EMPLOYEE_H

     #include <QSharedData>
     #include <QString>

     class EmployeeData : public QSharedData
     {
     public:
         EmployeeData();
         EmployeeData(const EmployeeData &other);
         ~EmployeeData();

         int id;
         QString *name;
     };

     class Employee
     {
     public:
         Employee();
         Employee(int id, const QString &name);

         void setId(int id) { d->id = id; }
         void setName(const QString &name);

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

     private:
         QSharedDataPointer<EmployeeData> d;
     };

     #endif

All accesses to the data in the setter and getter functions are made through the QSharedDataPointer object `d`. For non-const functions, operator->() automatically calls detach(), ensuring that modifications to one `Employee` object don't affect other `Employee` objects.

The `EmployeeData` type is a simple class that inherits QSharedData and that provides a default constructor, a copy constructor, and a destructor. Normally, this is all you need in the "data" class.

Here's the implementation of the `EmployeeData` members:

     EmployeeData::EmployeeData()
     {
         id = -1;
         name = 0;
     }

     EmployeeData::EmployeeData(const EmployeeData &other)
         : QSharedData(other)
     {
         id = other.id;
         if (other.name) {
             name = new QString(*other.name);
         } else {
             name = 0;
         }
     }

     EmployeeData::~EmployeeData()
     {
         delete name;
     }

Let's now see how to implement the `Employee` constructors:

     Employee::Employee()
     {
         d = new EmployeeData;
     }

In the default constructor, we create an object of type `EmployeeData` and assign it to the `d` pointer using operator=().

Behind the scenes, QSharedDataPointer automatically increments or decrements the reference count of the shared data object pointed to by `d`, and deletes shared objects when the reference count reaches 0.

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

In the constructor that takes an ID and an employee's name, we also create an object of type `EmployeeData` and assign it to the `d` pointer.

     void Employee::setName(const QString &name)
     {
         if (!d->name)
             d->name = new QString;
         *d->name = name;
     }

When we use the `d` pointer from a non-const function, detach() is automatically called to ensure that we work on our own copy of the data.

     QString Employee::name() const
     {
         if (!d->name)
             return QString();
         return *d->name;
     }

When we use the `d` pointer in a const function, detach() is not called.

Notice that there is no need to implement a copy constructor or assignment operator in the `Employee` class. This is because the C++ compiler provides default implementations that simply perform member-by-member copy. Here, the only member is `d`, and its operator=() simply increments a reference count (which is precisely what we want).

See also QSharedData.

## Member Function Documentation

### QSharedDataPointer::QSharedDataPointer ()

Constructs a QSharedDataPointer initialized with a null pointer.

### QSharedDataPointer::QSharedDataPointer ( T * sharedData )

Constructs a QSharedDataPointer that points to sharedData.

This function automatically increments sharedData's reference count.

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

Constructs a copy of other.

This function automatically increments the reference count of the shared data object pointed to by other.

### QSharedDataPointer::~QSharedDataPointer ()

Destroys the QSharedDataPointer.

This function automatically decrements the reference count of the shared object and deletes the object if the reference count reaches 0.

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

Returns a const pointer to the shared object.

This function does not call detach().

See also data().

### T * QSharedDataPointer::data ()

Returns a pointer to the shared object.

This function does a detach().

See also constData().

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

This is an overloaded member function, provided for convenience.

This function does not call detach().

### void QSharedDataPointer::detach ()

If the shared data's reference count is greater than 1, creates a deep copy of the shared data.

This function is automatically called by QSharedDataPointer when necessary. You should never need to call it yourself.

### QSharedDataPointer::operator T * ()

Returns a pointer to the shared object.

This function does a detach().

See also data() and constData().

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

Returns a pointer to the shared object.

This function does not call detach().

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

Returns true if this pointer is null; otherwise returns false.

### bool QSharedDataPointer::operator!= ( const QSharedDataPointer<T> & other ) const

Returns a true if the pointer to the shared object in other is not equal to to the pointer to the shared data in this else returns false.

This function does not call detach().

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

Provides access to the shared object's members.

This function does a detach().

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

This is an overloaded member function, provided for convenience.

This function does not call detach().

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

Provides access to the shared object's members.

This function does a detach().

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

This is an overloaded member function, provided for convenience.

This function does not call detach().

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

Assigns other to this pointer.

This function automatically increments the reference count of the shared data object pointed to by other, and decrements the reference count of the object previously pointed to by this QSharedDataPointer. If the reference count reaches 0, the shared data object is deleted.

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

This is an overloaded member function, provided for convenience.

Sets this QSharedDataPointer to point to sharedData.

This function automatically increments sharedData's reference count, and decrements the reference count of the object previously pointed to by this QSharedDataPointer. If the reference count reaches 0, the shared data object is deleted.

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

Returns a true if the pointer to the shared object in other is equal to to the pointer to the shared data in this else returns false.

This function does not call detach().