You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
More polishings for the paper:
1. Update date;
2. Fix typo in section "III. Design decisions";
3. Add synopsis to "Header stacktrace" subsection;
4. Add more constexpr for the God of constexpr;
5. Fix typos in comments in header synopsis;
6. Change wording in brief functions descriptions.
<!--p class='notes'>Green lines are notes for the <b>editor</b> or for the <b>SG14</b> that must not be treated as part of the wording.</p-->
@@ -65,12 +65,45 @@ <h2>II. Impact on the Standard</h2>
65
65
<h2>III. Design Decisions</h2>
66
66
<p>The design is based on the Boost.Stacktrace library, a popular library that does not depend on any non-standard library components.</p>
67
67
<p><b>Note about signal safety:</b> this proposal does not attempt to provide a signal-safe solution for capturing and decoding stacktraces.
68
-
Such functionality currently is not implementable on some of the popular platforms. However, the paper attempts to provide extendable solution, that may be made sygnal safe some day.</p>
68
+
Such functionality currently is not implementable on some of the popular platforms. However, the paper attempts to provide extendable solution, that may be made signal safe some day.</p>
69
69
<p><b>Note on performance:</b> during Boost.Stacktrace development phase many users requested a fast way to store stack trace, without decoding the function names. This functionality is preserved in the paper.</p>
70
70
71
71
72
72
<h2>IV. Proposed Interface</h2>
73
-
<h3>Header <stacktrace></h3>
73
+
<h3>Header <stacktrace> synopsis</h3>
74
+
<pre>
75
+
namespace std {
76
+
77
+
class stack_frame;
78
+
79
+
template<typename Allocator>
80
+
class basic_stacktrace;
81
+
82
+
// free functions
83
+
84
+
// This is the alias to use unless you'd like to provide a specific allocator to basic_stacktrace.
85
+
using stacktrace = basic_stacktrace<allocator<stack_frame>>;
86
+
87
+
// Outputs stacktrace in a human readable format to output stream.
// functions that querying information about stored address
94
127
string name() const;
95
128
string source_file() const;
96
129
size_t source_line() const;
97
130
98
131
private:
99
-
native_frame_ptr_t data; // exposiotion only
132
+
native_frame_ptr_t data; // exposition only
100
133
};
134
+
}
135
+
</pre>
136
+
137
+
138
+
<h3><code>stack_frame</code> constructors</h3>
139
+
<pre>stack_frame() noexcept;</pre>
140
+
<divclass="desc">Constructs stack_frame that references nullptr address. Calls to <code>source_file()</code> and <code>source_line()</code> will return empty string. Calls to <code>source_line()</code> will return 0.</div>
<divclass="desc">Constructs stack_frame that references addr and could later generate information about that address using platform specific features.</div>
145
+
146
+
147
+
<h3><code>stack_frame</code> member functions</h3>
148
+
<pre>std::string name() const;</pre>
149
+
<divclass="desc">Returns empty string or platform specific name of the function that the stored address is pointing to. Throws std::bad_alloc if not enough memory to construct resulting string.</div>
<divclass="desc">Returns address stored by this.</div>
153
+
154
+
<pre>std::string source_file() const;</pre>
155
+
<divclass="desc">Returns empty string or path to the source file, where the function of the frame is defined. Returns empty string if this->source_line() == 0. Throws std::bad_alloc if not enough memory to construct resulting string.</div>
101
156
157
+
<pre>std::string source_line() const;</pre>
158
+
<divclass="desc">Returns 0 or code line in the source file, where the function of the stored address is defined. Throws std::bad_alloc if not enough memory to construct resulting string.</div>
<divclass="desc">Returns true if this stores and address other than NULL.</div>
102
162
163
+
164
+
<h3>Class template <basic_stacktrace></h3>
165
+
<p>The basic_stacktrace template class stores current call sequence on construction and provides functions for querying information about the call sequence.</p>
<divclass="desc">Constructs stack_frame that references NULL address. Calls to <code>source_file()</code> and <code>source_line()</code> will return empty string. Calls to <code>source_line()</code> will return 0.</div>
<divclass="desc">Constructs stack_frame that references addr and could later generate information about that address using platform specific features.</div>
163
-
164
-
165
-
<h3><code>stack_frame</code> member functions</h3>
166
-
<pre>std::string name() const;</pre>
167
-
<divclass="desc">Returns platform specific name of the stack_frame (function name in a human readable form). Throws std::bad_alloc if not enough memory to construct resulting string.</div>
<divclass="desc">Returns address of the stack_frame.</div>
171
-
172
-
<pre>std::string source_file() const;</pre>
173
-
<divclass="desc">Returns path to the source file, where the function of the frame is defined. Returns empty string if this->source_line() == 0. Throws std::bad_alloc if not enough memory to construct resulting string.</div>
174
-
175
-
<pre>std::string source_line() const;</pre>
176
-
<divclass="desc">Returns code line in the source line, where the function of the frame is defined. Throws std::bad_alloc if not enough memory to construct resulting string.</div>
177
-
178
-
<pre>constexpr bool empty() const;</pre>
179
-
<divclass="desc">Checks that stack_frame is not references NULL address.</div>
explicit basic_stacktrace(const allocator_type & a) noexcept;</pre>
190
210
191
-
<divclass="desc">Stores the current function call sequence inside *this without any decoding or any other heavy platform specific operations.</div>
211
+
<divclass="desc">Stores the current call sequence inside *this without querying information about each call.</div>
192
212
<divclass="desc">Any exception raised during this operation is
193
213
silently ignored. In case of exception <code>(bool)*this</code> is <code>false</code></div>
194
214
195
215
<pre>basic_stacktrace(size_type skip, size_type max_depth, const allocator_type& a = allocator_type()) noexcept;</pre>
196
-
<divclass="desc">Stores [skip; skip + max_depth) of the current function call sequence inside *this without any decoding or any heavy platform specific operations.</div>
216
+
<divclass="desc">Stores [skip; skip + max_depth) of the current function call sequence inside *this without querying information about each call.</div>
197
217
<divclass="desc">Any exception raised during this operation is
198
218
silently ignored. In case of exception <code>(bool)*this</code> is <code>false</code></div>
199
219
@@ -203,7 +223,7 @@ <h3><code>basic_stacktrace</code> member functions</h3>
203
223
<divclass="desc">Parameters: <code>frame_no</code> - zero-based index of frame to return. 0 is the function index where stacktrace was constructed and index close to this->size() contains function main().</div>
0 commit comments