Error handling
Error handling follows the C++ Guidline and the philosophy H5CPP library is built around, that is to help you to start without reading much of the documentation, and providing ample of room for more should you require it. The root of exception tree is: h5::error::any
derived from std::runtime_exception
in accordance with C++ guidelines custom exceptions. All HDF5 CAPI calls are considered as resource, and in case of error H5CPP aims to roll back to last known stable state, cleaning up all resource allocations between the call entry and thrown error. This mechanism is guaranteed by RAII.
For granularity io::[file|dataset|attribute]
exceptions provided, with the pattern to capture the entire subset by ::any
. Exceptions thrown with error massages __FILE__ and __LINE__ relevant to H5CPP template library with a brief description to help the developer to investigate. This error reporting mechanism uses a macro found inside h5cpp/config.h and maybe redefined:
An example to capture and handle errors centrally:
Detailed CAPI error stack may be unrolled and dumped, muted, unmuted with provided methods:
h5::mute
- saves current HDF5 CAPI error handler to thread local storage and replaces it with NULL handler, getting rid of all error messages produced by CAPI. CAVEAT: lean and mean, therefore no nested calls are supported. Should you require more sophisticated handler keep reading on.h5::unmute
- restores previously saved error handler, error messages are handled according to previous handler.
usage:
h5::use_errorhandler()
- captures ALL CAPI error messages into thread local storage, replacing current CAPI error handler comes handy when you want to provide details of error happened.
std::stack<std::string> h5::error_stack()
- walks through underlying CAPI error handler
usage:
Design criteria
- All HDF5 CAPI calls are checked with the only exception of
H5Lexsists
where the failure carries information, that the path does not exist yet. - Callbacks of CAPI routines doesn't throw any exceptions, honoring the HDF5 CAPI contract, hence allowing the CAPI call to clean up
- Error messages currently are collected in
H5Eall.hpp
may be customized - Thrown exceptions are hierarchical
- Only RAII capable/wrapped objects used, guaranteed cleanup through stack unrolling
Exception hierarchy is embedded in namespaces, the chart should be interpreted as tree, for instance a file create exception is h5::error::io::file::create
. Keep in mind namespace aliasing allow you customization should you find the long names inconvenient:
h5::error : public std::runtime_error ::any - captures ALL H5CPP runtime errors with the exception of `rollback` ::io:: - namespace: IO related error, see aliasing ::io::any - collective capture of IO errors within this namespace/block recursively ::file:: - namespace: file related errors ::any - captures all exceptions within this namespace/block ::create - create failed ::open - check if the object, in this case file exists at all, retry if networked resource ::close - resource may have been removed since opened ::read - may not be fixed, should software crash crash? ::write - is it read only? is recource still available since opening? ::misc - errors which are not covered otherwise: start investigating from reported file/line ::dataset:: - ::any ::create ::open ::close ::read ::write ::append ::misc ::attribute:: ::any ::create ::open ::close ::read ::write ::misc ::property_list:: ::rollback ::any ::misc ::argument
This is a work in progress, if for any reasons you think it could be improved, or some real life scenario is not represented please shoot me an email with the use case, a brief working example.
Diagnostics
On occasions it comes handy to dump internal state of objects, while currently only h5::sp_t
data-space descriptor and dimensions supported in time most of HDF5 CAPI diagnostics/information calls will be added.
stream operators
Some objects implement operator<<
to furnish you with diagnostics. In time all objects will the functionality added, for now only the following objects:
- h5::current_dims_t
- h5::max_dim_t
- h5::chunk_t
- h5::offset_t
- h5::stride_t
- h5::count_t
- h5::block_t
- h5::dims_t
- h5::dt_t
- h5::pt_t
- h5::sp_t
- h5::