[boost] Re: Exception safety guarantie

From: David B. Held (dheld_at_[hidden])
Date: 2004-07-18 00:27:17

David Abrahams wrote:
> [...]
> It might be best to describe what it means to say "has no effects"
 > in one place.  Maybe I should put a section in
> http://www.boost.org/more/error_handling.html that discusses these
> conventions for documenting exception-safety.  Then library
> documentation can link to that part of the page.  It would say
> something like:
> 
> - Unless otherwise specified, all Boost library operations give the
>   /basic guarantee/: the library's maintains its invariants and does
 >   not leak resources in the face of exceptions.

I would just make the editorial fixes as so:

     ...the library maintains its invariants...

> - Some library operations give the /strong guarantee/ that if an
>   exception is thrown, there are no effects.  If those operations
>   involve calls to user-supplied operations (such as copying an
>   instance of a template type parameter) and those operations have
>   side-effects, it's understood that those side-effects are outside
>   the control of the library and not included in the strong guarantee.

Looks good.

> - ...anything else...?
> 
> Then I would probably add a section that showed some examples of the
> kind of language used to document exception-safety, and describe how
> to understand it.
> 
> Thoughts?

I think it's a good idea overall, and perhaps some older libraries that
don't document exception safety should revisit the issue.  The library
requirements page mentions "Discussion of error detection and recovery
strategy", but doesn't require any particular section to be in the
documentation.  Perhaps we should require that libraries that offer
something other than the basic guarantee include an exception safety
section in the docs.

Dave