Класс QSharedPointer

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

Этот класс был представлен в Qt 4.5.

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

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

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

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

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

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

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

template <typename Deleter> QSharedPointer::QSharedPointer(std::nullptr_t, Deleter d)

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

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

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

QSharedPointer::QSharedPointer(std::nullptr_t)

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

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

template <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().

template <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 в сильную ссылку и делает этот объект общим по отношению к указателю, на который ссылается other. Текущая ссылка на указатель отбрасывается, и, если это была последняя ссылка, указатель будет удалён.

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

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

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

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

QSharedPointer::~QSharedPointer()

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

void QSharedPointer::clear()

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

template <typename X> QSharedPointer<X> QSharedPointer::constCast() const

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

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

[static] template <typename Args> QSharedPointer<T> QSharedPointer::create(Args &&... args)

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

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

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

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

T *QSharedPointer::data() const

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

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

template <typename X> 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 , если этот объект ссылается на nullptr.

template <typename X> 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.

template <typename Deleter> void QSharedPointer::reset(T *t, Deleter deleter)

Сбрасывает этот объект QSharedPointer на указание на t вместо, с обработчиком освобождения deleter. Эквивалентно:

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

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

template <typename X> 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, если содержащийся указатель не 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().