Qt 4.8
Public Types | Public Functions | Protected Functions | Private Functions | Properties | List of all members
QSharedDataPointer< T > Class Template Reference

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

#include <qshareddata.h>

Public Types

typedef T * pointer
 
typedef T Type
 This is the type of the shared data object. More...
 

Public Functions

const T * constData () const
 Returns a const pointer to the shared data object. More...
 
T * data ()
 Returns a pointer to the shared data object. More...
 
const T * data () const
 Returns a pointer to the shared data object. More...
 
void 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. More...
 
 operator const T * () const
 Returns a pointer to the shared data object. More...
 
 operator T* ()
 Returns a pointer to the shared data object. More...
 
bool operator! () const
 Returns true if the d pointer of this is null. More...
 
bool operator!= (const QSharedDataPointer< T > &other) const
 Returns true if other and this do not have the same d pointer. More...
 
T & operator* ()
 Provides access to the shared data object's members. More...
 
const T & operator* () const
 Provides const access to the shared data object's members. More...
 
T * operator-> ()
 Provides access to the shared data object's members. More...
 
const T * operator-> () const
 Provides const access to the shared data object's members. More...
 
QSharedDataPointer< T > & operator= (const QSharedDataPointer< T > &o)
 Sets the d pointer of this to the d pointer of other and increments the reference count of the shared data object. More...
 
QSharedDataPointeroperator= (T *o)
 Sets the d pointer og this to sharedData and increments {sharedData}'s reference count. More...
 
bool operator== (const QSharedDataPointer< T > &other) const
 Returns true if other and this have the same d pointer. More...
 
 QSharedDataPointer ()
 Constructs a QSharedDataPointer initialized with a null d pointer. More...
 
 QSharedDataPointer (T *data)
 Constructs a QSharedDataPointer with d pointer set to sharedData and increments {sharedData}'s reference count. More...
 
 QSharedDataPointer (const QSharedDataPointer< T > &o)
 Sets the d pointer of this to the d pointer in other and increments the reference count of the shared data object. More...
 
void swap (QSharedDataPointer &other)
 Swap this instance's shared data pointer with the shared data pointer in other. More...
 
 ~QSharedDataPointer ()
 Decrements the reference count of the shared data object. More...
 

Protected Functions

T * clone ()
 

Private Functions

void detach_helper ()
 

Properties

T * d
 

Detailed Description

template<class T>
class QSharedDataPointer< T >

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

