Класс 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 имеет ограничения на множественное или виртуальное наследование (то есть в случаях, когда два разных адреса указателей могут ссылаться на один и тот же объект). В этом случае, если указатель преобразуется в другой тип и его значение изменяется, механизм отслеживания указателей в 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().