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
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
> 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
No, you just follow the established practice for documenting
exception-safety in generic functions. There's no need to reinvent
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
- 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.
-- Dave Abrahams Boost Consulting http://www.boost-consulting.com
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk