Класс QSharedPointer

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

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

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

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

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

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

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

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

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

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

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

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

QSharedPointer::QSharedPointer()

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

QSharedPointer::QSharedPointer(T *ptr)

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

QSharedPointer::QSharedPointer(T *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();
}

Также можно указать функцию-член напрямую, как в примере:

QSharedPointer<MyObject> obj =
    QSharedPointer<MyObject>(new MyObject, &QObject::deleteLater);

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

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