Exception handling about libosmium

[springmeyer]

My vote: std::runtime_exception all the way unless you need to catch and re throw somewhere specifically inside the library, then a custom exception could be through/caught and re throw for the user as a runtime exception. I think the type of exception is much less important that that all exceptions can be caught as std:exception and that they provide a helpful what().

[joto]

• All exceptions thrown derive from std::exception
• Where applicable exceptions should be or derive from std::runtime_error
• All osmium-specific exceptions are directly in namespace osmium
• Osmium-specific exceptions should be used in cases where targeted catch clauses will probably be used
• All exceptions need to be documented
• All functions throwing exceptions need to document which exceptions they throw

[daniel-j-h]

All functions throwing exceptions need to document which exceptions they throw

Strictly speaking, it would be great to also document exception safety and guarantees we can give and also what we can not guarantee for. For example, where can we provide the strong exception safety guarantee, where is it not possible (or simply not implemented) and what happens in those cases.

This gives a great summary of what this means for the code.

The documentation currently lacks this, making it hard to reason about correctness for simple scenarios like: "what happens if my handler throws", and "what happens if my handler throws and there is a node cache handler in front of it" and "how is the interaction between handlers when one of them throws?" and more. Of course I can read the code and do some tests, but it would be great to document this.

[joto]

I agree. But it is a huge task and we have to keep the documentation in sync with the implementation. So more of a long-term project. :-)

[joto]

This has mostly been done now. If anybody finds cases where exceptions are not used in the right way, open individual issues for it.