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

QExplicitlySharedDataPointer Class Reference
[
QtCore module]

The QExplicitlySharedDataPointer class provides a pointer to a shared, non-copied data object. More...

 #include <QExplicitlySharedDataPointer>

Note: All the functions in this class are reentrant.

Public Types

Public Functions


Detailed Description

The QExplicitlySharedDataPointer class provides a pointer to a shared, non-copied data object.

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

Explicit 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.

Compared to QSharedDataPointer, QExplicitlySharedDataPointer never detaches the data object when a mutating function is called. Therefore pointers always use the same object regardless of if the object's data is modified. In that way QExplicitlySharedDataPointer acts like a regular C++ pointer, with the exception that it automatically handles ownership.

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

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

 /****************************************************************************
 **
 ** Copyright (C) 2004-2008 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 versions 2.0 or 3.0 as published by the Free Software
** Foundation and appearing in the files LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file.  Alternatively you may (at
** your option) use any later version of the GNU General Public
** License if such license has been publicly approved by Trolltech ASA
** (or its successors, if any) and the KDE Free Qt Foundation. In
** addition, as a special exception, Trolltech gives you certain
** additional rights. These rights are described in the Trolltech GPL
** Exception version 1.2, which can be found at
** http://www.trolltech.com/products/qt/gplexception/ and in the file
** GPL_EXCEPTION.txt in this package.
**
** 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, 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.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. 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:
     QExplicitlySharedDataPointer<EmployeeData> d;
 };

 #endif

All accesses to the data in the setter and getter functions are made through the QExplicitlySharedDataPointer object d.

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, QExplicitlySharedDataPointer 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;
 }

Notice that there is no need to implement a copy constructor or assignment operator in the Employee class. This is because they will never be called, since QExplicitlySharedDataPointer never copies the object pointed to.

See also QSharedData.


Member Type Documentation

typedef QExplicitlySharedDataPointer::Type


Member Function Documentation

QExplicitlySharedDataPointer::QExplicitlySharedDataPointer ()

Constructs a QExplicitlySharedDataPointer initialized with a null pointer.

QExplicitlySharedDataPointer::QExplicitlySharedDataPointer ( T * sharedData )

Constructs a QExplicitlySharedDataPointer that points to sharedData.

This function automatically increments sharedData's reference count.

QExplicitlySharedDataPointer::QExplicitlySharedDataPointer ( const QExplicitlySharedDataPointer<T> & other )

Constructs a copy of other.

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

QExplicitlySharedDataPointer::QExplicitlySharedDataPointer ( const QExplicitlySharedDataPointer<X> & o )

QExplicitlySharedDataPointer::~QExplicitlySharedDataPointer ()

Destroys the QExplicitlySharedDataPointer.

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

const T * QExplicitlySharedDataPointer::constData () const

Returns a const pointer to the shared object.

See also data().

T * QExplicitlySharedDataPointer::data () const

void QExplicitlySharedDataPointer::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 QExplicitlySharedDataPointer when necessary. You should never need to call it yourself.

void QExplicitlySharedDataPointer::reset ()

QExplicitlySharedDataPointer::operator bool () const

bool QExplicitlySharedDataPointer::operator! () const

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

bool QExplicitlySharedDataPointer::operator!= ( const QExplicitlySharedDataPointer<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.

bool QExplicitlySharedDataPointer::operator!= ( const T * ptr ) const

This is an overloaded member function, provided for convenience.

T & QExplicitlySharedDataPointer::operator* ()

Provides access to the shared object's members.

const T & QExplicitlySharedDataPointer::operator* () const

This is an overloaded member function, provided for convenience.

T * QExplicitlySharedDataPointer::operator-> ()

Provides access to the shared object's members.

T * QExplicitlySharedDataPointer::operator-> () const

This is an overloaded member function, provided for convenience.

QExplicitlySharedDataPointer<T> & QExplicitlySharedDataPointer::operator= ( const QExplicitlySharedDataPointer<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 QExplicitlySharedDataPointer. If the reference count reaches 0, the shared data object is deleted.

QExplicitlySharedDataPointer & QExplicitlySharedDataPointer::operator= ( T * sharedData )

This is an overloaded member function, provided for convenience.

Sets this QExplicitlySharedDataPointer 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 QExplicitlySharedDataPointer. If the reference count reaches 0, the shared data object is deleted.

bool QExplicitlySharedDataPointer::operator== ( const QExplicitlySharedDataPointer<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.

bool QExplicitlySharedDataPointer::operator== ( const T * ptr ) const

This is an overloaded member function, provided for convenience.


Copyright © 2008 Trolltech Trademarks
Qt 4.4.0-beta1