Класс QScopedPointer

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

Этот класс был представлен в Qt 4.6.

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

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

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

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

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

Управление объектами, выделенными в куче вручную, сложно и подвержено ошибкам, в результате чего код часто приводит к утечкам памяти и трудно поддерживается. 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;
}

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

Константное квалификатор обычного 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, указывающие на предварительно объявленный класс, должны иметь конструкторы, деструкторы и операторы присваивания, которые не являются inline:

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 если этот объект ссылается на nullptr.

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

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

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

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

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

T *QScopedPointer::take()

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

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

bool QScopedPointer::operator bool() const

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

if (scopedPointer) {
    ...
}

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

bool QScopedPointer::operator!() const

Возвращает true если этот объект ссылается на nullptr.

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

T &QScopedPointer::operator*() const

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

Если содержащийся указатель nullptr, поведение не определено.

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

T *QScopedPointer::operator->() const

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

Если содержащийся указатель nullptr, поведение не определено.

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