Generic: Change the Way You Write Exception-Safe Code — Forever

Call it overselling, but we'll tell you up front: we have killer material for this article. This is only because I convinced my good friend Petru Marginean to be my coauthor. Petru has developed a library facility that is helpful with exceptions. Together, we streamlined the implementation until we obtained a lean, mean library that can make writing exception-safe code much easier.

Let's face it, writing correct code in the presence of exceptions is a not an easy task. Exceptions establish a separate control flow that has little to do with the main control flow of the application. Figuring out the exception flow requires a different way of thinking, as well as new tools.

Writing Exception-Safe Code Is Hard: An Example

Let's say you are developing one of those trendy instant messaging servers. Users can log on and off the system and can send messages to each other. You hold a server-side database of users, plus in-memory information for users who are logged on. Each user can have friends. The list of friends is also kept both in the database and in memory.

When a user adds or removes a friend, you need to do two things: update the database and update the in-memory cache that you keep for that user. It's that simple.

Assuming that you model per-user information with a class called User and the user database with a UserDatabase class, the code for adding a friend might look like this:

class User
{
    ...
    string GetName();
    void AddFriend(User& newFriend);
private:
    typedef vector<User*> UserCont;
    UserCont friends_;
    UserDatabase* pDB_;
};
void User::AddFriend(User& newFriend)
{
    // Add the new friend to the database
    pDB_->AddFriend(GetName(), newFriend.GetName());
    // Add the new friend to the vector of friends
    friends_.push_back(&newFriend);
}

void User::AddFriend(User& newFriend)
{
    // Add the new friend to the vector of friends
    // If this throws, the friend is not added to
    //     the vector, nor the database
    friends_.push_back(&newFriend);
    // Add the new friend to the database
    pDB_->AddFriend(GetName(), newFriend.GetName());
}

Solution 1: Brute Force

void User::AddFriend(User& newFriend)
{
    friends_.push_back(&newFriend);
    try
    {
        pDB_->AddFriend(GetName(), newFriend.GetName());
    }
    catch (...)
    {
        friends_.pop_back();
        throw;
    }
}

Solution 2: The Politically Correct Approach

class VectorInserter
{
public:
    VectorInserter(std::vector& v, User& u)
    : container_(v), commit_(false)
    {
        container_.push_back(&u);
    }
    void Commit() throw()
    {
        commit_ = true;
    }
    ~VectorInserter()
    {
        if (!commit_) container_.pop_back();
    }
private:
    std::vector& container_;
    bool commit_;
};

void User::AddFriend(User& newFriend)
{
    VectorInserter ins(friends_, &newFriend);
    pDB_->AddFriend(GetName(), newFriend.GetName());
    // Everything went fine, commit the vector insertion
    ins.Commit();
}

Solution 3: The Real Approach

void User::AddFriend(User& newFriend)
{
    friends_.push_back(&newFriend);
    pDB_->AddFriend(GetName(), newFriend.GetName());
}

Solution 4: Petru's Approach

void User::AddFriend(User& newFriend)
{
    friends_.push_back(&newFriend);
    ScopeGuard guard = MakeObjGuard(
        friends_, &UserCont::pop_back);
    pDB_->AddFriend(GetName(), newFriend.GetName());
    guard.Dismiss();
}

friends_.push_back(&newFriend);
ScopeGuard guard = MakeObjGuard(
    friends_, &UserCont::pop_back);

void* buffer = std::malloc(1024);
ScopeGuard freeIt = MakeGuard(std::free, buffer);
FILE* topSecret = std::fopen("cia.txt");
ScopeGuard closeIt = MakeGuard(std::fclose, topSecret);

Implementing ScopeGuard

class ScopeGuardImplBase
{
public:
    void Dismiss() const throw()
    {    dismissed_ = true;    }
protected:
    ScopeGuardImplBase() : dismissed_(false)
    {}
    ScopeGuardImplBase(const ScopeGuardImplBase& other)
    : dismissed_(other.dismissed_)
    {    other.Dismiss();    }
    ~ScopeGuardImplBase() {} // nonvirtual (see below why)
    mutable bool dismissed_;

private:
    // Disable assignment
    ScopeGuardImplBase& operator=(
        const ScopeGuardImplBase&);
};

template <typename Fun, typename Parm>
class ScopeGuardImpl1 : public ScopeGuardImplBase
{
public:
    ScopeGuardImpl1(const Fun& fun, const Parm& parm)
    : fun_(fun), parm_(parm) 
    {}
    ~ScopeGuardImpl1()
    {
        if (!dismissed_) fun_(parm_);
    }
private:
    Fun fun_;
    const Parm parm_;
};

template <typename Fun, typename Parm>
ScopeGuardImpl1<Fun, Parm>
MakeGuard(const Fun& fun, const Parm& parm)
{
    return ScopeGuardImpl1<Fun, Parm>(fun, parm);
}

typedef const ScopeGuardImplBase& ScopeGuard;

