Cpp Coding Standards/ERR/Safe

Function Safety Guarantees (ERR:Safe)

Summary

Provide the strongest error-safety guarantee for each function that does not punish callers who do not need it. The basic guarantee is always necessary.

Explanation

The three guarantees are:

Basic Guarantee

Errors leave the program at least in a valid state. Classes's invariants are kept, there are no memory leaks, etc. Further details of this state may however not be predictable.

Strong Guarantee

This is like a transaction. After the function call, the program either has the intended state (as it should be after the function call) or the same state as before the function was called.

No-fail Guarantee

The function can not fail.

The rule is: Every function has to provide at least the basic guarantee.

How to document the guarantees

For a free function or a non-const member function, the basic guarantee is the default. If it provides a stronger guarantee, mention this in the documentation. (Use the documentation tag "@onerror".)

For a const-member function, the no-fail guarantee is the default. It has to be documented, if its guarantee is weaker, but it also has to be at least the basic guarantee.

See also

ERR:NoFail - which functions never fail

References

For the three kinds of guarantee:

• D. Abrahams: "Exception Safety in STLPort" (STLPort website, 1996)
• Bjaarne Stroustrup: "The C++ Programming Language (Special 3rd Edition)" (Addison Wesley, 2000)