https://github.com/gpmueller/trace

An exception backtracing library
https://github.com/gpmueller/trace

backtrace cpp17 exceptions

Last synced: 8 months ago
JSON representation

An exception backtracing library

• Host: GitHub
• URL: https://github.com/gpmueller/trace
• Owner: GPMueller
• License: mit
• Created: 2019-12-15T17:20:02.000Z (about 6 years ago)
• Default Branch: master
• Last Pushed: 2022-04-04T10:48:11.000Z (almost 4 years ago)
• Last Synced: 2025-04-24T02:42:02.076Z (10 months ago)
• Topics: backtrace, cpp17, exceptions
• Language: C++
• Homepage:
• Size: 144 KB
• Stars: 11
• Watchers: 2
• Forks: 4
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
trace - portable exception backtracing in C++17

====================================================================

[![CI](https://github.com/GPMueller/trace/workflows/CI/badge.svg)](https://github.com/GPMueller/trace/actions)

[![Coverage](https://codecov.io/gh/GPMueller/trace/branch/master/graph/badge.svg)](https://codecov.io/gh/GPMueller/trace)

This library uses

[`std::nested_exception`](http://en.cppreference.com/w/cpp/error/nested_exception)

and

[`std::throw_with_nested`](http://en.cppreference.com/w/cpp/error/throw_with_nested)

and can be applied in order to not lose information while propagating an original

[`std::exception`](https://en.cppreference.com/w/cpp/error/exception)

upwards through a chain of function calls and create a **backtrace** without any

overhead (compare e.g. logging of debug messages). This avoids much of the need for any

debugging and provides a way of ensuring that a library does not crash ungracefully.

Usage

--------------------------------------------------------------------

```C++

#include 

```

The library revolves around three macros

- `trace::initiate`: can be placed anywhere. Takes a `std::string message` and initiates

  a trace with information about the corresponding function and source file. This is done

  by throwing an exception.

- `trace::propagate`: should be placed in a catch-block. Takes a `std::string message`,

  attaches it to the trace and propagates the trace up the function call stack by

  rethrowing a nested exception

- `trace::handle`: should be placed in a catch-block. Takes a `std::exception &` and

  unwraps it to creates a backtrace

and the function `trace::latest()`, which returns the most recent backtrace, created by

the call to `handle`.