Класс QSharedPointer

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

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

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

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

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

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

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

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

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

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

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

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

QSharedPointer и QWeakPointer являются реентерабельными классами. Это означает, что, как правило, к данному объекту QSharedPointer или QWeakPointer нельзя получить доступ из нескольких потоков одновременно без синхронизации.

Разные объекты QSharedPointer и QWeakPointer могут безопасно использоваться из нескольких потоков одновременно. Это включает случай, когда они содержат указатели на один и тот же объект; механизм подсчета ссылок является атомным, и никакая ручная синхронизация не требуется.

Следует отметить, что, хотя к значению указателя можно получить доступ таким образом (то есть из нескольких потоков одновременно без синхронизации), QSharedPointer и QWeakPointer не гарантируют, что объект, на который он указывает, будет доступен. Применимы правила безопасности потоков и реентерабельности для этого объекта.

Другие классы указателей

Qt также предоставляет два других класса-обертки для указателей: QPointer и QSharedDataPointer. Они несовместимы друг с другом, так как каждый имеет свое очень специфическое применение.

QSharedPointer хранит общий указатель с помощью внешнего счетчика ссылок (т.е., счетчика ссылок, расположенного вне объекта). Как следует из названия, значение указателя совместно используется всеми экземплярами QSharedPointer и QWeakPointer. Однако содержимое объекта, на который указывает указатель, не должно считаться общим: существует только один объект. По этой причине QSharedPointer не предоставляет способ отсоединения или создания копий объекта, на который он указывает.

QSharedDataPointer, с другой стороны, хранит указатель на общие данные (т.е., класс, производный от QSharedData). Он делает это с помощью внутреннего счетчика ссылок, размещенного в базовом классе QSharedData. Таким образом, этот класс может отсоединяться в зависимости от типа доступа к защищаемым данным: если это доступ без констант, он атомарно создает копию для завершения операции.

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, который является нулевым. Это эквивалентно конструктору по умолчанию QSharedPointer.

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

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

QSharedPointer::QSharedPointer(std::nullptr_t)

Создает QSharedPointer, который является нулевым. Это эквивалентно конструктору по умолчанию 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, который является нулевым (объект хранит ссылку на 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, возвращаемый объект будет нулевым.

Примечание: шаблонный тип 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, возвращаемый объект будет нулевым.

Примечание: шаблонный тип 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 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().