[boost] Re: Exception safety guarantie

From: David Abrahams (dave_at_[hidden])
Date: 2004-07-17 07:31:07

"David B. Held" <dheld_at_[hidden]> writes:

> David Abrahams wrote:
>> [...]
>> Further, I'm not sure it usually makes sense to use "pure" when
>> describing constraints on user-supplied operations.  It stands to
>> reason that in general, the library has no knowledge of external state
>> that might be modified by a user-supplied operation and can't roll
>> back the results.  It's often a reasonable shorthand to say "gives the
>> strong guarantee" when you mean "gives the strong guarantee as long
>> as the user-supplied operation is pure".
>
> But what is the user-supplied operation, and how does the user know
> she has supplied it?  

There's no mystery.  The algorithm spells out its requirements on its
type arguments.  Part of those requirements has to include the
operations that the algorithm will perform on those arguments.

> In this case, it's the default c'tor for the Sequence, but the
> function is not documented as taking that as a user-spplied
> operation.  

The function had better darned well document that it requires
Sequence to satisfy certain concept requirements that include
default-constructibility (and maybe push_back or whatever the
operation needs).

> Thus, it seems worthwhile to tell the user which operations must be
> pure in order to get the strong guarantee.  Will that constrain
> implementations?  Maybe.  But safety isn't free.  The only
> alternative I see is to not even attempt to offer the strong
> guarantee.

No, you just follow the established practice for documenting
exception-safety in generic functions.  There's no need to reinvent
the wheel.

I think purity is a useful idea for analyzing exception safety, and I
have no objection to mentioning it in specifications _if_ it truly
adds clarity.  If the specification can be considered minimal and
complete without mentioning purity, that might be better.

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.

- 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.

- ...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?

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com