| Home | Libraries | People | FAQ | More

## Macro BOOST_SCOPE_EXIT

BOOST_SCOPE_EXIT — This macro declares a scope exit.

## Synopsis

    // In header: <boost/scope_exit.hpp>

    BOOST_SCOPE_EXIT(capture_list)

## Description

The scope exit declaration schedules the execution of the scope exit body at the exit of the enclosing scope:

    { // Some local scope.
        ...
        BOOST_SCOPE_EXIT(capture_list) {
            ... // Body code.
        } BOOST_SCOPE_EXIT_END
        ...
    }

The enclosing scope must be local. If multiple scope exits are declared within the same enclosing scope, the scope exit bodies are executed in the reversed order of their declarations. Note how the end of the scope exit body must be marked by `BOOST_SCOPE_EXIT_END`.

Parameters:

`capture_list`

On compilers that support variadic macros (see also Boost.Config `BOOST_NO_CXX11_VARIADIC_MACROS`), the capture list syntax is defined by the following grammar:

    capture_list:
            void | capture_tuple | capture_sequence
    capture_tuple:
            capture, capture, ...
    capture_sequence:
            (capture) (capture) ...
    capture:
            [&]variable | this_

On compilers that do not support variadic macros, `capture_tuple` cannot be used:

    capture_list:
            void | capture_sequence

Furthermore, if `BOOST_SCOPE_EXIT_CONFIG_USE_LAMBDAS` is defined on C++11 compilers that support lambda functions (i.e., Boost.Config's `BOOST_NO_CXX11_LAMBDAS` is not defined) then a semicolon `;` can be used instead of `BOOST_SCOPE_EXIT_END` and `this` can be used instead of `this_`:

    capture:
            [&]variable | this_ | this

(Lexical conventions: `token1 | token2` means either `token1` or `token2`; `[token]` means either `token` or nothing; `{expression}` means the tokens resulting from the expression.)

Note that on compilers that support variadic macros (most of moder compliers and all C++11 compilers), the capture list can be specified as a comma-separated list of tokens (this is the preferred syntax). However, on all compilers the same macro `BOOST_SCOPE_EXIT` also allows to specify the capture list as a Boost.Preprocessor sequence of tokens (for supporting compilers without variadic macros and for backward compatibility with older versions of this library).

The name `variable` of each captured variable must be a valid name in the enclosing scope and it must appear exactly once in the capture list. If a capture starts with the ampersand sign `&`, the corresponding variable will be available by reference within the scope exit body; otherwise, a copy of the variable will be made at the point of the scope exit declaration and that copy will be available inside the scope exit body (in this case, the variable's type must be `CopyConstructible`).

From within a member function, the object `this` can be captured using the special name `this_` in both the capture list and the scope exit body (using `this` instead of `this_` in the scope exit body leads to undefined behaviour).

It is possible to capture no variable by specifying the capture list as `void` (regardless of variadic macro support).

Only variables listed in the capture list, static variables, `extern` variables, global variables, functions, and enumerations from the enclosing scope can be used inside the scope exit body.

On various GCC versions the special macro `BOOST_SCOPE_EXIT_TPL` must be used instead of `BOOST_SCOPE_EXIT` within templates (to maximize portability, it is recommended to always use `BOOST_SCOPE_EXIT_TPL` within templates).

On C++11, it is possible capture all variables in scope without listing their names one-by-one using the macro `BOOST_SCOPE_EXIT_ALL`.

In general, the special macro `BOOST_SCOPE_EXIT_ID` must be used instead of `BOOST_SCOPE_EXIT` when it is necessary to expand multiple scope exit declarations on the same line.

Warning: The implementation executes the scope exit body within a destructor thus the scope exit body must never throw in order to comply with STL exception safety requirements.

Note: The implementation uses Boost.Typeof to automatically deduce the types of the captured variables. In order to compile code in type-of emulation mode, all types must be properly registered with Boost.Typeof (see the Getting Started section).

See: Tutorial section, Getting Started section, No Variadic Macros section, `BOOST_SCOPE_EXIT_TPL`, `BOOST_SCOPE_EXIT_ALL`, `BOOST_SCOPE_EXIT_END`, `BOOST_SCOPE_EXIT_ID`.