Класс QSharedPointer

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

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

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

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

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

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

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

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

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

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

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

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(const QWeakPointer<T> &other)

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

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

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

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

Создает объект QSharedPointer, который совмещает указатель other.

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

[since 5.8] шаблон <typename Deleter> QSharedPointer::QSharedPointer(std::nullptr_t, Deleter d)

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

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

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

[since 5.8] QSharedPointer::QSharedPointer(std::nullptr_t)

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

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

шаблон <typename X, typename Deleter> 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().

шаблон <typename X> QSharedPointer::QSharedPointer(X *ptr)

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

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

QSharedPointer::QSharedPointer()

Создаёт QSharedPointer, который равен null (объект содержит ссылку на nullptr).

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

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

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

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

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

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

QSharedPointer::~QSharedPointer()

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

void QSharedPointer::clear()

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

шаблон <typename X> QSharedPointer<X> QSharedPointer::constCast() const

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

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

[static, since 5.1] шаблон <typename Args> QSharedPointer<T> QSharedPointer::create(Args &&... args)

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

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

Функция попытается вызвать конструктор типа T, который может принять все переданные аргументы (args). Аргументы будут переданы по значению.

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

T *QSharedPointer::data() const

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

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

шаблон <typename X> QSharedPointer<X> QSharedPointer::dynamicCast() const

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

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

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

[since 5.11] T *QSharedPointer::get() const

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

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

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

bool QSharedPointer::isNull() const

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

шаблон <typename X> QSharedPointer<X> QSharedPointer::objectCast() const

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

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

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

[since 5.0] void QSharedPointer::reset()

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

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

[since 5.0] void QSharedPointer::reset(T *t)

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

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

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

[since 5.0] шаблон <typename Deleter> void QSharedPointer::reset(T *t, Deleter deleter)

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

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

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

шаблон <typename X> QSharedPointer<X> QSharedPointer::staticCast() const

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

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

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

[since 5.3] void QSharedPointer::swap(QSharedPointer<T> &other)

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

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

QWeakPointer<T> QSharedPointer::toWeakRef() const

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

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

bool QSharedPointer::operator bool() const

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

    if (sharedptr) { ... }

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

bool QSharedPointer::operator!() const

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

    if (!sharedptr) { ... }

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

T &QSharedPointer::operator*() const

Обеспечивает доступ к членам общего указателя.

Если содержащийся указатель nullptr, поведение не определено.

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

T *QSharedPointer::operator->() const

Обеспечивает доступ к членам общего указателя.

Если содержащийся указатель nullptr, поведение не определено.

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