QtBase
v6.3.1
|
The QSharedDataPointer class represents a pointer to an implicitly shared object. More...
#include <qshareddata.h>
Public Types | |
typedef T | Type |
typedef T * | pointer |
Public Member Functions | |
void | detach () |
T & | operator* () |
const T & | operator* () const |
T * | operator-> () |
const T * | operator-> () const noexcept |
operator T* () | |
operator const T * () const noexcept | |
T * | data () |
T * | get () |
const T * | data () const noexcept |
const T * | get () const noexcept |
const T * | constData () const noexcept |
T * | take () noexcept |
QSharedDataPointer () noexcept | |
~QSharedDataPointer () | |
QSharedDataPointer (T *data) noexcept | |
QSharedDataPointer (T *data, QAdoptSharedDataTag) noexcept | |
QSharedDataPointer (const QSharedDataPointer &o) noexcept | |
void | reset (T *ptr=nullptr) noexcept |
QSharedDataPointer & | operator= (const QSharedDataPointer &o) noexcept |
QSharedDataPointer & | operator= (T *o) noexcept |
QSharedDataPointer (QSharedDataPointer &&o) noexcept | |
operator bool () const noexcept | |
bool | operator! () const noexcept |
void | swap (QSharedDataPointer &other) noexcept |
Protected Member Functions | |
T * | clone () |
The QSharedDataPointer class represents a pointer to an implicitly shared object.
\inmodule QtCore
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
Employee
to have a single data member of type {QSharedDataPointer<EmployeeData>}
.EmployeeData
class derived from \l QSharedData to contain all the data members you would normally have put in the Employee
class.\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
.
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
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} .
\codeline
Note that class Employee
also has a trivial copy constructor defined, which is not strictly required in this case.
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:
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.
\codeline
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.
\codeline
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 70 of file qshareddata.h.
QSharedDataPointer< T >::pointer |
Definition at line 74 of file qshareddata.h.
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 73 of file qshareddata.h.
|
inlinenoexcept |
Constructs a QSharedDataPointer initialized with \nullptr as {d pointer}.
Definition at line 90 of file qshareddata.h.
|
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 91 of file qshareddata.h.
|
inlineexplicitnoexcept |
Constructs a QSharedDataPointer with {d pointer} set to data and increments {data}'s reference count.
Definition at line 93 of file qshareddata.h.
|
inlinenoexcept |
Definition at line 95 of file qshareddata.h.
|
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 97 of file qshareddata.h.
|
inlinenoexcept |
Move-constructs a QSharedDataPointer instance, making it point at the same object that o was pointing to.
Definition at line 121 of file qshareddata.h.
|
protected |
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:
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 246 of file qshareddata.h.
|
inlinenoexcept |
Returns a const pointer to the shared data object. This function does not call detach().
Definition at line 87 of file qshareddata.h.
|
inline |
Returns a pointer to the shared data object. This function calls detach().
Definition at line 83 of file qshareddata.h.
|
inlinenoexcept |
Returns a pointer to the shared data object. This function does not call detach().
Definition at line 85 of file qshareddata.h.
|
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 76 of file qshareddata.h.
|
inline |
Same as data(). This function is provided for STL compatibility.
Definition at line 84 of file qshareddata.h.
|
inlinenoexcept |
Same as data(). This function is provided for STL compatibility.
Definition at line 86 of file qshareddata.h.
|
inlinenoexcept |
Definition at line 124 of file qshareddata.h.
|
inlinenoexcept |
Returns a pointer to the shared data object. This function does not call detach().
Definition at line 82 of file qshareddata.h.
|
inline |
Returns a pointer to the shared data object. This function calls detach().
Definition at line 81 of file qshareddata.h.
|
inlinenoexcept |
Returns true
if the {d pointer} of this is \nullptr.
Definition at line 125 of file qshareddata.h.
|
inline |
Provides access to the shared data object's members. This function calls detach().
Definition at line 77 of file qshareddata.h.
|
inline |
Provides const access to the shared data object's members. This function does not call detach().
Definition at line 78 of file qshareddata.h.
|
inline |
Provides access to the shared data object's members. This function calls detach().
Definition at line 79 of file qshareddata.h.
|
inlinenoexcept |
Provides const access to the shared data object's members. This function does not call detach().
Definition at line 80 of file qshareddata.h.
|
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 111 of file qshareddata.h.
|
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 116 of file qshareddata.h.
|
inlinenoexcept |
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 100 of file qshareddata.h.
|
inlinenoexcept |
Swap this instance's shared data pointer with the shared data pointer in other.
Definition at line 127 of file qshareddata.h.
|
inlinenoexcept |
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.)
Definition at line 88 of file qshareddata.h.