From 8768a721b10b386690c6a28d3692380844f7ea8a Mon Sep 17 00:00:00 2001 From: Antony Polukhin Date: Wed, 26 Oct 2016 22:23:09 +0300 Subject: [PATCH] Doxyden output improved, improved docs and added more examples --- doc/Jamfile.v2 | 5 ++-- doc/stacktrace.qbk | 25 ++++++++++++---- example/getting_started.cpp | 55 ++++++++++++++++++++++++++++++++++++ include/boost/stacktrace.hpp | 6 ++-- 4 files changed, 81 insertions(+), 10 deletions(-) diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index 36b616b..d9e009a 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -18,8 +18,9 @@ doxygen autodoc EXPAND_ONLY_PREDEF=YES MACRO_EXPANSION=YES "PREDEFINED=\"stl_type_info=std::type_info\" \\ - \"BOOST_EXPLICIT_OPERATOR_BOOL_NOEXCEPT()=explicit operator bool() noexcept;\" \\ - \"BOOST_STACKTRACE_FUNCTION\"" + \"BOOST_EXPLICIT_OPERATOR_BOOL_NOEXCEPT()=explicit operator bool() const noexcept;\" \\ + \"BOOST_STACKTRACE_FUNCTION\" \\ + \"BOOST_STACKTRACE_DOXYGEN_INVOKED\"" "boost.doxygen.reftitle=Boost.Stacktrace Header Reference" ; diff --git a/doc/stacktrace.qbk b/doc/stacktrace.qbk index 0a24dbd..afee2a8 100644 --- a/doc/stacktrace.qbk +++ b/doc/stacktrace.qbk @@ -194,6 +194,21 @@ See [link boost_stacktrace.build_macros_and_backends section "Build, Macros and [endsect] +[section Saving stacktraces by specified format] + +[classref boost::stacktrace::stacktrace] provides access to individual [classref boost::stacktrace::stacktrace::frame_view frames] of the stacktrace, +so that you could save stacktrace information in your own format. Consider the example, that saves only function addresses of each frame: + +[getting_started_trace_addresses] + +Code from above will output: + +``` +0x401a25,0x401a25,0x401a25,0x401a25,0x401a25,0x401a25,0x4019cb,0x401a7f,0x7f9da8a46e50,0x4013e0,0, +``` + +[endsect] + [endsect] [section Build, Macros and Backends] @@ -203,11 +218,11 @@ By default Boost.Stacktrace is a header-only library and it attempts to detect t You can define the following macros to explicitly specify backend that you're willing to use in header-only mode (those macros have no effect if defined *BOOST_STACKTRACE_LINK* or *BOOST_STACKTRACE_DYN_LINK*): [table:configbackend Header only backend specifications - [[Macro name] [Effect] [Platforms] [Uses debug information [footnote This will provide more readable backtraces if the binary is built with debug information.]] [Uses dynamic exports information [footnote This will provide readable function names in backtrace for functions that are exported by the binary.]]] - [[*BOOST_STACKTRACE_USE_LIBUNWIND*] [Use libunwind tracing backend. This is the best known backend for POSIX systems that requires linking with libunwind library.] [POSIX] [yes] [yes]] - [[*BOOST_STACKTRACE_USE_WINDBG*] [Use Windows specific tracing backend that uses DbgHelp. This is the best and only known backend for Windows platform that requires linking with DbgHelp library.] [Windows] [yes] [yes]] - [[*BOOST_STACKTRACE_USE_BACKTRACE*] [Use tracing backend that calls POSIX function backtrace. This is a fallback backend for POSIX platforms that requires linking with libdl library.] [POSIX] [no] [yes]] - [[*BOOST_STACKTRACE_USE_NOOP*] [Use noop tracing backend that does nothing. Use this backend if you wish to disable backtracing.] [POSIX and Windows] [no] [no]] + [[Macro name] [Effect] [Platforms] [Uses debug information [footnote This will provide more readable backtraces if the binary is built with debug information.]] [Uses dynamic exports information [footnote This will provide readable function names in backtrace for functions that are exported by the binary.]] [Construction speed]] + [[*BOOST_STACKTRACE_USE_LIBUNWIND*] [Use libunwind tracing backend. This is the best known backend for POSIX systems that requires linking with libunwind library.] [POSIX] [yes] [yes] [slow]] + [[*BOOST_STACKTRACE_USE_WINDBG*] [Use Windows specific tracing backend that uses DbgHelp. This is the best and only known backend for Windows platform that requires linking with DbgHelp library.] [Windows] [yes] [yes] [fast]] + [[*BOOST_STACKTRACE_USE_BACKTRACE*] [Use tracing backend that calls POSIX function backtrace. This is a fallback backend for POSIX platforms that requires linking with libdl library.] [POSIX] [no] [yes] [fast]] + [[*BOOST_STACKTRACE_USE_NOOP*] [Use noop tracing backend that does nothing. Use this backend if you wish to disable backtracing.] [POSIX and Windows] [no] [no] [noop]] ] diff --git a/example/getting_started.cpp b/example/getting_started.cpp index da2296a..47a134e 100644 --- a/example/getting_started.cpp +++ b/example/getting_started.cpp @@ -111,14 +111,69 @@ void setup_handlers() { //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// +// outputs: 0x401a25,0x401a25,0x401a25,0x401a25,0x401a25,0x401a25,0x4019cb,0x401a7f,0x7f9da8a46e50,0x4013e0,0, + +#ifdef BOOST_NO_CXX11_RANGE_BASED_FOR +#include +#include // std::cout + +namespace bs = boost::stacktrace; +void dump_compact(const bs::stacktrace& st) { + for (unsigned i = 0; i < st.size(); ++i) { + bs::stacktrace::frame_view frame = st[i]; + std::cout << frame.address() << ','; + } + + std::cout << std::endl; +} +#else +//[getting_started_trace_addresses +#include +#include // std::cout + +namespace bs = boost::stacktrace; +void dump_compact(const bs::stacktrace& st) { + for (bs::stacktrace::frame_view frame: st) { + std::cout << frame.address() << ','; + } + + std::cout << std::endl; +} +//] +#endif + +BOOST_NOINLINE boost::stacktrace::stacktrace rec1(int i); +BOOST_NOINLINE boost::stacktrace::stacktrace rec2(int i); + +BOOST_NOINLINE boost::stacktrace::stacktrace rec1(int i) { + if (i < 5) { + if (!i) return boost::stacktrace::stacktrace(); + return rec2(--i); + } + + return rec2(i - 2); +} + +BOOST_NOINLINE boost::stacktrace::stacktrace rec2(int i) { + if (i < 5) { + if (!i) return boost::stacktrace::stacktrace(); + return rec2(--i); + } + + return rec2(i - 2); +} + + #include int main() { + dump_compact(rec1(8)); setup_handlers(); BOOST_TRY { foo(5); // testing assert handler } BOOST_CATCH(...) { } BOOST_CATCH_END + } diff --git a/include/boost/stacktrace.hpp b/include/boost/stacktrace.hpp index 85b9ec0..594ddc9 100644 --- a/include/boost/stacktrace.hpp +++ b/include/boost/stacktrace.hpp @@ -107,7 +107,7 @@ public: #endif class frame_view { - /// @cond + /// @cond const stacktrace* impl_; std::size_t frame_no_; @@ -117,7 +117,7 @@ public: {} friend class ::boost::stacktrace::stacktrace::iterator; - /// @endcond + /// @endcond public: /// @returns Name of the frame (function name in a human readable form). @@ -147,7 +147,7 @@ public: }; /// @cond - class iterator : public boost::iterator_facade< + class iterator: public boost::iterator_facade< iterator, frame_view, boost::random_access_traversal_tag,