Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
QSharedDataPointer< T > Class Template Reference

\inmodule QtCore More...

#include <qshareddata.h>

+ Collaboration diagram for QSharedDataPointer< T >:

Public Types

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

Public Member Functions

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.
 
T & operator* ()
 Provides access to the shared data object's members.
 
const T & operator* () const
 Provides const access to the shared data object's members.
 
T * operator-> ()
 Provides access to the shared data object's members.
 
const T * operator-> () const noexcept
 Provides const access to the shared data object's members.
 
 operator T* ()
 Returns a pointer to the shared data object.
 
 operator const T * () const noexcept
 Returns a pointer to the shared data object.
 
T * data ()
 Returns a pointer to the shared data object.
 
T * get ()
 
const T * data () const noexcept
 Returns a pointer to the shared data object.
 
const T * get () const noexcept
 
const T * constData () const noexcept
 Returns a const pointer to the shared data object.
 
T * take () noexcept
 
Q_NODISCARD_CTOR QSharedDataPointer () noexcept
 Constructs a QSharedDataPointer initialized with \nullptr as {d pointer}.
 
 ~QSharedDataPointer ()
 Decrements the reference count of the shared data object.
 
Q_NODISCARD_CTOR QSharedDataPointer (T *data) noexcept
 Constructs a QSharedDataPointer with {d pointer} set to data and increments {data}'s reference count.
 
Q_NODISCARD_CTOR QSharedDataPointer (T *data, QAdoptSharedDataTag) noexcept
 
Q_NODISCARD_CTOR QSharedDataPointer (const QSharedDataPointer &o) noexcept
 Sets the {d pointer} of this to the {d pointer} in o and increments the reference count of the shared data object.
 
void reset (T *ptr=nullptr) noexcept
 
QSharedDataPointeroperator= (const QSharedDataPointer &o) noexcept
 Sets the {d pointer} of this to the {d pointer} of o and increments the reference count of the shared data object.
 
QSharedDataPointeroperator= (T *o) noexcept
 Sets the {d pointer} og this to o and increments {o}'s reference count.
 
Q_NODISCARD_CTOR QSharedDataPointer (QSharedDataPointer &&o) noexcept
 Move-constructs a QSharedDataPointer instance, making it point at the same object that o was pointing to.
 
 operator bool () const noexcept
 
bool operator! () const noexcept
 Returns true if the {d pointer} of this is \nullptr.
 
void swap (QSharedDataPointer &other) noexcept
 \memberswap{shared data pointer}
 
Q_INLINE_TEMPLATE void detach ()
 
void detach ()
 
void detach ()
 
void detach ()
 
void detach ()
 
void detach ()
 
void detach ()
 

Protected Member Functions

T * clone ()
 
EmployeeDataclone ()
 [0]
 
QUrlQueryPrivateclone ()
 
QLocalePrivateclone ()
 
QTimeZonePrivateclone ()
 
QTimeZonePrivateclone ()
 
QT_BEGIN_NAMESPACE QPlacePrivateclone ()
 
QT_USE_NAMESPACE QPlaceSearchResultPrivateclone ()
 
QPlaceSearchResultPrivateclone ()
 
Q_INLINE_TEMPLATE QGeoShapePrivateclone ()
 
EmployeeDataclone ()
 [0]
 
QUrlQueryPrivateclone ()
 
QTimeZonePrivateclone ()
 
QT_BEGIN_NAMESPACE QPlacePrivateclone ()
 
QT_USE_NAMESPACE QPlaceSearchResultPrivateclone ()
 

Friends

bool comparesEqual (const QSharedDataPointer &lhs, const QSharedDataPointer &rhs) noexcept
 
Qt::strong_ordering compareThreeWay (const QSharedDataPointer &lhs, const QSharedDataPointer &rhs) noexcept
 
bool comparesEqual (const QSharedDataPointer &lhs, const T *rhs) noexcept
 
Qt::strong_ordering compareThreeWay (const QSharedDataPointer &lhs, const T *rhs) noexcept
 
bool comparesEqual (const QSharedDataPointer &lhs, std::nullptr_t) noexcept
 
Qt::strong_ordering compareThreeWay (const QSharedDataPointer &lhs, std::nullptr_t) noexcept
 

Detailed Description

template<typename T>
class QSharedDataPointer< T >

\inmodule QtCore

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

Since
4.0 \reentrant

\compares strong \compareswith strong T* std::nullptr_t \endcompareswith

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

\l {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 \l{Shared Classes} page for more information.

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

\list

\endlist

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) { }
int id;
QString name;
};
class Employee
{
public:
Employee() { d = new EmployeeData; }
Employee(int id, const QString &name) {
d = new EmployeeData;
setId(id);
}
: 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; }

\codeline

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

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

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

