Класс QSharedPointer

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

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

Примечание: Все функции в этом классе являются повторно входящими.

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

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

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

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

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

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

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

Создаёт QSharedPointer, который указывает на null (0).

QSharedPointer::QSharedPointer(X *ptr)

Создаёт QSharedPointer, который указывает на ptr. Указатель ptr становится управляемым этим QSharedPointer и не должен передаваться другому объекту QSharedPointer или удаляться за пределами этого объекта.

Начиная с Qt 5.8, при уничтожении последней ссылки на этот QSharedPointer, ptr будет удалён путём вызова деструктора X, даже если X не совпадает с параметром шаблона QSharedPointer T. Ранее вызывался деструктор T.

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(std::nullptr_t)

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

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

QSharedPointer::QSharedPointer(std::nullptr_t, Deleter d)

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

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

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

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

Создаёт объект QSharedPointer, который разделяет указатель other.

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

QSharedPointer::QSharedPointer(const QWeakPointer<T> &other)

Создаёт QSharedPointer путём повышения слабого указателя other до сильной ссылки и разделения его указателя.

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

См. также QWeakPointer::toStrongRef().

QSharedPointer::~QSharedPointer()

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

void QSharedPointer::clear()

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

QSharedPointer<X> QSharedPointer::constCast() const

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

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

    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 если этот объект не равен null. Эта функция подходит для использования в if-constructs, например:

    if (sharedptr) { ... }

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

bool QSharedPointer::operator!() const

Возвращает true если этот объект равен null. Эта функция подходит для использования в if-constructs, например:

    if (!sharedptr) { ... }

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

T &QSharedPointer::operator*() const

Обеспечивает доступ к членам общего указателя.

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

T *QSharedPointer::operator->() const

Обеспечивает доступ к членам общего указателя.

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

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

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

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

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

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

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