Класс QScopedPointer

Класс QScopedPointer хранит указатель на динамически выделенный объект и удаляет его при уничтожении. Подробнее...

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

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

Публичные функции

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

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

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

Управление объектами, выделенными на куче, вручную сложно и подвержено ошибкам, что часто приводит к утечке памяти и трудностям при обслуживании кода. QScopedPointer — это небольшой вспомогательный класс, который существенно упрощает это, назначая основанную на стеке собственность памяти выделениям на куче, более общее название — приобретение ресурсов при инициализации (RAII).

QScopedPointer гарантирует, что объект, на который указывает указатель, будет удалён, когда текущий область видимости исчезнет.

Рассмотрим эту функцию, которая выполняет выделение памяти на куче и имеет различные точки выхода:

void myFunction(bool useSubClass)
{
    MyClass *p = useSubClass ? new MyClass() : new MySubClass;
    QIODevice *device = handsOverOwnership();

    if (m_value > 3) {
        delete p;
        delete device;
        return;
    }

    try {
        process(device);
    }
    catch (...) {
        delete p;
        delete device;
        throw;
    }

    delete p;
    delete device;
}

Она обременена вызовами manual delete. С помощью QScopedPointer код можно упростить до:

void myFunction(bool useSubClass)
{
    // assuming that MyClass has a virtual destructor
    QScopedPointer<MyClass> p(useSubClass ? new MyClass() : new MySubClass);
    QScopedPointer<QIODevice> device(handsOverOwnership());

    if (m_value > 3)
        return;

    process(device);
}

Код, который генерирует компилятор для QScopedPointer, такой же, как при написании вручную. Код, который использует delete, является кандидатом для использования QScopedPointer (и если нет, возможно, другого типа умного указателя, например QSharedPointer). QScopedPointer намеренно не имеет конструктора копирования или оператора присваивания, чтобы четко передать владение и жизненный цикл.

Квалификатор const для обычного C++ указателя также можно выразить с помощью QScopedPointer:

    const QWidget *const p = new QWidget();
    // is equivalent to:
    const QScopedPointer<const QWidget> p(new QWidget());

    QWidget *const p = new QWidget();
    // is equivalent to:
    const QScopedPointer<QWidget> p(new QWidget());

    const QWidget *p = new QWidget();
    // is equivalent to:
    QScopedPointer<const QWidget> p(new QWidget());

Пользовательские обработчики очистки

Массивы, а также указатели, которые были выделены с помощью malloc , не должны удаляться с помощью delete. Второй шаблонный параметр QScopedPointer может использоваться для пользовательских обработчиков очистки.

Существуют следующие пользовательские обработчики очистки:

• QScopedPointerDeleter — по умолчанию, удаляет указатель, используя delete
• QScopedPointerArrayDeleter — удаляет указатель, используя delete []. Используйте этот обработчик для указателей, которые были выделены с помощью new [].
• QScopedPointerPodDeleter — удаляет указатель, используя free(). Используйте этот обработчик для указателей, которые были выделены с помощью malloc().
• QScopedPointerDeleteLater — удаляет указатель, вызывая deleteLater() на нём. Используйте этот обработчик для указателей на QObject, которые активно участвуют в QEventLoop.

Вы можете передавать свои классы в качестве обработчиков, при условии, что у них есть публичная статическая функция void cleanup(T *pointer).

// this QScopedPointer deletes its data using the delete[] operator:
QScopedPointer<int, QScopedPointerArrayDeleter<int> > arrayPointer(new int[42]);

// this QScopedPointer frees its data using free():
QScopedPointer<int, QScopedPointerPodDeleter> podPointer(reinterpret_cast<int *>(malloc(42)));

// this struct calls "myCustomDeallocator" to delete the pointer
struct ScopedPointerCustomDeleter
{
    static inline void cleanup(MyCustomClass *pointer)
    {
        myCustomDeallocator(pointer);
    }
};

// QScopedPointer using a custom deleter:
QScopedPointer<MyCustomClass, ScopedPointerCustomDeleter> customPointer(new MyCustomClass);

Указатели, объявленные вперёд

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

Конкретно, это означает, что все классы, содержащие QScopedPointer, которые указывают на класс, объявленный вперёд, должны иметь нелинейные конструкторы, деструкторы и операторы присваивания:

class MyPrivateClass; // forward declare MyPrivateClass

class MyClass
{
private:
    QScopedPointer<MyPrivateClass> privatePtr; // QScopedPointer to forward declared class

public:
    MyClass(); // OK
    inline ~MyClass() {} // VIOLATION - Destructor must not be inline

private:
    Q_DISABLE_COPY(MyClass) // OK - copy constructor and assignment operators
                             // are now disabled, so the compiler won't implicitely
                             // generate them.
};

В противном случае компилятор выведет предупреждение о невозможности уничтожения MyPrivateClass.

См. также QSharedPointer.

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

QScopedPointer::QScopedPointer(T *p = ...)

Конструирует этот QScopedPointer экземпляр и устанавливает его указатель на p.

QScopedPointer::~QScopedPointer()

Уничтожает этот QScopedPointer объект. Удалить объект, на который указывает его указатель.

T *QScopedPointer::data() const

Возвращает значение указателя, на который ссылается этот объект. QScopedPointer по-прежнему владеет объектом, на который указывает указатель.

T *QScopedPointer::get() const

То же самое, что и data().

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

bool QScopedPointer::isNull() const

Возвращает true если этот объект содержит указатель, который является null.

void QScopedPointer::reset(T *other = ...)

Удаляет существующий объект, на который он указывает (если таковой имеется), и устанавливает его указатель на other. QScopedPointer теперь владеет other и удалит его в своём деструкторе.

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

void QScopedPointer::swap(QScopedPointer<T, Cleanup> &other)

Поменять местами этот указатель с other.

T *QScopedPointer::take()

Возвращает значение указателя, на который ссылается этот объект. Указатель этого QScopedPointer объекта будет сброшен до null.

Вызывающие функции берут на себя владение указателем.

bool QScopedPointer::operator bool() const

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

if (scopedPointer) {
    ...
}

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

bool QScopedPointer::operator!() const

Возвращает true если указатель, на который ссылается этот объект, null, в противном случае возвращает false.

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

T &QScopedPointer::operator*() const

Предоставляет доступ к объекту указателя.

Если указанный указатель null, поведение неопределённо.

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

T *QScopedPointer::operator->() const

Предоставляет доступ к объекту указателя.

Если указанный указатель null, поведение неопределённо.

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