\codeline

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

\codeline

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.

\target Implicit vs Explicit Sharing

Definition at line 34 of file qshareddata.h.

Member Typedef Documentation

◆ pointer

template<typename T>
typedef T* QSharedDataPointer< T >::pointer

Definition at line 38 of file qshareddata.h.

◆ Type

template<typename T>
typedef 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 37 of file qshareddata.h.

Constructor & Destructor Documentation

◆ QSharedDataPointer() [1/5]

◆ ~QSharedDataPointer()

template<typename 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 56 of file qshareddata.h.

◆ QSharedDataPointer() [2/5]

template<typename T>
Q_NODISCARD_CTOR QSharedDataPointer< T >::QSharedDataPointer ( T * data)
inlineexplicitnoexcept

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

Definition at line 59 of file qshareddata.h.

◆ QSharedDataPointer() [3/5]

template<typename T>
Q_NODISCARD_CTOR QSharedDataPointer< T >::QSharedDataPointer ( T * data,
QAdoptSharedDataTag  )
inlinenoexcept
Since
6.0 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().
See also
take()

Definition at line 62 of file qshareddata.h.

◆ QSharedDataPointer() [4/5]

template<typename T>
Q_NODISCARD_CTOR QSharedDataPointer< T >::QSharedDataPointer ( const QSharedDataPointer< T > & o)
inlinenoexcept

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

Definition at line 65 of file qshareddata.h.

◆ QSharedDataPointer() [5/5]

template<typename T>
Q_NODISCARD_CTOR QSharedDataPointer< T >::QSharedDataPointer ( QSharedDataPointer< T > && o)
inlinenoexcept

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

Since
5.2

Definition at line 90 of file qshareddata.h.

Member Function Documentation

◆ clone() [1/15]

EmployeeData * QSharedDataPointer< EmployeeData >::clone ( )
protected

[0]

[1]

Definition at line 10 of file src_corelib_tools_qshareddata.cpp.

◆ clone() [2/15]

EmployeeData * QSharedDataPointer< EmployeeData >::clone ( )
protected

[0]

[1]

Definition at line 10 of file src_corelib_tools_qshareddata.cpp.

◆ clone() [3/15]

QUrlQueryPrivate * QSharedDataPointer< QUrlQueryPrivate >::clone ( )
inlineprotected

Definition at line 315 of file qurlquery.cpp.

◆ clone() [4/15]

QUrlQueryPrivate * QSharedDataPointer< QUrlQueryPrivate >::clone ( )
inlineprotected

Definition at line 315 of file qurlquery.cpp.

◆ clone() [5/15]

QLocalePrivate * QSharedDataPointer< QLocalePrivate >::clone ( )
inlineprotected

Definition at line 572 of file qlocale_p.h.

◆ clone() [6/15]

Definition at line 893 of file qtimezoneprivate.cpp.

◆ clone() [7/15]

Definition at line 893 of file qtimezoneprivate.cpp.

◆ clone() [8/15]

◆ clone() [9/15]

template<typename 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 236 of file qshareddata.h.

◆ clone() [10/15]

Definition at line 18 of file qplace.cpp.

◆ clone() [11/15]

Definition at line 18 of file qplace.cpp.

◆ clone() [12/15]

◆ clone() [13/15]

◆ clone() [14/15]

◆ clone() [15/15]

Q_INLINE_TEMPLATE QGeoShapePrivate * QSharedDataPointer< QGeoShapePrivate >::clone ( )
protected

Definition at line 51 of file qgeoshape_p.h.

◆ constData()

template<typename T>
const T * QSharedDataPointer< T >::constData ( ) const
inlinenoexcept

Returns a const pointer to the shared data object.

This function does not call detach().

See also
data()

Definition at line 51 of file qshareddata.h.

◆ data() [1/2]

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

Returns a pointer to the shared data object.

This function calls detach().

See also
constData()

Definition at line 47 of file qshareddata.h.

◆ data() [2/2]

template<typename T>
const T * QSharedDataPointer< T >::data ( ) const
inlinenoexcept

Returns a pointer to the shared data object.

This function does not call detach().

Definition at line 49 of file qshareddata.h.

◆ detach() [1/8]

Q_INLINE_TEMPLATE void QSharedDataPointer< QProcessEnvironmentPrivate >::detach ( )

Definition at line 177 of file qprocess_p.h.

◆ detach() [2/8]

Definition at line 169 of file qurlquery.cpp.

◆ detach() [3/8]

Definition at line 169 of file qurlquery.cpp.

◆ detach() [4/8]

template<typename 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 40 of file qshareddata.h.

