Boost C++ Libraries

Imagine that we want to make many modifications to data members of some world class in its world::add_person member function. We start with adding a new person object to a vector of persons:

void world::add_person(person const& a_person) {
    bool commit = false;

    persons_.push_back(a_person);           // (1) direct action
    ...

Some operations down the road may throw an exception and all changes to involved objects should be rolled back. This all-or-nothing semantic is also known as strong guarantee.

In particular, the last added person must be deleted from persons_ if the function throws. All we need is to define a delayed action (release of a resource) right after the direct action (resource acquisition). For example (see also world.cpp):

void world::add_person(person const& a_person) {
    bool commit = false;

    persons_.push_back(a_person);           // (1) direct action
    // Following block is executed when the enclosing scope exits.
    BOOST_SCOPE_EXIT(&commit, &persons_) {
        if(!commit) persons_.pop_back();    // (2) rollback action
    } BOOST_SCOPE_EXIT_END

    // ...                                  // (3) other operations

    commit = true;                          // (4) disable rollback actions
}

The block below point (1) is a Boost.ScopeExit declaration. Unlike point (1), an execution of the Boost.ScopeExit body will be delayed until the end of the current scope. In this case it will be executed either after point (4) or on any exception. (On various versions of the GCC compiler, it is necessary to use BOOST_SCOPE_EXIT_TPL instead of BOOST_SCOPE_EXIT within templates, see later in this section for details.)

The Boost.ScopeExit declaration starts with the BOOST_SCOPE_EXIT macro invocation which accepts a comma-separated list of captured variables (a Boost.Preprocessor sequence is also accepted here for compilers that do not support variadic macros and for backward compatibility with older versions of this library, see the No Variadic Macros section). If a capture starts with the ampersand sign &, a reference to the captured variable will be available inside the Boost.ScopeExit body; otherwise, a copy of the variable will be made after the Boost.ScopeExit declaration at point (1) and only the copy will be available inside the body (in this case, the captured variable's type must be CopyConstructible).

In the example above, the variables commit and persons_ are captured by reference because the final value of the commit variable should be used to determine whether to execute rollback actions or not and the action should modify the persons_ object, not its copy. This is the most common case but passing a variable by value is sometimes useful as well.

Finally, the end of the Boost.ScopeExit body must be marked by the BOOST_SCOPE_EXIT_END macro which must follow the closing curly bracket } of the Boost.ScopeExit body. On C++11 it is also possible (but not required) to use a semi-column ; instead of the BOOST_SCOPE_EXIT_END macro. ^[2]

	Important
	In order to comply with the STL exception safety requirements, the Boost.ScopeExit body must never throw (because the library implementation executes the body within a destructor). This is true for all Boost.ScopeExit macros (including BOOST_SCOPE_EXIT_TPL and BOOST_SCOPE_EXIT_ALL) on both C++03 and C++11.

Consider a more complex example where world::add_person can save intermediate states at some point and roll back to the last saved state. We use person::evolution_ to store a version of the changes and increment it to cancel all rollback actions associated with those changes. If we pass a current value of evolution_ stored in the checkpoint variable by value, it remains unchanged within the Boost.ScopeExit body so we can compare it with the final value of evolution_. If the latter was not incremented since we saved it, the rollback action inside the Boost.ScopeExit body should be executed. For example (see also world_checkpoint.cpp):

void world::add_person(person const& a_person) {
    persons_.push_back(a_person);

    // This block must be no-throw.
    person& p = persons_.back();
    person::evolution_t checkpoint = p.evolution_;
    BOOST_SCOPE_EXIT(checkpoint, &p, &persons_) {
        if(checkpoint == p.evolution_) persons_.pop_back();
    } BOOST_SCOPE_EXIT_END

    // ...

    checkpoint = ++p.evolution_;

    // Assign new identifier to the person.
    world::id_t const prev_id = p.id_;
    p.id_ = next_id_++;
    BOOST_SCOPE_EXIT(checkpoint, &p, &next_id_, prev_id) {
        if(checkpoint == p.evolution_) {
            next_id_ = p.id_;
            p.id_ = prev_id;
        }
    } BOOST_SCOPE_EXIT_END

    // ...

    checkpoint = ++p.evolution_;
}

When multiple Boost.ScopeExit blocks are declared within the same enclosing scope, the Boost.ScopeExit bodies are executed in the reversed order of their declarations.