Класс QSharedPointer

Класс QSharedPointer хранит сильную ссылку на общий указатель. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются реентерабельными.

Открытые функции

Статические открытые члены

Связанные внешние члены

Подробное описание

Класс QSharedPointer хранит сильную ссылку на общий указатель.

Класс QSharedPointer — это автоматический общий указатель в C++. Он ведет себя точно как обычный указатель для обычных целей, в том числе в отношении константности.

Класс QSharedPointer удалит указанный им объект при выходе из области видимости, при условии, что на него не ссылаются другие объекты QSharedPointer.

Объект QSharedPointer может быть создан из обычного указателя, другого объекта QSharedPointer или путем повышения объекта QWeakPointer до сильной ссылки.

Безопасность потоков

Классы QSharedPointer и QWeakPointer безопасны для работы в потоках и работают атомарно со значением указателя. Разные потоки также могут обращаться к QSharedPointer или QWeakPointer, указывающим на один и тот же объект, одновременно без необходимости использования механизмов блокировки.

Следует отметить, что, хотя к значению указателя можно получить доступ таким образом, QSharedPointer и QWeakPointer не гарантируют, что указанный объект существует. Правила безопасности потоков и реентерабельности для этого объекта по-прежнему применяются.

Другие классы указателей

Qt также предоставляет два других класса-обертки указателей: QPointer и QSharedDataPointer. Они несовместимы друг с другом, так как у каждого из них совершенно разные области применения.

QSharedPointer хранит общий указатель с помощью внешнего счётчика ссылок (т.е. счётчик ссылок, размещённый вне объекта). Как следует из названия, значение указателя делится между всеми экземплярами QSharedPointer и QWeakPointer. Однако содержимое объекта, на который указывает указатель, не следует рассматривать как общее: существует только один объект. По этой причине QSharedPointer не предоставляет способ отсоединения или создания копий объекта, на который указывает указатель.

QSharedDataPointer, с другой стороны, хранит указатель на общие данные (т.е. класс, производный от QSharedData). Он делает это с помощью внутреннего счётчика ссылок, размещённого в базовом классе QSharedData. Таким образом, этот класс может отсоединяться в зависимости от типа доступа к защищаемым данным: при доступе без const он создаёт копию атомарно для завершения операции.

QExplicitlySharedDataPointer является вариантом QSharedDataPointer, за исключением того, что он отсоединяется только при явном вызове QExplicitlySharedDataPointer::detach() (отсюда и название).

QScopedPointer просто хранит указатель на объект, выделенный на куче, и удаляет его в своём деструкторе. Этот класс полезен, когда объект нужно выделить на куче и удалить, но больше ничего не делать. QScopedPointer является лёгким, он не использует дополнительной структуры или подсчёта ссылок.

Наконец, QPointer хранит указатель на объект, производный от QObject, но делает это слабо. QWeakPointer имеет ту же функциональность, но его использование для этой функции устарело.

Дополнительный отслеживание указателей

Функцией QSharedPointer, которая может быть включена во время компиляции для отладки, является механизм отслеживания указателей. При включении QSharedPointer регистрирует в глобальном наборе все отслеживаемые им указатели. Это позволяет поймать ошибки, такие как присвоение одного и того же указателя двум объектам QSharedPointer.

Эта функция включена путём определения макроса QT_SHAREDPOINTER_TRACK_POINTERS перед включением заголовка QSharedPointer.

Это безопасно использовать эту функцию даже с кодом, скомпилированным без этой функции. QSharedPointer будет гарантировать, что указатель удалён из трекера даже из кода, скомпилированного без отслеживания указателей.

Однако следует отметить, что функция отслеживания указателей имеет ограничения на множественное или виртуальное наследование (то есть в случаях, когда два разных адреса указателей могут ссылаться на один и тот же объект). В этом случае, если указатель преобразован в другой тип и его значение изменяется, механизм отслеживания указателей QSharedPointer может не обнаружить, что отслеживаемый объект является тем же.

См. также QSharedDataPointer, QWeakPointer, QScopedPointer и QEnableSharedFromThis.

Документация по функциям-членам

QSharedPointer::QSharedPointer()

Создаёт QSharedPointer, который указывает на ноль (0).

QSharedPointer::QSharedPointer(X *ptr)

Создаёт QSharedPointer, который указывает на ptr. Указатель ptr управляется этим QSharedPointer и не должен передаваться другому объекту QSharedPointer или удаляться вне этого объекта.

Начиная с Qt 5.8, при уничтожении последней ссылки на этот QSharedPointer, ptr будет удалён вызовом деструктора X (даже если X не совпадает с шаблоном параметром QSharedPointer T). Ранее вызывался деструктор T.

QSharedPointer::QSharedPointer(X *ptr, Deleter d)