Referenced by QSharedDataPointer< QUrlQueryPrivate >::data(), QSharedDataPointer< QUrlQueryPrivate >::get(), QSharedDataPointer< EmployeeData >::operator EmployeeData *(), QSharedDataPointer< QUrlQueryPrivate >::operator*(), and QSharedDataPointer< QUrlQueryPrivate >::operator->().

+ Here is the caller graph for this function:

◆ detach() [5/8]

Definition at line 445 of file qnetworkproxy.cpp.

◆ detach() [6/8]

Definition at line 445 of file qnetworkproxy.cpp.

◆ detach() [7/8]

Definition at line 930 of file qnetworkproxy.cpp.

◆ detach() [8/8]

Definition at line 930 of file qnetworkproxy.cpp.

◆ get() [1/2]

template<typename T>
T * QSharedDataPointer< T >::get ( )
inline
Since
6.0

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

Definition at line 48 of file qshareddata.h.

◆ get() [2/2]

template<typename T>
const T * QSharedDataPointer< T >::get ( ) const
inlinenoexcept
Since
6.0

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

Definition at line 50 of file qshareddata.h.

◆ operator bool()

template<typename T>
QSharedDataPointer< T >::operator bool ( ) const
inlinenoexcept

Definition at line 93 of file qshareddata.h.

◆ operator const T *()

template<typename T>
QSharedDataPointer< T >::operator const T * ( ) const
inlinenoexcept

Returns a pointer to the shared data object.

This function does not call detach().

Definition at line 46 of file qshareddata.h.

◆ operator T*()

template<typename 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 45 of file qshareddata.h.

◆ operator!()

template<typename T>
bool QSharedDataPointer< T >::operator! ( ) const
inlinenoexcept

Returns true if the {d pointer} of this is \nullptr.

Definition at line 94 of file qshareddata.h.

◆ operator*() [1/2]

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

Provides access to the shared data object's members.

This function calls detach().

Definition at line 41 of file qshareddata.h.

◆ operator*() [2/2]

template<typename 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 42 of file qshareddata.h.

◆ operator->() [1/2]

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

Provides access to the shared data object's members.

This function calls detach().

Definition at line 43 of file qshareddata.h.

◆ operator->() [2/2]

template<typename T>
const T * QSharedDataPointer< T >::operator-> ( ) const
inlinenoexcept

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

This function does not call detach().

Definition at line 44 of file qshareddata.h.

◆ operator=() [1/2]

template<typename T>
QSharedDataPointer & QSharedDataPointer< T >::operator= ( const QSharedDataPointer< T > & o)
inlinenoexcept

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.

Definition at line 79 of file qshareddata.h.

◆ operator=() [2/2]

template<typename T>
QSharedDataPointer & QSharedDataPointer< T >::operator= ( T * o)
inlinenoexcept

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.

Definition at line 84 of file qshareddata.h.

◆ reset()

template<typename T>
void QSharedDataPointer< T >::reset ( T * ptr = nullptr)
inlinenoexcept
Since
6.0

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.

Definition at line 68 of file qshareddata.h.

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

+ Here is the caller graph for this function:

◆ swap()

template<typename T>
void QSharedDataPointer< T >::swap ( QSharedDataPointer< T > & other)
inlinenoexcept

\memberswap{shared data pointer}

Definition at line 96 of file qshareddata.h.

◆ take()

template<typename T>
T * QSharedDataPointer< T >::take ( )
inlinenoexcept
Since
6.0

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.

Definition at line 52 of file qshareddata.h.

Friends And Related Symbol Documentation

◆ comparesEqual [1/3]

template<typename T>
bool comparesEqual ( const QSharedDataPointer< T > & lhs,
const QSharedDataPointer< T > & rhs )
friend

Definition at line 103 of file qshareddata.h.

◆ comparesEqual [2/3]

template<typename T>
bool comparesEqual ( const QSharedDataPointer< T > & lhs,
const T * rhs )
friend

Definition at line 110 of file qshareddata.h.

◆ comparesEqual [3/3]

template<typename T>
bool comparesEqual ( const QSharedDataPointer< T > & lhs,
std::nullptr_t  )
friend

Definition at line 117 of file qshareddata.h.

◆ compareThreeWay [1/3]

template<typename T>
Qt::strong_ordering compareThreeWay ( const QSharedDataPointer< T > & lhs,
const QSharedDataPointer< T > & rhs )
friend

Definition at line 106 of file qshareddata.h.

◆ compareThreeWay [2/3]

template<typename T>
Qt::strong_ordering compareThreeWay ( const QSharedDataPointer< T > & lhs,
const T * rhs )
friend

Definition at line 113 of file qshareddata.h.

◆ compareThreeWay [3/3]

template<typename T>
Qt::strong_ordering compareThreeWay ( const QSharedDataPointer< T > & lhs,
std::nullptr_t  )
friend

Definition at line 120 of file qshareddata.h.


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