https://github.com/adishavit/mittens
Because somebody has to catch the hot potato!
https://github.com/adishavit/mittens
Last synced: 4 months ago
JSON representation
Because somebody has to catch the hot potato!
- Host: GitHub
- URL: https://github.com/adishavit/mittens
- Owner: adishavit
- License: bsd-3-clause
- Created: 2016-05-15T21:26:19.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2016-05-22T06:41:09.000Z (about 10 years ago)
- Last Synced: 2025-06-06T11:05:44.367Z (about 1 year ago)
- Language: C++
- Homepage:
- Size: 44.9 KB
- Stars: 18
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
 Mittens
=======
Mittens is a cross-platform, C++ header-only library for centralized handling of exceptions, particularly along module boundaries.
Robust software needs to be able to handle exceptions as gracefully as possible. This might include last-minute error logging, alternate notification mechanisms (e.g. via the JVM) etc.
An unexpected exit out of `main()` or an exception escaping from a DLL, COM or JNI function call can cause severe havoc. Module boundaries are stress-points where escaped exceptions should be firmly handled. Dynamically linked libraries (DLLs) export multiple C-like functions forming the dynamic module boundaries. Here, in particular, we would like a uniform and consistent way of handling exceptions. This often requires a lot of copy-paste code since try-catch statements do not naturally compose nor can they be easily encapsulated.
Mittens is a generic header-only library that allows `try-catch` statement composition, ordering and nesting with customizable actions per exception type. These composite exception handlers can be defined once and reused multiple times where needed.
 Overview
-----
#### Features
- Centralized, uniform, maintainable, consistent and composable exception handling;
- Support both portable cross-platform and platform-specific code;
- Write robust, well ordered, exception-type-specific custom code;
- Particularly useful along module boundaries: e.g command-line applications and dynamically loaded libraries (DLLs, shared-object `.so`, Android JNI, etc.)
#### TL;DR: Show Me the Code!
```cpp
#include "common_handlers.hpp"
auto handleIt = mittens::all_catcher (-1, []() { std::cerr << "Caught exception of unknown type!" << std::endl; },
mittens::std_exception_handler (-2, [](auto& e){ std::cerr << "Caught std::exception: " << e.what() << std::endl; },
mittens::generic_handler(-3, [](auto& e){ std::cerr << "Caught thrown `int` = " << e << std::endl; })));
int main() try
{
throw std::runtime_error("Goodbye World, Hello Mittens!");
return EXIT_SUCCESS;
}
catch (...)
{ return handleIt(); }
```
Application prints: `Caught std::exception: Goodbye World, Hello Mittens!` and the app return value will be `-2`.
**See the [Tutorial](https://github.com/adishavit/mittens/wiki/The-Mittens-Tutorial) for more.**
#### Integration
- Single header file `generic_exception_handler.hpp` + optional helper header (`common_handlers.hpp`).
- Cross platform: Windows, Linux OSX;
- No external dependencies (but unit tests use Boost.Test);
- BSD License
#### Epilogue
- Mittens grew out of the need to robustly and consistently handle exceptions across module boundaries in Windows DLLs and Android JNIs.
- The first version was written in 2013. This repo is a complete rewrite to allow for much more genericity.
- Although the design is very different, Mittens was originally inspired by Matthew Wilson's Quality Matters articles ([QM#6](http://accu.org/index.php/journals/1706), [QM#7](http://accu.org/index.php/articles/1868)).
- Check out the `examples` folder for more examples of how Mittens can help you and more advanced usage.
- Comments, discussions, questions, ideas and PRs are most welcome!