Corosig (properly spelled as [karа́s'ik]) is a crossplatform (currently just POSIX) library for using C++20 coroutines safely after your application crashes. In POSIX systems this means operating inside C library's signal handlers.
In POSIX, signal handlers, which are used to handle crashes, are very restrictive environments. There is not a lot of things one can do safely inside it. There should be no allocations and syscalls which are not marked as signal-safe. Also calls to global objects must be kept to the minimum since they might be invalidated by the moment sighandler is entered.
Most of the time when signal is received it is possible to just set some flag somewhere, exit handler and after that handle occured signal somewhere in main event loop. This aproach is recommended, since it is much easier to follow.
Returning to main loop is not possible if a signal was raised by your implementation due to some horrific state occuring inside your program (such as std::terminate, std::abort, assertion, zero division, etc). If something scary has happened, then you cannot return to the main loop, since there are invalidated objects somewhere. And in most cases you cannot know where, so there is pretty much no one to be trusted. This exact moment you should stay inside sighandler, send any valuable diagnosing data (such as logs) somewhere they can be persisted for further studying.
And as any IO operation, this is faster and fancier when you do it asynchronously.
If you are an xmake user, add that to your project's xmake.lua:
add_repositories("corosig-repo [email protected]:bugsnotabunny/corosig.git v0.1.2")
add_requires("corosig v0.1.2", { external = true })
-- override boost settings and version, if needed
add_requireconfs("corosig.boost", { override = true, version = "1.90.0" })More complete example may be found here
If you are using anything other then xmake, following commands will generate you code for target build system:
xmake config --toolchain=clang --mode=release --tests=n --examples=n --benchmarks=n
xmake project -k (cmake|make|ninja)This project uses doxygen for documenting it's APIs. You can read docs in source code or read an index generated by xmake doxygen command. There is no remote docs index currently
Currently, you have to do this in order to get access to coroutines in SIGFPE handler:
corosig::Fut<void> sighandler(Reactor& r, int sig) noexcept {
// here you can co_await and do any other nasty stuff
}
int main() {
// in bytes, how much stack space can be used
// to allocate coroutine frames here
constexpr auto REACTOR_MEMORY = 8000;
corosig::set_sighandler<REACTOR_MEMORY, sighandler>(SIGFPE);
return 0;
}Maybe somewhere in future there will be windows support based on VEH mechanism. Currently I didn't have enough time for that