Source code
Revision control
Copy as Markdown
// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
#include <qshareddata.h>
QT_BEGIN_NAMESPACE
/*!
\class QSharedData
\inmodule QtCore
\brief The QSharedData class is a base class for shared data objects.
\reentrant
QSharedData is designed to be used with QSharedDataPointer or
QExplicitlySharedDataPointer to implement custom \l{implicitly
shared} or explicitly shared classes. QSharedData provides
\l{thread-safe} reference counting.
See QSharedDataPointer and QExplicitlySharedDataPointer for details.
*/
/*! \fn QSharedData::QSharedData()
Constructs a QSharedData object with a reference count of 0.
*/
/*! \fn QSharedData::QSharedData(const QSharedData& )
Constructs a QSharedData object with reference count 0.
The parameter is ignored.
*/
/*!
\class QAdoptSharedDataTag
\inmodule QtCore
\threadsafe
\brief The QAdoptSharedDataTag is a helper tag class.
\since 6.0
QAdoptSharedDataTag objects are used in QSharedDataPointer
and QExplicitlySharedDataPointer to adopt a pointer to
shared data.
See QSharedDataPointer and QExplicitlySharedDataPointer for details.
*/
/*!
\class QSharedDataPointer
\inmodule QtCore
\brief 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 is a template class where the template parameter
\a T specifies the type of the shared data class that derives from
QSharedData.
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 \c Employee class implicitly shared. The
procedure is:
\list
\li Define the class \c Employee to have a single data member of
type \c {QSharedDataPointer<EmployeeData>}.
\li Define the \c EmployeeData class derived from \l QSharedData to
contain all the data members you would normally have put in the
\c Employee class.
\endlist
To show this in practice, we review the source code for the
implicitly shared \c Employee class. In the header file we define the
two classes \c Employee and \c EmployeeData.
\snippet sharedemployee/employee.h 0
In class \c Employee, note the single data member, a \e {d pointer}
of type \c {QSharedDataPointer<EmployeeData>}. All accesses of
employee data must go through the \e {d pointer's} \c
{operator->()}. For write accesses, \c {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 \c Employee object don't affect
any other \c Employee objects that share the same \c EmployeeData
object.
Class \c EmployeeData inherits QSharedData, which provides the
\e{behind the scenes} reference counter. \c EmployeeData has a default
constructor, a copy constructor, and a destructor. Normally, trivial
implementations of these are all that is needed in the \e {data}
class for an implicitly shared class.
Implementing the two constructors for class \c Employee is also
straightforward. Both create a new instance of \c EmployeeData
and assign it to the \e{d pointer} .
\snippet sharedemployee/employee.h 1
\codeline
\snippet sharedemployee/employee.h 2
Note that class \c Employee also has a trivial copy constructor
defined, which is not strictly required in this case.
\snippet sharedemployee/employee.h 7
The copy constructor is not strictly required here, because class \c
EmployeeData is included in the same file as class \c Employee
(\c{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 \c EmployeeData in a separate
file, which would \e{not} be included in \c{employee.h}. Instead, we
would just predeclare the private subclass \c EmployeeData in \c
{employee.h} this way:
\snippet code/src_corelib_tools_qshareddata.cpp 0
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 \c Employee object is copied, assigned,
or passed as a parameter. It decrements the reference count whenever
an \c Employee object is deleted or goes out of scope. The shared
\c EmployeeData object is deleted automatically if and when the
reference count reaches 0.
In a non-const member function of \c Employee, whenever the \e {d
pointer} is dereferenced, QSharedDataPointer automatically calls
detach() to ensure that the function operates on its own copy of the
data.
\snippet sharedemployee/employee.h 3
\codeline
\snippet sharedemployee/employee.h 4
Note that if detach() is called more than once in a member function
due to multiple dereferences of the \e {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 \c Employee constructor, which takes an
employee ID and a name, both setId() and setName() are called, but
they don't cause \e{copy on write}, because the reference count for
the newly constructed \c EmployeeData object has just been set to 1.
In \c Employee's \e const member functions, dereferencing the \e {d
pointer} does \e not cause detach() to be called.
\snippet sharedemployee/employee.h 5
\codeline
\snippet sharedemployee/employee.h 6
Notice that there is no need to implement a copy constructor or an
assignment operator for the \c Employee class, because the copy
constructor and assignment operator provided by the C++ compiler
will do the \e{member by member} shallow copy required. The only
member to copy is the \e {d pointer}, which is a QSharedDataPointer,
whose \c {operator=()} just increments the reference count of the
shared \c EmployeeData object.
\target Implicit vs Explicit Sharing
\section1 Implicit vs Explicit Sharing
Implicit sharing might not be right for the \c Employee class.
Consider a simple example that creates two instances of the
implicitly shared \c Employee class.
\snippet sharedemployee/main.cpp 0
After the second employee e2 is created and e1 is assigned to it,
both \c e1 and \c e2 refer to Albrecht Durer, employee 1001. Both \c
Employee objects point to the same instance of \c EmployeeData,
which has reference count 2. Then \c {e1.setName("Hans Holbein")} is
called to change the employee name, but because the reference count
is greater than 1, a \e{copy on write} is performed before the name
is changed. Now \c e1 and \c e2 point to different \c 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
\c {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 \l {QExplicitlySharedDataPointer}
{explicit sharing} in the \c Employee class instead of implicit
sharing.
If you declare the \e {d pointer} in the \c Employee class to be
\c {QExplicitlySharedDataPointer<EmployeeData>}, then explicit
sharing is used and \e{copy on write} operations are not performed
automatically (i.e. detach() is not called in non-const
functions). In that case, after \c {e1.setName("Hans Holbein")}, the
employee's name has been changed, but both e1 and e2 still refer to
the same instance of \c EmployeeData, so there is only one employee
with ID 1001.
In the member function documentation, \e{d pointer} always refers
to the internal pointer to the shared data object.
\section1 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 \c Employee class
above and uses a QSharedDataPointer or QExplicitlySharedDataPointer as the
only member. This can improve performance and memory efficiency when using
Qt's \l{container classes}.
\sa QSharedData, QExplicitlySharedDataPointer, QScopedPointer, QSharedPointer
*/
/*! \typedef QSharedDataPointer::Type
This is the type of the shared data object. The \e{d pointer}
points to an object of this type.
*/
/*! \typedef QSharedDataPointer::pointer
\internal
*/
/*! \fn template <class T> T& QSharedDataPointer<T>::operator*()
Provides access to the shared data object's members.
This function calls detach().
*/
/*! \fn template <class T> const T& QSharedDataPointer<T>::operator*() const
Provides const access to the shared data object's members.
This function does \e not call detach().
*/
/*! \fn template <class T> T* QSharedDataPointer<T>::operator->()
Provides access to the shared data object's members.
This function calls detach().
*/
/*! \fn template <class T> const T* QSharedDataPointer<T>::operator->() const
Provides const access to the shared data object's members.
This function does \e not call detach().
*/
/*! \fn template <class T> QSharedDataPointer<T>::operator T*()
Returns a pointer to the shared data object.
This function calls detach().
\sa data(), constData()
*/
/*! \fn template <class T> QSharedDataPointer<T>::operator const T*() const
Returns a pointer to the shared data object.
This function does \e not call detach().
*/
/*! \fn template <class T> T* QSharedDataPointer<T>::data()
Returns a pointer to the shared data object.
This function calls detach().
\sa constData()
*/
/*! \fn template <class T> T* QSharedDataPointer<T>::get()
\since 6.0
Same as data(). This function is provided for STL compatibility.
*/
/*! \fn template <class T> const T* QSharedDataPointer<T>::data() const
Returns a pointer to the shared data object.
This function does \e not call detach().
*/
/*! \fn template <class T> const T* QSharedDataPointer<T>::get() const
\since 6.0
Same as data(). This function is provided for STL compatibility.
*/
/*! \fn template <class T> const T* QSharedDataPointer<T>::take()
\since 6.0
Returns a pointer to the shared object, and resets \e this to be \nullptr.
(That is, this function sets the \e{d pointer} of \e this to \nullptr.)
\note The reference count of the returned object will \b{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.
*/
/*! \fn template <class T> const T* QSharedDataPointer<T>::constData() const
Returns a const pointer to the shared data object.
This function does \e not call detach().
\sa data()
*/
/*! \fn template <class T> void QSharedDataPointer<T>::reset(T *ptr = nullptr)
\since 6.0
Sets the \e{d pointer} of \e this to \a ptr and increments \a{ptr}'s reference
count if \a 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.
*/
/*! \fn template <class T> void QSharedDataPointer<T>::swap(QSharedDataPointer &other)
\memberswap{shared data pointer}
*/
/*!
\fn template <class T> QSharedDataPointer<T> &QSharedDataPointer<T>::operator=(QSharedDataPointer<T> &&other)
Move-assigns \a other to this QSharedDataPointer instance.
\since 5.2
*/
/*! \fn template <class T> bool QSharedDataPointer<T>::operator==(const QSharedDataPointer<T>& lhs, const QSharedDataPointer<T>& rhs)
Returns \c true if \a lhs and \a rhs have the same \e{d pointer}.
This function does \e not call detach().
*/
/*! \fn template <class T> bool QSharedDataPointer<T>::operator!=(const QSharedDataPointer<T>& lhs, const QSharedDataPointer<T>& rhs)
Returns \c true if \a lhs and \a rhs do \e not have the same
\e{d pointer}. This function does \e not call detach().
*/
/*! \fn template <class T> bool QSharedDataPointer<T>::operator==(T* const &lhs, const QSharedDataPointer<T>& rhs)
Returns \c true if the \e{d pointer} of \a rhs is \a lhs.
This function does \e not call detach().
*/
/*! \fn template <class T> bool QSharedDataPointer<T>::operator!=(T* const &lhs, const QSharedDataPointer<T>& rhs)
Returns \c true if the \e{d pointer} of \a rhs is \e not \a lhs.
\e{d pointer}. This function does \e not call detach().
*/
/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer()
Constructs a QSharedDataPointer initialized with \nullptr as \e{d pointer}.
*/
/*!
\fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(QSharedDataPointer &&o)
Move-constructs a QSharedDataPointer instance, making it point at the same
object that \a o was pointing to.
\since 5.2
*/
/*! \fn template <class T> QSharedDataPointer<T>::~QSharedDataPointer()
Decrements the reference count of the shared data object.
If the reference count becomes 0, the shared data object
is deleted. \e This is then destroyed.
*/
/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(T* data)
Constructs a QSharedDataPointer with \e{d pointer} set to
\a data and increments \a{data}'s reference count.
*/
/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(T* data, QAdoptSharedDataTag)
\since 6.0
Constructs a QSharedDataPointer with \e{d pointer} set to
\a data. \a data's reference counter is \b{not} incremented;
this can be used to adopt pointers obtained from take().
\sa take()
*/
/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(const QSharedDataPointer<T>& o)
Sets the \e{d pointer} of \e this to the \e{d pointer} in
\a o and increments the reference count of the shared
data object.
*/
/*! \fn template <class T> QSharedDataPointer<T>& QSharedDataPointer<T>::operator=(const QSharedDataPointer<T>& o)
Sets the \e{d pointer} of \e this to the \e{d pointer} of
\a o and increments the reference count of the shared
data object. The reference count of the old shared data
object of \e this is decremented. If the reference count
of the old shared data object becomes 0, the old shared
data object is deleted.
*/
/*! \fn template <class T> QSharedDataPointer& QSharedDataPointer<T>::operator=(T* o)
Sets the \e{d pointer} og \e this to \a o and increments
\a{o}'s reference count. The reference count of the old
shared data object of \e this is decremented. If the reference
count of the old shared data object becomes 0, the old shared data
object is deleted.
*/
/*! \fn template <class T> bool QSharedDataPointer<T>::operator!() const
Returns \c true if the \e{d pointer} of \e this is \nullptr.
*/
/*! \fn template <class T> void QSharedDataPointer<T>::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
\e{d pointer} of \e this to the copy.
This function is called automatically by non-const member
functions of QSharedDataPointer if \e{copy on write} is
required. You don't need to call it yourself.
*/
/*! \fn template <class T> T *QSharedDataPointer<T>::clone()
\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 \e {operator
new} and calls the copy constructor of the type \a 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:
\snippet code/src_corelib_tools_qshareddata.cpp 1
In the example above, the template specialization for the clone()
function calls the \e {EmployeeData::clone()} virtual function. A
class derived from EmployeeData could override that function and
return the proper polymorphic type.
*/
/*!
\class QExplicitlySharedDataPointer
\inmodule QtCore
\brief The QExplicitlySharedDataPointer class represents a pointer to an explicitly shared object.
\since 4.4
\reentrant
\compares strong
\compareswith strong T* std::nullptr_t
\endcompareswith
QExplicitlySharedDataPointer is a template class where the template
parameter \a T specifies the type of the shared data class that
derives from QSharedData.
QExplicitlySharedDataPointer\<T\> makes writing your own explicitly
shared classes easy. QExplicitlySharedDataPointer implements
\l {thread-safe} reference counting, ensuring that adding
QExplicitlySharedDataPointers to your \l {reentrant} classes won't
make them non-reentrant.
Except for one big difference, QExplicitlySharedDataPointer is just
like QSharedDataPointer. The big difference is that member functions
of QExplicitlySharedDataPointer \e{do not} do the automatic
\e{copy on write} operation (detach()) that non-const members of
QSharedDataPointer do before allowing the shared data object to be
modified. There is a detach() function available, but if you really
want to detach(), you have to call it yourself. This means that
QExplicitlySharedDataPointers behave like regular C++ pointers,
except that by doing reference counting and not deleting the shared
data object until the reference count is 0, they avoid the dangling
pointer problem.
It is instructive to compare QExplicitlySharedDataPointer with
QSharedDataPointer by way of an example. Consider the \l {Employee
example} in QSharedDataPointer, modified to use explicit sharing as
explained in the discussion \l {Implicit vs Explicit Sharing}.
Note that if you use this class but find you are calling detach() a
lot, you probably should be using QSharedDataPointer instead.
In the member function documentation, \e{d pointer} always refers
to the internal pointer to the shared data object.
\sa QSharedData, QSharedDataPointer
*/
/*! \fn template <class T> T& QExplicitlySharedDataPointer<T>::operator*() const
Provides access to the shared data object's members.
*/
/*! \fn template <class T> T* QExplicitlySharedDataPointer<T>::operator->()
Provides access to the shared data object's members.
*/
/*! \fn template <class T> const T* QExplicitlySharedDataPointer<T>::operator->() const
Provides const access to the shared data object's members.
*/
/*! \fn template <class T> T* QExplicitlySharedDataPointer<T>::data() const
Returns a pointer to the shared data object.
*/
/*! \fn template <class T> T* QExplicitlySharedDataPointer<T>::get() const
\since 6.0
Same as data(). This function is provided for STL compatibility.
*/
/*! \fn template <class T> const T* QExplicitlySharedDataPointer<T>::constData() const
Returns a const pointer to the shared data object.
\sa data()
*/
/*! \fn template <class T> void QExplicitlySharedDataPointer<T>::swap(QExplicitlySharedDataPointer &other)
\memberswap{explicitly-shared data pointer}
*/
/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator==(const QExplicitlySharedDataPointer<T>& lhs, const QExplicitlySharedDataPointer<T>& rhs)
Returns \c true if \a lhs and \a rhs have the same \e{d pointer}.
*/
/*!
\fn template <class T> QExplicitlySharedDataPointer<T> &QExplicitlySharedDataPointer<T>::operator=(QExplicitlySharedDataPointer<T> &&other)
Move-assigns \a other to this QExplicitlySharedDataPointer instance.
\since 5.2
*/
/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator==(const T* const &lhs, const QExplicitlySharedDataPointer<T>& rhs)
Returns \c true if the \e{d pointer} of \a rhs is \a lhs.
*/
/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator!=(const QExplicitlySharedDataPointer<T>& lhs, const QExplicitlySharedDataPointer<T>& rhs)
Returns \c true if \a lhs and \a rhs do \e not have the same
\e{d pointer}.
*/
/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator!=(const T* const &lhs, const QExplicitlySharedDataPointer<T>& rhs)
Returns \c true if the \e{d pointer} of \a rhs is \e not \a lhs.
*/
/*! \fn template <class T> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer()
Constructs a QExplicitlySharedDataPointer initialized with \nullptr
as \e{d pointer}.
*/
/*! \fn template <class T> QExplicitlySharedDataPointer<T>::~QExplicitlySharedDataPointer()
Decrements the reference count of the shared data object.
If the reference count becomes 0, the shared data object
is deleted. \e This is then destroyed.
*/
/*!
\fn template <class T> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer(QExplicitlySharedDataPointer &&o)
Move-constructs a QExplicitlySharedDataPointer instance, making it point at the same
object that \a o was pointing to.
\since 5.2
*/
/*! \fn template <class T> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer(T* data)
Constructs a QExplicitlySharedDataPointer with \e{d pointer}
set to \a data and increments \a{data}'s reference
count.
*/
/*! \fn template <class T> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer(const QExplicitlySharedDataPointer<T>& o)
This standard copy constructor sets the \e {d pointer} of \e this to
the \e {d pointer} in \a o and increments the reference count of
the shared data object.
*/
/*! \fn template <class T> template <class X> QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer(const QExplicitlySharedDataPointer<X>& o)
This copy constructor is different in that it allows \a o to be
a different type of explicitly shared data pointer but one that has
a compatible shared data object.
By default, the \e{d pointer} of \a o (of type \c{\a X *}) gets
implicitly converted to the type \c{\a T *}; the result of this
conversion is set as the \e{d pointer} of \e{this}, and the
reference count of the shared data object is incremented.
*/
/*! \fn template <class T> QExplicitlySharedDataPointer<T>& QExplicitlySharedDataPointer<T>::operator=(const QExplicitlySharedDataPointer<T>& o)
Sets the \e{d pointer} of \e this to the \e{d pointer} of
\a o and increments the reference count of the shared
data object. The reference count of the old shared data
object of \e this is decremented. If the reference count
of the old shared data object becomes 0, the old shared
data object is deleted.
*/
/*! \fn template <class T> QExplicitlySharedDataPointer& QExplicitlySharedDataPointer<T>::operator=(T* o)
Sets the \e{d pointer} of \e this to \a o and
increments \a{o}'s reference count. The reference
count of the old shared data object of \e this is decremented.
If the reference count of the old shared data object becomes
0, the old shared data object is deleted.
*/
/*! \fn template <class T> void QExplicitlySharedDataPointer<T>::reset(T *ptr = nullptr)
\since 6.0
Sets the \e{d pointer} of \e this to \a ptr and increments \a{ptr}'s reference
count if \a 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.
*/
/*! \fn template <class T> T *QExplicitlySharedDataPointer<T>::take()
\since 5.12
Returns a pointer to the shared object, and resets \e this to be \nullptr.
(That is, this function sets the \e{d pointer} of \e this to \nullptr.)
\note The reference count of the returned object will \b{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.
*/
/*! \fn template <class T> QExplicitlySharedDataPointer<T>::operator bool () const
Returns \c true if the \e{d pointer} of \e this is \e not null.
*/
/*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator!() const
Returns \c true if the \e{d pointer} of \e this is \nullptr.
*/
/*! \fn template <class T> void QExplicitlySharedDataPointer<T>::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
\e{d pointer} of \e this to the copy.
Because QExplicitlySharedDataPointer does not do the automatic
\e{copy on write} operations that members of QSharedDataPointer do,
detach() is \e not called automatically anywhere in the member
functions of this class. If you find that you are calling detach()
everywhere in your code, consider using QSharedDataPointer instead.
*/
/*! \fn template <class T> T *QExplicitlySharedDataPointer<T>::clone()
\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 \e {operator
new} and calls the copy constructor of the type \a T.
See QSharedDataPointer<T>::clone() for an explanation of how to use it.
*/
/*!
\typedef QExplicitlySharedDataPointer::Type
This is the type of the shared data object. The \e{d pointer}
points to an object of this type.
*/
/*! \typedef QExplicitlySharedDataPointer::pointer
\internal
*/
QT_END_NAMESPACE