Класс 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

Выполняет приведение типа указателя с учётом 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().