[boost::serialization] Document the use of boost::serialization::throw_exception()

[adishavit@…]

The boost::serialization library provides the boost::serialization::throw_exception() function to allow throwing exceptions from serialization code. This is apparently not documented anywhere. Unless this is a strictly internal function, it should be documented as it is very helpful in many custom class de-serialization situations.

[Robert Ramey]

boost::serialization::throw_exception() is part of somewhat tottered history.

a) originally it was boost::throw_exception(). This was designed to funnel all exceptions through a central point so that the could be handled in accordance with the available support for exceptions. That is boost::throw_exception() would be defined to use throw if the system supported while it might be defined as something else if the system didn't support exceptions - or if the developer using the library didn't want to support exceptions.

b) Along came the boost exception library to improve support for exceptions in application. It was subjected to the boost review process and was accepted on the basis if two (I think) positive reviews. It was then upload into the boost development tree.

c) Part of boost exception was to redefine boost::throw_exception for a purpose totally different than the original one. Now it added the facilities to any library which had previously had depended upon boost::throw_exception. This added a whole bunch of templated code where non had existed before and (temporarily) broke a bunch of library code. As this occurred "under the radar" it was really annoying. It also meant that one's library (serialization) had a whole new dependency and included a bunch of code which the library itself never used.

d) In spite of objections raised by a number of library authors, the changes were not rolled back. Our only choice was to re-implement boost::throw_exception as (in my case boost::serialization::throw exception). Which is what I did.

So that is how we came the stuck with this problem.

In your case, you can use any thing you want to throw an exception and it will work fine.

If you want to prepare text to document all of the above to include in the documentation, I would consider adding it to the documentation. Meanwhile I'm going to close this ticket.

Thanks for your interest.

Robert Ramey