Re: [boost] Operating System API Error Reporting Guidelines

From: Beman Dawes (bdawes_at_[hidden])
Date: 2006-02-19 11:00:55

"David Abrahams" <dave_at_[hidden]> wrote in message 
news:u1wy1wipv.fsf_at_boost-consulting.com...
> Beman Dawes <bdawes_at_[hidden]> writes:
>
>> Guidelines
>>
>>    Unless  otherwise specified, the default versions of all Boost library
>>    functions, except destructors, that call operating system API 
>> functions
>>    should check for API errors and report the occurrence of such errors 
>> by
>>    throwing an exception of type boost::system_error.
>
> or a class derived therefrom.

Yep, fixed.

>>    Such  functions  should also have an overload that takes an additional
>>    argument of type boost::system_error_code& ec. The behavior of this 
>> overload
>>    is the same as the non-overloaded version, except that it does not 
>> throw an
>>    exception on an API error, and it sets ec to the error code reported 
>> by the
>>    operating system, or to 0 if no error is reported.
>>
>>    For functions where the non-overloaded version returns void, the 
>> overloaded
>>    version returns an object of type boost::system_error_code with the 
>> same
>>    value that ec was set to.
>
> Does it worry you that this will potentially expose an implementation
> detail of the functions (i.e. that they use a system call) which may
> even differ from platform to platform, making code nonportable?

Some libraries (Boost.Filesystem for example) really shouldn't try to hide 
the fact that there is an operating system underneath. Programmers have to 
be defensive when using them because of things like race-conditions with 
other processes.

But with some libraries, yes, use of the OS API is very much an 
implementation detail that shouldn't be exposed. The current draft tries to 
be less dogmatic, and explictly acknowledges that there are cases when the 
guidelines shouldn't be applied. I hope that addresses this concern.

> If we do this, system_error_code should probably be a type that checks
> at runtime that its value has been inspected, and asserts otherwise.

I thought about that quite a bit, and even started to implement such an 
approach for Boost.Filesystem. But then I decided that it was too nannyish 
and also complicated the case where the user very deliberately wishes to 
ignore errors. If someone uses the non-throwing version of a function, that 
is an explicit choice they made and presumably know what they are doing.

(I was burned by being excessively nannyish with native versus portable path 
names; it is sometimes a fine line between trying to protect users from 
themselves and over constraining them.)

Thanks,

--Beman