QSharedDataPointer 类表示隐式共享对象指针。 更多...
| 头： | #include <QSharedDataPointer> |
| CMake: |
find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
注意： 此类的所有函数 可重入 .
| Type |
| QSharedDataPointer () | |
| QSharedDataPointer (T * data ) | |
(从 6.0 起)
|
QSharedDataPointer (T * data , QAdoptSharedDataTag) |
| QSharedDataPointer (const QSharedDataPointer<T> & o ) | |
| QSharedDataPointer (QSharedDataPointer<T> && o ) | |
| ~QSharedDataPointer () | |
| const T * | constData () const |
| T * | data () |
| const T * | data () const |
| void | detach () |
(从 6.0 起)
T *
|
get () |
(从 6.0 起)
const T *
|
get () const |
(从 6.0 起)
void
|
reset (T * ptr = nullptr) |
| void | swap (QSharedDataPointer<T> & other ) |
(从 6.0 起)
T *
|
take () |
| T * | operator T * () |
| const T * | operator const T * () const |
| bool | operator! () const |
| T & | operator* () |
| const T & | operator* () const |
| T * | operator-> () |
| const T * | operator-> () const |
| QSharedDataPointer<T> & | operator= (const QSharedDataPointer<T> & o ) |
| QSharedDataPointer<T> & | operator= (T * o ) |
| QSharedDataPointer<T> & | operator= (QSharedDataPointer<T> && other ) |
| T * | clone () |
| bool | operator!= (const QSharedDataPointer<T> & lhs , const QSharedDataPointer<T> & rhs ) |
| bool | operator!= (const T * ptr , const QSharedDataPointer<T> & rhs ) |
| bool | operator== (const QSharedDataPointer<T> & lhs , const QSharedDataPointer<T> & rhs ) |
| bool | operator== (const T * ptr , const QSharedDataPointer<T> & rhs ) |
QSharedDataPointer<T> makes writing your own 隐式共享 classes easy. QSharedDataPointer implements thread-safe reference counting, ensuring that adding QSharedDataPointers to your 可重入 classes won't make them non-reentrant.
隐式共享 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 页面，了解更多信息。
Suppose you want to make an
Employee
class implicitly shared. The procedure is:
Employee
to have a single data member of type
QSharedDataPointer<EmployeeData>
.
EmployeeData
class derived from
QSharedData
to contain all the data members you would normally have put in the
Employee
类。
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; QString name; }; class Employee { public: Employee() { d = new EmployeeData; } Employee(int id, const 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(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
类型
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
对象。
类
EmployeeData
继承
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, const 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(const QString &name) { d->name = name; }
注意，若 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.
在
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
对象。
Implicit sharing might not be right for the
Employee
class. Consider a simple example that creates two instances of the implicitly shared
Employee
类。
#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
explicit sharing
在
Employee
class instead of implicit sharing.
If you declare the
d pointer
在
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.
You should consider marking your implicitly shared class as a movable type using the
Q_DECLARE_TYPEINFO
() macro if it resembles the
Employee
class above and uses a QSharedDataPointer or
QExplicitlySharedDataPointer
as the only member. This can improve performance and memory efficiency when using Qt's
容器类
.
另请参阅 QSharedData , QExplicitlySharedDataPointer , QScopedPointer ，和 QSharedPointer .
这是共享数据对象的类型。 d pointer 指向此类型的对象。
[noexcept]
QSharedDataPointer::
QSharedDataPointer
()
构造 QSharedDataPointer 初始采用
nullptr
as
d pointer
.
[explicit noexcept]
QSharedDataPointer::
QSharedDataPointer
(
T
*
data
)
构造 QSharedDataPointer 采用 d pointer 设为 data 并递增 data 的引用计数。
[noexcept, since 6.0]
QSharedDataPointer::
QSharedDataPointer
(
T
*
data
,
QAdoptSharedDataTag
)
构造 QSharedDataPointer 采用 d pointer 设为 data . data 's reference counter is not incremented; this can be used to adopt pointers obtained from take ().
该函数在 Qt 6.0 引入。
另请参阅 take ().
[noexcept]
QSharedDataPointer::
QSharedDataPointer
(const
QSharedDataPointer
<
T
> &
o
)
设置 d pointer of this 到 d pointer in o and increments the reference count of the shared data object.
[noexcept]
QSharedDataPointer::
QSharedDataPointer
(
QSharedDataPointer
<
T
> &&
o
)
Move-constructs a QSharedDataPointer instance, making it point at the same object that o 所指向的。
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.
[protected]
T
*QSharedDataPointer::
clone
()
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<>
EmployeeData *QSharedDataPointer<EmployeeData>::clone()
{
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.
[noexcept]
const
T
*QSharedDataPointer::
constData
() const
Returns a const pointer to the shared data object. This function does not call detach ().
另请参阅 data ().
Returns a pointer to the shared data object. This function calls detach ().
另请参阅 constData ().
[noexcept]
const
T
*QSharedDataPointer::
data
() const
Returns a pointer to the shared data object. This function does not call 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.
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.
[since 6.0]
T
*QSharedDataPointer::
get
()
如同 data ()。此函数为兼容 STL (标准模板库) 提供。
该函数在 Qt 6.0 引入。
[noexcept, since 6.0]
const
T
*QSharedDataPointer::
get
() const
如同 data ()。此函数为兼容 STL (标准模板库) 提供。
该函数在 Qt 6.0 引入。
[noexcept, since 6.0]
void
QSharedDataPointer::
reset
(
T
*
ptr
= nullptr)
设置
d pointer
of
this
to
ptr
并递增
ptr
的引用计数若
ptr
不是
nullptr
. The reference count of the old shared data object is decremented, and the object deleted if the reference count reaches 0.
该函数在 Qt 6.0 引入。
[noexcept]
void
QSharedDataPointer::
swap
(
QSharedDataPointer
<
T
> &
other
)
Swap this instance's shared data pointer with the shared data pointer in other .
[noexcept, since 6.0]
T
*QSharedDataPointer::
take
()
Returns a pointer to the shared object, and resets
this
到
nullptr
. (That is, this function sets the
d pointer
of
this
to
nullptr
)。
注意： 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.
该函数在 Qt 6.0 引入。
Returns a pointer to the shared data object. This function calls detach ().
[noexcept]
const
T
*QSharedDataPointer::
operator const T *
() const
Returns a pointer to the shared data object. This function does not call detach ().
[noexcept]
bool
QSharedDataPointer::
operator!
() const
返回
true
若
d pointer
of
this
is
nullptr
.
Provides access to the shared data object's members. This function calls detach ().
Provides const access to the shared data object's members. This function does not call detach ().
Provides access to the shared data object's members. This function calls detach ().
[noexcept]
const
T
*QSharedDataPointer::
operator->
() const
Provides const access to the shared data object's members. This function does not call detach ().
[noexcept]
QSharedDataPointer
<
T
> &QSharedDataPointer::
operator=
(const
QSharedDataPointer
<
T
> &
o
)
设置 d pointer of this 到 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.
[noexcept]
QSharedDataPointer
<
T
> &QSharedDataPointer::
operator=
(
T
*
o
)
设置 d pointer og this to o 并递增 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.
[noexcept]
QSharedDataPointer
<
T
> &QSharedDataPointer::
operator=
(
QSharedDataPointer
<
T
> &&
other
)
移动赋值 other 到此 QSharedDataPointer 实例。
[noexcept]
bool
operator!=
(const
QSharedDataPointer
<
T
> &
lhs
, const
QSharedDataPointer
<
T
> &
rhs
)
返回
true
if
lhs
and
rhs
do
not
有相同
d pointer
. This function does
not
call
detach
().
[noexcept]
bool
operator!=
(const
T
*
ptr
, const
QSharedDataPointer
<
T
> &
rhs
)
返回
true
若
d pointer
of
rhs
is
not
ptr
.
d pointer
. This function does
not
call
detach
().
[noexcept]
bool
operator==
(const
QSharedDataPointer
<
T
> &
lhs
, const
QSharedDataPointer
<
T
> &
rhs
)
返回
true
if
lhs
and
rhs
有相同
d pointer
. This function does
not
call
detach
().
[noexcept]
bool
operator==
(const
T
*
ptr
, const
QSharedDataPointer
<
T
> &
rhs
)
返回
true
若
d pointer
of
rhs
is
ptr
. This function does
not
call
detach
().