Since
4.0
Note
This class or function is reentrant.

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:

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;
};
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:
};

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.

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 QExplicitlySharedDataPointer {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.

See also
QSharedData, QExplicitlySharedDataPointer, QScopedPointer, QSharedPointer

Definition at line 54 of file qshareddata.h.

Typedefs

◆ pointer

template<class T>
QSharedDataPointer< T >::pointer
Warning
This function is not part of the public interface.

Definition at line 73 of file qshareddata.h.

◆ Type

template<class T>
QSharedDataPointer< T >::Type

This is the type of the shared data object.

The d pointer points to an object of this type.

Definition at line 72 of file qshareddata.h.

Constructors and Destructors

◆ QSharedDataPointer() [1/3]

template<class T>
QSharedDataPointer< T >::QSharedDataPointer ( )
inline

◆ ~QSharedDataPointer()

template<class T>
QSharedDataPointer< T >::~QSharedDataPointer ( )
inline

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.

Definition at line 90 of file qshareddata.h.

90 { if (d && !d->ref.deref()) delete d; }

◆ QSharedDataPointer() [2/3]

template<class T>
Q_INLINE_TEMPLATE QSharedDataPointer< T >::QSharedDataPointer ( T *  data)
explicit

Constructs a QSharedDataPointer with d pointer set to sharedData and increments {sharedData}'s reference count.

Definition at line 221 of file qshareddata.h.

221  : d(adata)
222 { if (d) d->ref.ref(); }

◆ QSharedDataPointer() [3/3]

template<class T>
QSharedDataPointer< T >::QSharedDataPointer ( const QSharedDataPointer< T > &  o)
inline

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

Definition at line 93 of file qshareddata.h.

93 : d(o.d) { if (d) d->ref.ref(); }

Functions

◆ clone()

template<class T >
Q_INLINE_TEMPLATE T * QSharedDataPointer< T >::clone ( )
protected
Since
4.5

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

Definition at line 225 of file qshareddata.h.

Referenced by QSharedDataPointer< QSslConfigurationPrivate >::detach_helper(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::detach_helper(), QSharedDataPointer< QSslConfigurationPrivate >::swap(), and QExplicitlySharedDataPointer< QSslConfigurationPrivate >::swap().

226 {
227  return new T(*d);
228 }

◆ constData()

template<class T>
const T * QSharedDataPointer< T >::constData ( ) const
inline

◆ data() [1/2]

template<class T>
T * QSharedDataPointer< T >::data ( )
inline

Returns a pointer to the shared data object.

This function calls detach().

See also
constData()

Definition at line 82 of file qshareddata.h.

Referenced by QVolatileImage::constImageRef(), QDir::nameFiltersFromString(), QDir::refresh(), QDir::setFilter(), QDir::setNameFilters(), QDir::setSorting(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::~QExplicitlySharedDataPointer(), and QSharedDataPointer< QSslConfigurationPrivate >::~QSharedDataPointer().

82 { detach(); return d; }
void detach()
If the shared data object&#39;s reference count is greater than 1, this function creates a deep copy of t...
Definition: qshareddata.h:75

◆ data() [2/2]

template<class T>
const T * QSharedDataPointer< T >::data ( ) const
inline

Returns a pointer to the shared data object.

This function does not call detach().

Definition at line 83 of file qshareddata.h.

83 { return d; }

◆ detach()

template<class T>
void QSharedDataPointer< T >::detach ( )
inline

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.

Definition at line 75 of file qshareddata.h.

Referenced by QSharedDataPointer< QSslConfigurationPrivate >::data(), QFileInfo::detach(), QProcessEnvironment::insert(), QSharedDataPointer< T >::operator T*(), QSharedDataPointer< QSslConfigurationPrivate >::operator*(), QSharedDataPointer< QSslConfigurationPrivate >::operator->(), QNetworkProxyPrivate::operator==(), QProcessEnvironment::remove(), QUnixSocketMessage::setBytes(), and QUnixSocketMessage::setRights().

75 { if (d && d->ref != 1) detach_helper(); }

◆ detach_helper()

template<class T >
Q_OUTOFLINE_TEMPLATE void QSharedDataPointer< T >::detach_helper ( )
private

◆ operator const T *()

template<class T>
QSharedDataPointer< T >::operator const T * ( ) const
inline

Returns a pointer to the shared data object.

This function does not call detach().

Definition at line 81 of file qshareddata.h.

81 { return d; }

◆ operator T*()

template<class T>
QSharedDataPointer< T >::operator T* ( )
inline

Returns a pointer to the shared data object.

This function calls detach().

See also
data(), constData()

Definition at line 80 of file qshareddata.h.

80 { detach(); return d; }
void detach()
If the shared data object&#39;s reference count is greater than 1, this function creates a deep copy of t...
Definition: qshareddata.h:75

◆ operator!()

template<class T>
bool QSharedDataPointer< T >::operator! ( ) const
inline

Returns true if the d pointer of this is null.

Definition at line 122 of file qshareddata.h.

122 { return !d; }

◆ operator!=()

template<class T>
bool QSharedDataPointer< T >::operator!= ( const QSharedDataPointer< T > &  other) const
inline

Returns true if other and this do not have the same d pointer.

This function does not call detach().

Definition at line 87 of file qshareddata.h.

87 { return d != other.d; }

◆ operator*() [1/2]

template<class T>
T & QSharedDataPointer< T >::operator* ( )
inline

Provides access to the shared data object's members.

This function calls detach().

Definition at line 76 of file qshareddata.h.

76 { detach(); return *d; }
void detach()
If the shared data object&#39;s reference count is greater than 1, this function creates a deep copy of t...
Definition: qshareddata.h:75

◆ operator*() [2/2]

template<class T>
const T & QSharedDataPointer< T >::operator* ( ) const
inline

Provides const access to the shared data object's members.

This function does not call detach().

Definition at line 77 of file qshareddata.h.

77 { return *d; }

◆ operator->() [1/2]

template<class T>
T * QSharedDataPointer< T >::operator-> ( )
inline

Provides access to the shared data object's members.

This function calls detach().

Definition at line 78 of file qshareddata.h.

78 { detach(); return d; }
void detach()
If the shared data object&#39;s reference count is greater than 1, this function creates a deep copy of t...
Definition: qshareddata.h:75

◆ operator->() [2/2]

template<class T>
const T * QSharedDataPointer< T >::operator-> ( ) const
inline

Provides const access to the shared data object's members.

This function does not call detach().

Definition at line 79 of file qshareddata.h.

79 { return d; }

◆ operator=() [1/2]

template<class T>
QSharedDataPointer< T > & QSharedDataPointer< T >::operator= ( const QSharedDataPointer< T > &  other)
inline

Sets the d pointer of this to the d pointer of other 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.

Definition at line 94 of file qshareddata.h.

Referenced by QSharedDataPointer< QSslConfigurationPrivate >::operator=(), and QExplicitlySharedDataPointer< QSslConfigurationPrivate >::operator=().

94  {
95  if (o.d != d) {
96  if (o.d)
97  o.d->ref.ref();
98  T *old = d;
99  d = o.d;
100  if (old && !old->ref.deref())
101  delete old;
102  }
103  return *this;
104  }

◆ operator=() [2/2]

template<class T>
QSharedDataPointer & QSharedDataPointer< T >::operator= ( T *  sharedData)
inline

Sets the d pointer og this to sharedData and increments {sharedData}'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.

Definition at line 105 of file qshareddata.h.

105  {
106  if (o != d) {
107  if (o)
108  o->ref.ref();
109  T *old = d;
110  d = o;
111  if (old && !old->ref.deref())
112  delete old;
113  }
114  return *this;
115  }

◆ operator==()

template<class T>
bool QSharedDataPointer< T >::operator== ( const QSharedDataPointer< T > &  other) const
inline

Returns true if other and this have the same d pointer.

This function does not call detach().

Definition at line 86 of file qshareddata.h.

86 { return d == other.d; }

◆ swap()

template<class T>
void QSharedDataPointer< T >::swap ( QSharedDataPointer< T > &  other)
inline

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

Definition at line 124 of file qshareddata.h.

Referenced by qSwap().

125  { qSwap(d, other.d); }
Q_INLINE_TEMPLATE void qSwap(QSharedDataPointer< T > &p1, QSharedDataPointer< T > &p2)
Definition: qshareddata.h:261

Properties

◆ d

template<class T>
T* QSharedDataPointer< T >::d
private

Definition at line 133 of file qshareddata.h.

Referenced by QSharedDataPointer< QSslConfigurationPrivate >::clone(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::clone(), QSharedDataPointer< QSslConfigurationPrivate >::constData(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::constData(), QSharedDataPointer< QSslConfigurationPrivate >::data(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::data(), QSharedDataPointer< QSslConfigurationPrivate >::detach(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::detach(), QSharedDataPointer< QSslConfigurationPrivate >::detach_helper(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::detach_helper(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::operator bool(), QSharedDataPointer< T >::operator const T *(), QSharedDataPointer< T >::operator T*(), QSharedDataPointer< QSslConfigurationPrivate >::operator!(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::operator!(), QSharedDataPointer< QSslConfigurationPrivate >::operator!=(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::operator!=(), QSharedDataPointer< QSslConfigurationPrivate >::operator*(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::operator*(), QSharedDataPointer< QSslConfigurationPrivate >::operator->(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::operator->(), QSharedDataPointer< QSslConfigurationPrivate >::operator=(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::operator=(), QSharedDataPointer< QSslConfigurationPrivate >::operator==(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::operator==(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::QExplicitlySharedDataPointer(), QSharedDataPointer< QSslConfigurationPrivate >::QSharedDataPointer(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::reset(), QSharedDataPointer< QSslConfigurationPrivate >::swap(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::swap(), QExplicitlySharedDataPointer< QSslConfigurationPrivate >::~QExplicitlySharedDataPointer(), and QSharedDataPointer< QSslConfigurationPrivate >::~QSharedDataPointer().


The documentation for this class was generated from the following files: