Класс QSharedPointer

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

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

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

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

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

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

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

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

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

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

Объект QSharedPointer можно создать из обычного указателя, другого объекта 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.

Документация по членам-функциям

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

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

Параметр deleter задаёт пользовательский удалитель для этого объекта. Пользовательский удалитель вызывается вместо оператора 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, который равен null. Это эквивалентно конструктору по умолчанию QSharedPointer.

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

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

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

Эта функция была введена в 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

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

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

[static] QSharedPointer<T> QSharedPointer::create()

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

Эта функция вызывает конструктор по умолчанию для типа T.

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

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

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

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

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

Примечание: Эта функция полностью доступна только с компилятором C++, поддерживающим идеальную передачу произвольного количества аргументов.

Если компилятор не поддерживает необходимые функции C++11, то с Qt 5.4 доступна ограниченная версия: вы можете передать один (но только один) аргумент, и он всегда будет передан по константной ссылке.

Если вы используете Qt до версии 5.4, вы должны использовать перегрузку, которая вызывает конструктор по умолчанию.

Эта функция была введена в 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().

bool QSharedPointer::isNull() const

Возвращает true, если этот объект хранит ссылку на null-указатель.

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

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