Создаёт QSharedPointer, который указывает на ptr. Указатель ptr управляется этим QSharedPointer и не должен передаваться другому объекту QSharedPointer или удаляться вне этого объекта.

Параметр делегата d задаёт пользовательский делегат для этого объекта. Пользовательский делегат вызывается вместо оператора delete(), когда счётчик сильных ссылок падает до 0. Это полезно, например, для вызова deleteLater() на QObject вместо этого:

static void doDeleteLater(MyObject *obj)
{
    obj->deleteLater();
}

void otherFunction()
{
    QSharedPointer<MyObject> obj =
        QSharedPointer<MyObject>(new MyObject, doDeleteLater);

    // continue using obj
    obj.clear();    // calls obj->deleteLater();
}

Обратите внимание, что пользовательская функция делегата будет вызвана с указателем на тип X, даже если шаблонный параметр QSharedPointer T не совпадает.

Также можно указать функцию-член напрямую, как в:

QSharedPointer<MyObject> obj =
    QSharedPointer<MyObject>(new MyObject, &QObject::deleteLater);

См. также clear().

QSharedPointer::QSharedPointer(std::nullptr_t)

Создаёт QSharedPointer, который является нулевым. Это эквивалентно конструктору по умолчанию QSharedPointer.

Эта функция была добавлена в Qt 5.8.

QSharedPointer::QSharedPointer(std::nullptr_t, Deleter d)

Создаёт QSharedPointer, который является нулевым. Это эквивалентно конструктору по умолчанию QSharedPointer.

Параметр делегата d задаёт пользовательский делегат для этого объекта. Пользовательский делегат вызывается вместо оператора delete(), когда счётчик сильных ссылок падает до 0.

Эта функция была добавлена в Qt 5.8.

QSharedPointer::QSharedPointer(const QSharedPointer<T> &other)

Создаёт объект QSharedPointer, который разделяет указатель other.

Если T является производным типом шаблона параметра этого класса, QSharedPointer выполнит автоматическое преобразование. В противном случае вы получите ошибку компилятора.

QSharedPointer::QSharedPointer(const QWeakPointer<T> &other)

Создаёт QSharedPointer путём повышения слабой ссылки other до сильной ссылки и разделения её указателя.

Если T является производным типом шаблона параметра этого класса, QSharedPointer выполнит автоматическое преобразование. В противном случае вы получите ошибку компилятора.

См. также QWeakPointer::toStrongRef().

QSharedPointer::~QSharedPointer()

Уничтожает этот объект QSharedPointer. Если это последняя ссылка на хранимый указатель, он также будет удалён.

void QSharedPointer::clear()

Очищает этот объект QSharedPointer, удаляя ссылку, которая у него могла быть на указатель. Если это была последняя ссылка, то сам указатель будет удалён.

QSharedPointer<X> QSharedPointer::constCast() const

Выполняет const_cast от типа указателя до X и возвращает QSharedPointer, который разделяет ссылку. Эта функция может использоваться для повышения и понижения типов, но более полезна для повышения типов.

См. также isNull() и qSharedPointerConstCast().

[static] QSharedPointer<T> QSharedPointer::create()

Создаёт объект QSharedPointer и выделяет новый элемент типа T. Внутренние данные QSharedPointer и объект выделяются в одной памяти, что может помочь уменьшить фрагментацию памяти в долгоживущем приложении.

Эта функция вызывает конструктор по умолчанию для типа T.

Эта функция была добавлена в Qt 5.1.

[static] QSharedPointer<T> QSharedPointer::create(...)

Это перегруженная функция.

Создаёт объект QSharedPointer и выделяет новый элемент типа T. Внутренние данные QSharedPointer и объект выделяются в одной памяти, что может помочь уменьшить фрагментацию памяти в долгоживущем приложении.

Эта функция попытается вызвать конструктор типа T, который может принять все переданные аргументы. Аргументы будут переданы идеально.

Примечание: Эта функция доступна только с компилятором C++11, который поддерживает идеальную передачу произвольного количества аргументов.

Если компилятор не поддерживает необходимые функции C++11, то с Qt 5.4 доступна ограниченная версия: можно передать один (но только один) аргумент, и он всегда будет передан по константной ссылке.

Если вы нацеливаетесь на Qt до версии 5.4, вам необходимо использовать перегрузку, которая вызывает конструктор по умолчанию.

Эта функция была добавлена в Qt 5.1.

T *QSharedPointer::data() const

Возвращает значение указателя, на который ссылается этот объект.

Примечание: не удаляйте указатель, возвращённый этой функцией, и не передавайте его другой функции, которая могла бы его удалить, включая создание объектов QSharedPointer или QWeakPointer.

