stacktrace/detail/frame_decl.hpp

0001 // Copyright Antony Polukhin, 2016-2023.
0002 //
0003 // Distributed under the Boost Software License, Version 1.0. (See
0004 // accompanying file LICENSE_1_0.txt or copy at
0005 // http://www.boost.org/LICENSE_1_0.txt)
0006
0007 #ifndef BOOST_STACKTRACE_DETAIL_FRAME_DECL_HPP
0008 #define BOOST_STACKTRACE_DETAIL_FRAME_DECL_HPP
0009
0010 #include <boost/config.hpp>
0011 #ifdef BOOST_HAS_PRAGMA_ONCE
0012 #   pragma once
0013 #endif
0014
0015 #include <iosfwd>
0016 #include <string>
0017
0018 #include <boost/stacktrace/safe_dump_to.hpp> // boost::stacktrace::detail::native_frame_ptr_t
0019 #include <boost/stacktrace/detail/void_ptr_cast.hpp>
0020
0021 #include <boost/stacktrace/detail/push_options.h>
0022
0023 /// @file boost/stacktrace/detail/frame_decl.hpp
0024 /// Use <boost/stacktrace/frame.hpp> header instead of this one!
0025
0026 namespace boost { namespace stacktrace {
0027
0028 /// @class boost::stacktrace::frame boost/stacktrace/detail/frame_decl.hpp <boost/stacktrace/frame.hpp>
0029 /// @brief Class that stores frame/function address and can get information about it at runtime.
0030 class frame {
0031 public:
0032     typedef boost::stacktrace::detail::native_frame_ptr_t native_frame_ptr_t;
0033
0034 private:
0035     /// @cond
0036     native_frame_ptr_t addr_;
0037     /// @endcond
0038
0039 public:
0040     /// @brief Constructs frame that references NULL address.
0041     /// Calls to source_file() and source_line() will return empty string.
0042     /// Calls to source_line() will return 0.
0043     ///
0044     /// @b Complexity: O(1).
0045     ///
0046     /// @b Async-Handler-Safety: Safe.
0047     /// @throws Nothing.
0048     constexpr frame() noexcept
0049         : addr_(0)
0050     {}
0051
0052 #ifdef BOOST_STACKTRACE_DOXYGEN_INVOKED
0053     /// @brief Copy constructs frame.
0054     ///
0055     /// @b Complexity: O(1).
0056     ///
0057     /// @b Async-Handler-Safety: Safe.
0058     /// @throws Nothing.
0059     constexpr frame(const frame&) = default;
0060
0061     /// @brief Copy assigns frame.
0062     ///
0063     /// @b Complexity: O(1).
0064     ///
0065     /// @b Async-Handler-Safety: Safe.
0066     /// @throws Nothing.
0067     constexpr frame& operator=(const frame&) = default;
0068 #endif
0069
0070     /// @brief Constructs frame that references addr and could later generate information about that address using platform specific features.
0071     ///
0072     /// @b Complexity: O(1).
0073     ///
0074     /// @b Async-Handler-Safety: Safe.
0075     /// @throws Nothing.
0076     constexpr explicit frame(native_frame_ptr_t addr) noexcept
0077         : addr_(addr)
0078     {}
0079
0080     /// @brief Constructs frame that references function_addr and could later generate information about that function using platform specific features.
0081     ///
0082     /// @b Complexity: O(1).
0083     ///
0084     /// @b Async-Handler-Safety: Safe.
0085     /// @throws Nothing.
0086     template <class T>
0087     explicit frame(T* function_addr) noexcept
0088         : addr_(boost::stacktrace::detail::void_ptr_cast<native_frame_ptr_t>(function_addr))
0089     {}
0090
0091     /// @returns Name of the frame (function name in a human readable form).
0092     ///
0093     /// @b Complexity: unknown (lots of platform specific work).
0094     ///
0095     /// @b Async-Handler-Safety: Unsafe.
0096     /// @throws std::bad_alloc if not enough memory to construct resulting string.
0097     BOOST_STACKTRACE_FUNCTION std::string name() const;
0098
0099     /// @returns Address of the frame function.
0100     ///
0101     /// @b Complexity: O(1).
0102     ///
0103     /// @b Async-Handler-Safety: Safe.
0104     /// @throws Nothing.
0105     constexpr native_frame_ptr_t address() const noexcept {
0106         return addr_;
0107     }
0108
0109     /// @returns Path to the source file, were the function of the frame is defined. Returns empty string
0110     /// if this->source_line() == 0.
0111     /// @throws std::bad_alloc if not enough memory to construct resulting string.
0112     ///
0113     /// @b Complexity: unknown (lots of platform specific work).
0114     ///
0115     /// @b Async-Handler-Safety: Unsafe.
0116     BOOST_STACKTRACE_FUNCTION std::string source_file() const;
0117
0118     /// @returns Code line in the source file, were the function of the frame is defined.
0119     /// @throws std::bad_alloc if not enough memory to construct string for internal needs.
0120     ///
0121     /// @b Complexity: unknown (lots of platform specific work).
0122     ///
0123     /// @b Async-Handler-Safety: Unsafe.
0124     BOOST_STACKTRACE_FUNCTION std::size_t source_line() const;
0125
0126     /// @brief Checks that frame is not references NULL address.
0127     /// @returns `true` if `this->address() != 0`
0128     ///
0129     /// @b Complexity: O(1)
0130     ///
0131     /// @b Async-Handler-Safety: Safe.
0132     constexpr explicit operator bool () const noexcept { return !empty(); }
0133
0134     /// @brief Checks that frame references NULL address.
0135     /// @returns `true` if `this->address() == 0`
0136     ///
0137     /// @b Complexity: O(1)
0138     ///
0139     /// @b Async-Handler-Safety: Safe.
0140     constexpr bool empty() const noexcept { return !address(); }
0141 };
0142
0143
0144 namespace detail {
0145     BOOST_STACKTRACE_FUNCTION std::string to_string(const frame* frames, std::size_t size);
0146 } // namespace detail
0147
0148 }} // namespace boost::stacktrace
0149
0150
0151 #include <boost/stacktrace/detail/pop_options.h>
0152
0153 #endif // BOOST_STACKTRACE_DETAIL_FRAME_DECL_HPP