Document number: N2809=08-0319
Project: Programming Language C++, Library Working Group
Reply-to: Beman Dawes <bdawes at acm.org>
This proposal provides standard library clause 17 support for functions that allow
users to choose whether errors should be reported via exception or via
The impact is to ensure that a function specified like this:
void f(error_code& ec=unspecified-name);
acts as if it had been specified like this:
void f(); // throws on error void f(error_code& ec); // never throws
The benefit of a single signature providing both throwing and error reporting semantics is that it eliminates a doubling of the number of signatures. This is particularly beneficial where a function already has an uncomfortably large number of overloads. The intent is that this defaulted argument approach be applied uniformly throughout the standard library because it is less confusing if all hybrid error handling interfaces are consistent.
The proposal makes no change to any current standard library components. It just adds a sub-section to clause 17 specifying the semantics implied by an argument specified as error_code& ec=unspecified-name.
The original plan was to hold this proposal for TR2, where libraries like filesystem will make extensive use of this error handling idiom. A C++0x use (LWG issue 935, clock error handling needs to be specified) has now arisen, so it may be desirable to add it for C++0x.
Each of the three clocks specified in 20.9.5 Clocks [time.clock] provides the member function:
static time_point now();
The semantics are specified by 20.9.1 Clock requirements [time.clock.req], which as of CD1 makes no mention of error handling. Thus the function may throw bad_alloc or an implementation-defined exception (see [res.on.exception.handling] paragraph 4). Since the function is sometimes used in cases where exceptions are not appropriate or where the specifics of the exception or cause of error need to be available to the user, further options are needed.
Indeed, this is an example of a class of errors where use cases require that three possible semantic actions be supported:
system_erroror of a type derived from
This is the most appropriate default behavior, since it covers the very common use case where errors are not expected and the user does not wish to or have the knowledge to code anything dealing with error handling. Because the exception hierarchy is specified to derive from system_error, information about the cause of an error is provided should an exception occur.
This semantic action needs to be provided by
now()because it is often used in cases where errors are truly exceptional and if they do occur are best handled further up the call chain. Thus this option does need to be available for clock users and is the appropriate default.
This allows users to process errors, including details, yet does not incur the runtime and code complexity cost of try/catch blocks. Without this option, users report code becomes so littered with try/catch blocks that it is unreadable and unmaintainable.
For clocks, this option is particularly attractive for code that must be robust across a wide variety of platforms, including embedded and legacy systems.
This is just a subset of reporting via error_code object; the object is simply ignored. It is particularly appropriate in destructors.
now()is often used in destructors, so having this semantic action makes life simpler for clock users.
The proposed wording gives the user the choice of these three semantic
actions on an error, yet does not require a doubling or tripling of the number
of function signatures that must be specified in the standard or in actual
interfaces. Applying this to the
clock example, the
now function specification becomes:
static time_point now(error_code& ec=unspecified-name);
Implementations are permitted to actually implement this as one or two signatures.
The requisite extern was added to Boost at release 1.37.0. The idiom had been in more limited use approximately six months and is the outgrowth of several years of experience with predecessor idioms.
After 126.96.36.199 Value of error codes [value.error.codes], add a new subsection:
188.8.131.52 Semantics of
Certain standard library functions are specified as having an argument of
unspecified-nameshall be a name reserved for the implementation ([reserved.names]). [Note:
unspecified-nameserves only to denote a request for the default error handling behavior. --end note]
Such functions shall behave as if specified as two separate signatures:
A function signature without an
error_code&argument. If an error occurs, this function shall throw an exception of type
system_error, or of a type derived from
system_error, whose code() member function shall identify the reason for the error.
A function signature with an
error_code& ecargument. This function shall not throw exceptions. If an error occurs, this function shall have an implicit postcondition that ec.value()and ec.category() identify the reason for the error. If an error does not occur, this functions shall have an implicit postcondition that !ec is true. Unless specified, the return value if an error occurs is unspecified.
Whether or not implementations actually replace a single signature with a defaulted
error_code& ecargument with two signatures without defaulted
error_code& ecarguments is unspecified.
Howard Hinnant suggested use of an unspecified name rather than a specific name to denote the default case, and provided other helpful suggestions and comments that have been incorporated into this proposal.
Revised December 05, 2008
© Copyright Beman Dawes, 2008
Distributed under the Boost Software License, Version 1.0. (See file LICENSE_1_0.txt or www.boost.org/LICENSE_1_0.txt)