QSharedPointer<X> QSharedPointer::dynamicCast() const

Выполняет динамическое приведение типов указателя в этом объекте к X и возвращает QSharedPointer, разделяющий ссылку. Если эта функция используется для приведения к более общему типу, то QSharedPointer выполнит dynamic_cast, что означает, что если объект, на который указывает данный QSharedPointer, не является объектом типа X, возвращаемый объект будет null.

Примечание: шаблонный тип X должен иметь те же квалификаторы const и volatile, что и шаблон этого объекта, иначе приведение типов не удастся. Используйте constCast(), если нужно убрать эти квалификаторы.

См. также qSharedPointerDynamicCast().

T *QSharedPointer::get() const

То же, что и data().

Эта функция предоставлена для совместимости с API std::shared_ptr.

Эта функция была добавлена в Qt 5.11.

bool QSharedPointer::isNull() const

Возвращает true, если этот объект содержит ссылку на null-указатель.

QSharedPointer<X> QSharedPointer::objectCast() const

Выполняет qobject_cast() от типа этого указателя к X и возвращает QSharedPointer, разделяющий ссылку. Если эта функция используется для приведения к более общему типу, то QSharedPointer выполнит qobject_cast, что означает, что если объект, на который указывает данный QSharedPointer, не является объектом типа X, возвращаемый объект будет null.

Примечание: шаблонный тип X должен иметь те же квалификаторы const и volatile, что и шаблон этого объекта, иначе приведение типов не удастся. Используйте constCast(), если нужно убрать эти квалификаторы.

Эта функция была добавлена в Qt 4.6.

См. также qSharedPointerObjectCast().

void QSharedPointer::reset()

То же, что и clear(). Для совместимости со std::shared_ptr.

Эта функция была добавлена в Qt 5.0.

void QSharedPointer::reset(T *t)

Сбрасывает этот объект QSharedPointer на указание на t. Эквивалентно:

QSharedPointer<T> other(t); this->swap(other);

Эта функция была добавлена в Qt 5.0.

void QSharedPointer::reset(T *t, Deleter deleter)

Сбрасывает этот объект QSharedPointer на указание на t с помощью Deleter deleter. Эквивалентно:

QSharedPointer<T> other(t, deleter); this->swap(other);

Эта функция была добавлена в Qt 5.0.

QSharedPointer<X> QSharedPointer::staticCast() const

Выполняет статическое приведение типов от типа этого указателя к X и возвращает QSharedPointer, разделяющий ссылку. Эта функция может использоваться для приведения как к более общему, так и к более конкретному типу, но более полезна для приведения к более общему типу.

Примечание: шаблонный тип X должен иметь те же квалификаторы const и volatile, что и шаблон этого объекта, иначе приведение типов не удастся. Используйте constCast(), если нужно убрать эти квалификаторы.

См. также dynamicCast(), constCast() и qSharedPointerCast().

void QSharedPointer::swap(QSharedPointer<T> &other)

Меняет местами этот экземпляр разделяемого указателя с other. Эта функция очень быстрая и никогда не терпит неудачу.

Эта функция была добавлена в Qt 5.3.

QWeakPointer<T> QSharedPointer::toWeakRef() const

Возвращает объект слабой ссылки, разделяющий указатель, на который ссылается этот объект.

См. также QWeakPointer::QWeakPointer().

bool QSharedPointer::operator bool() const

Возвращает true, если этот объект не null. Эта функция подходит для использования в if-constructs, например:

if (sharedptr) { ... }

См. также isNull().

bool QSharedPointer::operator!() const

Возвращает true, если этот объект null. Эта функция подходит для использования в if-constructs, например:

if (!sharedptr) { ... }

См. также isNull().

T &QSharedPointer::operator*() const

Предоставляет доступ к членам разделяемого указателя.

См. также isNull().

T *QSharedPointer::operator->() const

Предоставляет доступ к членам разделяемого указателя.

См. также isNull().

QSharedPointer<T> &QSharedPointer::operator=(const QSharedPointer<T> &other)

Заставляет этот объект разделять указатель other. Текущая ссылка на указатель отбрасывается, и, если это была последняя ссылка, указатель будет удалён.

Если T является производным типом от шаблона параметров этого класса, QSharedPointer выполнит автоматическое приведение. В противном случае вы получите ошибку компилятора.

QSharedPointer<T> &QSharedPointer::operator=(const QWeakPointer<T> &other)

Преобразует other в сильную ссылку и заставляет этот объект разделять ссылку на указатель, на который она ссылается. Текущая ссылка на указатель отбрасывается, и, если это была последняя ссылка, указатель будет удалён.

Если T является производным типом от шаблона параметров этого класса, QSharedPointer выполнит автоматическое приведение. В противном случае вы получите ошибку компилятора.