qscopeguard.qdoc

Go to the documentation of this file.

// Copyright (C) 2018 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Sérgio Martins <sergio.martins@kdab.com>
// Copyright (C) 2019 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
#include "qscopeguard.h"
 
QT_BEGIN_NAMESPACE
 
/*!
    \class QScopeGuard
    \since 5.12
    \inmodule QtCore
    \brief Provides a scope guard for calling a function at the end of
           a scope.
 
    QScopeGuard<F> is a template class where \a F is the type of a callable
    (such as a function pointer, functor, or lambda) that will be invoked in
    the destructor. This is useful for guaranteeing your cleanup code is
    executed, whether the function is exited normally, exited early by a return
    statement, or exited by an exception.
 
    A scope guard can be disabled using dismiss(), in which case the function
    is not run at all, or executed ahead of destruction, using commit().
 
    \note Exceptions are not supported. The callable shouldn't throw when
          executed, copied or moved.
 
    \sa QScopedValueRollback
*/
 
/*!
    \fn template <typename F> QScopeGuard<F>::QScopeGuard(F &&f)
    \fn template <typename F> QScopeGuard<F>::QScopeGuard(const F &f)
 
    Creates a scope guard that will execute \a f at the end of the scope.
 
    If \e F is a lambda, its type cannot be written. In that case you need to
    either rely on class template argument deduction (C++17 feature) and leave
    the template parameter out completely or use the helper function
    qScopeGuard() instead of this constructor.
 
    \since 5.15
*/
 
/*! \fn template <typename F> void QScopeGuard<F>::dismiss()
 
    Disarms the scope guard, so that the function \e F will not be called at
    the end of the scope.
 
    \sa commit()
*/
 
/*!
    \since 6.11
    \fn template <typename F> void QScopeGuard<F>::commit()
 
    Calls the function \e F and then disarms the scope guard. The guard must be
    armed (not been \l{dismiss()}ed) when calling this function.
 
    \sa dismiss()
*/
 
/*!
    \fn [qScopeGuard] template <typename F> QScopeGuard<typename std::decay<F>::type> qScopeGuard(F &&f)
    \inmodule QtCore
    \relates QScopeGuard
    \brief The qScopeGuard function can be used to call a function at the end
           of the scope.
    \ingroup misc
 
    Create a scope guard that will execute \a f at the end of the scope.
 
    This helper function is provided so that you can easily construct a
    QScopeGuard without having to name the template parameter for the type of
    the callable. If \e F is a lambda then you cannot write its type and relying
    on this helper or class template argument deduction is necessary.
 
    Example usage is as follows:
 
    \snippet code/src_corelib_tools_qscopeguard.cpp 0
 
*/
 
QT_END_NAMESPACE