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

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.

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(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, удаляя ссылку, которая у него могла быть на указатель. Если это была последняя ссылка, то указатель сам будет удалён.

QSharedPointer<X> QSharedPointer::constCast() const

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

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

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

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

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

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

Эта функция была добавлена в 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, если этот объект ссылается на nullptr.

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. Эквивалентно:

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