FILE* topSecret = std::fopen("cia.txt");
ScopeGuard closeIt = MakeGuard(std::fclose, topSecret);

ScopeGuardImpl1<int (&)(FILE*), FILE*>

template <typename Fun>
ScopeGuardImpl0<Fun>
MakeGuard(const Fun& fun)
{
    return ScopeGuardImpl0<Fun >(fun);
}
...

ScopeGuard for Objects and Member Functions

template <class Obj, typename MemFun>
class ObjScopeGuardImpl0 : public ScopeGuardImplBase
{
public:
    ObjScopeGuardImpl0(Obj& obj, MemFun memFun)
    : obj_(obj), memFun_(memFun) 
    {}
    ~ObjScopeGuardImpl0()
    {
        if (!dismissed_) (obj_.*fun_)();
    }
private:
    Obj& obj_;
    MemFun memFun_;
};

template <class Obj, typename MemFun>
ObjScopeGuardImpl0<Obj, MemFun, Parm>
MakeObjGuard(Obj& obj, Fun fun)
{
    return ObjScopeGuardImpl0<Obj, MemFun>(obj, fun);
}

ScopeGuard guard = MakeObjGuard(
    friends_, &UserCont::pop_back);

ObjScopeGuardImpl0<UserCont, void (UserCont::*)()>

Error Handling

template <class Obj, typename MemFun>
class ObjScopeGuardImpl0 : public ScopeGuardImplBase
{
    ...
public:
    ~ScopeGuardImpl1()
    {
        if (!dismissed_)
            try { (obj_.*fun_)(); }
            catch(...) {}
    }
}

Supporting Parameters by Reference

void Decrement(int& x) { --x; }
void UseResource(int refCount)
{
    ++refCount;
    ScopeGuard guard = MakeGuard(Decrement, refCount);
    ...
}

template <class T>
class RefHolder
{
    T& ref_;
public:
    RefHolder(T& ref) : ref_(ref) {}
    operator T& () const
    {
        return ref_;
    }
};
template <class T>
inline RefHolder<T> ByRef(T& t)
{
    return RefHolder<T>(t);
}

void Decrement(int& x) { --x; }
void UseResource(int refCount)
{
    ++refCount;
    ScopeGuard guard = MakeGuard(Decrement, ByRef(refCount));
    ...
}

template <typename Fun, typename Parm>
class ScopeGuardImpl1 : public ScopeGuardImplBase
{
    ...
private:
    Fun fun_;
    const Parm parm_;
};

But Wait, There's More

{
    FILE* topSecret = fopen("cia.txt");
    ON_BLOCK_EXIT(std::fclose, topSecret);
    ... use topSecret ...
} // topSecret automagically closed

ON_BLOCK_EXIT says: "I want this action to be performed when the current block exists." Similarly, ON_BLOCK_EXIT_OBJ implements the same feature for a member function call.

These macros use non-orthodox (albeit legal) macro wizardry, which shall go undisclosed. The curious can look them up in the code.

ScopeGuard in the Real World

Maybe the coolest thing about ScopeGuard is its ease of use and conceptual simplicity. This article has detailed the entire implementation, but explaining ScopeGuard's usage only takes a couple of minutes. Amongst our colleagues, ScopeGuard has spread like wildfire. Everybody takes ScopeGuard for granted as a valuable tool that helps in various situations, from premature returns to exceptions. With ScopeGuard, you can finally write exception-safe code with reasonable ease and understand and maintain it just as easily.

Every tool comes with a use recommendation, and ScopeGuard is no exception. You should use ScopeGuard as it was intended — as an automatic variable in functions. You should not hold ScopeGuard objects as member variables, try to put them in vectors, or allocate them on the heap. For these purposes, the downloadable code contains a Janitor class, which does exactly what ScopeGuard does, but in a more general way — at the expense of some efficiency.

Conclusion

We have presented the issues that arise in writing exception-safe code. After discussing a couple of ways of achieving exception safety, we have introduced a generic solution. ScopeGuard uses several generic programming techniques to let you prescribe function and member function calls when a ScopeGuard variable exits a scope. Optionally, you can dismiss the ScopeGuard object.

ScopeGuard is useful when you need to perform automatic cleanup of resources. This idiom is important when you want to assemble an operation out of several atomic operations, each of which could fail.

Acknowledgements

The authors would like to thank to Mihai Antonescu for reviewing this paper and for making useful corrections and suggestions.

Bibliography

[1] Bjarne Stroustrup. The C++ Programming Language, 3rd Edition (Addison Wesley, 1997), page 366.

[2] Herb Sutter. Exceptional C++: 47 Engineering Puzzles, Programming Problems, and Solutions (Addison-Wesley, 2000).

Andrei Alexandrescu is a development manager at RealNetworks Inc. (www.realnetworks.com), based in Seattle, WA. He may be contacted at www.moderncppdesign.com.

Petru Marginean is senior C++ developer for Plural, New York. He can be reached at petrum@hotmail.com.