1// Copyright Antony Polukhin, 2016-2024.
2//
3// Distributed under the Boost Software License, Version 1.0. (See
4// accompanying file LICENSE_1_0.txt or copy at
5// http://www.boost.org/LICENSE_1_0.txt)
6
7#ifndef BOOST_STACKTRACE_DETAIL_FRAME_DECL_HPP
8#define BOOST_STACKTRACE_DETAIL_FRAME_DECL_HPP
9
10#include <boost/config.hpp>
11#ifdef BOOST_HAS_PRAGMA_ONCE
12# pragma once
13#endif
14
15#include <iosfwd>
16#include <string>
17
18#include <boost/stacktrace/safe_dump_to.hpp> // boost::stacktrace::detail::native_frame_ptr_t
19#include <boost/stacktrace/detail/void_ptr_cast.hpp>
20
21#include <boost/stacktrace/detail/push_options.h>
22
23/// @file boost/stacktrace/detail/frame_decl.hpp
24/// Use <boost/stacktrace/frame.hpp> header instead of this one!
25
26namespace boost { namespace stacktrace {
27
28/// @class boost::stacktrace::frame boost/stacktrace/detail/frame_decl.hpp <boost/stacktrace/frame.hpp>
29/// @brief Class that stores frame/function address and can get information about it at runtime.
30class frame {
31public:
32 typedef boost::stacktrace::detail::native_frame_ptr_t native_frame_ptr_t;
33
34private:
35 /// @cond
36 native_frame_ptr_t addr_;
37 /// @endcond
38
39public:
40 /// @brief Constructs frame that references NULL address.
41 /// Calls to source_file() and source_line() will return empty string.
42 /// Calls to source_line() will return 0.
43 ///
44 /// @b Complexity: O(1).
45 ///
46 /// @b Async-Handler-Safety: Safe.
47 /// @throws Nothing.
48 constexpr frame() noexcept
49 : addr_(0)
50 {}
51
52#ifdef BOOST_STACKTRACE_DOXYGEN_INVOKED
53 /// @brief Copy constructs frame.
54 ///
55 /// @b Complexity: O(1).
56 ///
57 /// @b Async-Handler-Safety: Safe.
58 /// @throws Nothing.
59 constexpr frame(const frame&) = default;
60
61 /// @brief Copy assigns frame.
62 ///
63 /// @b Complexity: O(1).
64 ///
65 /// @b Async-Handler-Safety: Safe.
66 /// @throws Nothing.
67 constexpr frame& operator=(const frame&) = default;
68#endif
69
70 /// @brief Constructs frame that references addr and could later generate information about that address using platform specific features.
71 ///
72 /// @b Complexity: O(1).
73 ///
74 /// @b Async-Handler-Safety: Safe.
75 /// @throws Nothing.
76 constexpr explicit frame(native_frame_ptr_t addr) noexcept
77 : addr_(addr)
78 {}
79
80 /// @brief Constructs frame that references function_addr and could later generate information about that function using platform specific features.
81 ///
82 /// @b Complexity: O(1).
83 ///
84 /// @b Async-Handler-Safety: Safe.
85 /// @throws Nothing.
86 template <class T>
87 explicit frame(T* function_addr) noexcept
88 : addr_(boost::stacktrace::detail::void_ptr_cast<native_frame_ptr_t>(function_addr))
89 {}
90
91 /// @returns Name of the frame (function name in a human readable form).
92 ///
93 /// @b Complexity: unknown (lots of platform specific work).
94 ///
95 /// @b Async-Handler-Safety: Unsafe.
96 /// @throws std::bad_alloc if not enough memory to construct resulting string.
97 BOOST_STACKTRACE_FUNCTION std::string name() const;
98
99 /// @returns Address of the frame function.
100 ///
101 /// @b Complexity: O(1).
102 ///
103 /// @b Async-Handler-Safety: Safe.
104 /// @throws Nothing.
105 constexpr native_frame_ptr_t address() const noexcept {
106 return addr_;
107 }
108
109 /// @returns Path to the source file, were the function of the frame is defined. Returns empty string
110 /// if this->source_line() == 0.
111 /// @throws std::bad_alloc if not enough memory to construct resulting string.
112 ///
113 /// @b Complexity: unknown (lots of platform specific work).
114 ///
115 /// @b Async-Handler-Safety: Unsafe.
116 BOOST_STACKTRACE_FUNCTION std::string source_file() const;
117
118 /// @returns Code line in the source file, were the function of the frame is defined.
119 /// @throws std::bad_alloc if not enough memory to construct string for internal needs.
120 ///
121 /// @b Complexity: unknown (lots of platform specific work).
122 ///
123 /// @b Async-Handler-Safety: Unsafe.
124 BOOST_STACKTRACE_FUNCTION std::size_t source_line() const;
125
126 /// @brief Checks that frame is not references NULL address.
127 /// @returns `true` if `this->address() != 0`
128 ///
129 /// @b Complexity: O(1)
130 ///
131 /// @b Async-Handler-Safety: Safe.
132 constexpr explicit operator bool () const noexcept { return !empty(); }
133
134 /// @brief Checks that frame references NULL address.
135 /// @returns `true` if `this->address() == 0`
136 ///
137 /// @b Complexity: O(1)
138 ///
139 /// @b Async-Handler-Safety: Safe.
140 constexpr bool empty() const noexcept { return !address(); }
141};
142
143
144namespace detail {
145 BOOST_STACKTRACE_FUNCTION std::string to_string(const frame* frames, std::size_t size);
146} // namespace detail
147
148}} // namespace boost::stacktrace
149
150
151#include <boost/stacktrace/detail/pop_options.h>
152
153#endif // BOOST_STACKTRACE_DETAIL_FRAME_DECL_HPP
154

source code of boost/libs/stacktrace/include/boost/stacktrace/detail/frame_decl.hpp