    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head>
    <title>A Proposal to add stacktrace library</title>
    <meta content="http://schemas.microsoft.com/intellisense/ie5" name="vs_targetSchema">
    <meta http-equiv="Content-Language" content="en-us">
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

    <style type="text/css">
        .addition { color: green; }
        .right { float:right; }
        .changed-deleted { background-color: #CFF0FC ; text-decoration: line-through; display: none; }
        .addition.changed-deleted { color: green; background-color: #CFF0FC ; text-decoration: line-through; text-decoration: black double line-through; display: none; }
        .changed-added { background-color: #CFF0FC ;}
        pre { line-height: 1.2; font-size: 10pt; margin-top: 25px; }
        .desc { margin-left: 35px; margin-top: 10px; padding:0; white-space: normal; }
        body {max-width: 1024px; margin-left: 25px;}
        .cppkeyword { color: blue; }
        .cppcomment { color: green; }
        .cppcomment > .cppkeyword{ color: green; }
        .cpptext { color: #2E8B57; }
        .notes { background-color: lightgreen ;}
    </style>
</head>
<body bgcolor="#ffffff">
    <address>Document number: P0881R5</address>
    <address>Project: Programming Language C++</address>
    <address>Audience: Library Working Group, Core Working Group</address>
    <address>&nbsp;</address>
    <address>Alexey Gorgurov &lt;<a href="mailto:leha-bot@yandex.ru">leha-bot@yandex.ru</a>&gt;, &lt;<a href="mailto:no-vista@yandex.ru">no-vista@yandex.ru</a>&gt;</address>
    <address>Antony Polukhin, Yandex.Taxi Ltd, &lt;<a href="mailto:antoshkka@gmail.com">antoshkka@gmail.com</a>&gt;, &lt;<a href="mailto:antoshkka@yandex-team.ru">antoshkka@yandex-team.ru</a>&gt;</address>
    <address>&nbsp;</address>
    <address>Date: 2019-05-23</address>
    <h1>A Proposal to add stacktrace library</h1>

    <p class="changed-added">Significant changes since <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0881r3.html">P0881R3</a> are marked with blue.</p><p>
    </p><p><input type="checkbox" id="show_deletions_d" onchange="show_hide_deleted_d()"> Show deleted lines from P0881R3.</p>

        <h2>I. Motivation</h2>
	<p>In the current working draft [<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/n4741.pdf">N4741</a>] there is no way to get, store and decode the current call sequence.
	Such call sequences are useful for debugging and post mortem debugging. They are popular in other programming languages (like Java, C#, Python).</p>

	<p>Pretty often assertions can't describe the whole picture of a bug and do not provide enough information to locate the problem.
	For example, you can see the following message on out-of-range access:</p>
<pre>
boost/array.hpp:123: T& boost::array&lt;T, N&gt;::operator[](boost::array&lt;T, N&gt;::size_type): Assertion '(i &lt; N)&&("out of range")' failed.
Aborted (core dumped)</pre>
	<p>That's not enough information in the assert message to locate the problem without debugger.</p>
	<p>This paper proposes classes that could simplify debugging and may change the assertion message into the following:</p>
<pre>
Expression 'i &lt; N' is false in function 'T& boost::array&lt;T, N&gt;::operator[](boost::array&lt;T, N&gt;::size_type)': out of range.
Backtrace:
 0# boost::assertion_failed_msg(char const*, char const*, char const*, char const*, long) at ../example/assert_handler.cpp:39
 1# boost::array&lt;int, 5ul&gt;::operator[](unsigned long) at ../../../boost/array.hpp:124
 2# bar(int) at ../example/assert_handler.cpp:17
 3# foo(int) at ../example/assert_handler.cpp:25
 4# bar(int) at ../example/assert_handler.cpp:17
 5# foo(int) at ../example/assert_handler.cpp:25
 6# main at ../example/assert_handler.cpp:54
 7# 0x00007F991FD69F45 in /lib/x86_64-linux-gnu/libc.so.6
 8# 0x0000000000401139
</pre>


	<h2>II. Design Decisions</h2>
	<p>The design is based on the Boost.Stacktrace library, a popular library that does not depend on any non-standard library components.</p>
	<p><b>Note about signal safety:</b> this proposal does not attempt to provide a signal-safe solution for capturing and decoding stacktraces.
	Such functionality currently is not implementable on some of the popular platforms. However, the paper attempts to provide extensible solution, that may be made signal safe some day
	by providing a signal safe allocator and changing the <code>stacktrace</code> implementation details.</p>
	<p><b>Note on performance:</b> during Boost.Stacktrace development phase many users requested a fast way to store stacktrace, without decoding the function names. This functionality is preserved in the paper.
	All the <code>stack_frame</code> functions and constructors are lazy and won't decode the pointer information if there was no explicit request from class user.</p>
	<p><b>Note on allocations:</b> initial <span class="changed-added">(pre-Boost)</span> implementations of Boost.Stacktrace were not using allocator and all the frames were placed inside a fixed size internal storage.
	That was a mistake! Sometimes the most important information is located at the bottom of the stack. For example if you run Boost.Test, then the test name will be located low on the stack.
	With a fixed size storage the bottom of the stack could be lost along with the information.</p>
	<p>Current design assumes that by default users wish to see the whole stack and OK with dynamic allocations, because do not construct <code>stacktrace</code>
	in performance critical places.
	For those users, who wish to use <code>stacktrace</code> on a hot path or in embedded environments <code>basic_stacktrace</code> allows to provide a custom allocator that allocates
	on the stack or in some other place, where users thinks it is appropriate.</p>
        <p class="changed-added">Custom allocators support for functions like <code>to_string</code>, <code>source_file</code> and <code>description</code> is not provided. Those functions usually require platform specific
	allocations, system calls and a lot of CPU intensive work. Custom allocator does not provide benefits for those functions as the platform specific operations take an order of magnitude more time than the allocation.
	</p>
	<p><b>Note on returning <code>std::string</code> and not having <code>noexcept</code> on <code>stack_frame::source_line()</code></b>:
	Unfortunately this is a necessarity on some platforms, where getting source line requires allocating or where source
	file name <a href="https://github.com/boostorg/stacktrace/blob/a0f948e9f505cb53baf582fccbcb3024fd255ee1/include/boost/stacktrace/detail/frame_msvc.ipp#L213-L219">returned into</a> a storage
	<a href="http://www.qnx.com/developers/docs/6.5.0/index.jsp?topic=%2Fcom.qnx.doc.neutrino_lib_ref%2Fb%2Fbt_get_backtrace.html"> provided by user</a>.</p>
	<p><b>Note on expected implementation</b>:
	We assume that Standard Library implementations would allow to disable/enable gathering stacktraces by a compiler switch that does not require recompiling the whole project.
	In other words, we expect to see a compiler option like <code>-fno-stacktrace</code> or <code>libstacktrace/lib_stacktrace_noop</code> libraries with the same ABI that would
	force the constructor of the <code>basic_stacktrace</code> to do nothing. This feature is implemented in Boost.Stacktrace and is highly requested in big projects.</p>

    <p><b>Should <code>stacktrace</code> be a class or a function?</b></p>

 <table style="width:100%; border: solid" border=1>
  <tr>
    <th>class</th>
    <th>function</th>
  </tr>
  <tr>
    <td valign="top"><pre>
struct promise_type {
    std::vector&lt;stack_frame&gt; frames;

    void append(const stacktrace&amp; s) {
        frames.insert(frames.end(), s.begin(), s.end());
    }

    void print() {<span style="font-weight:bold">
        for (int i=0; auto&amp; frame: frames) {
            std::cout &lt;&lt; i++ &lt;&lt; "  " &lt;&lt; frame;
        }</span>
    }
};
</pre></td>
    <td valign="top"><pre>
struct promise_type {
    std::vector&lt;stack_frame&gt; frames;

    void append(const std::vector&lt;stack_frame&gt;&amp; s) {
        frames.insert(frames.end(), s.begin(), s.end());
    }

    void print() {
        <span style="font-weight:bold">std::cout &lt;&lt; frames;</span>
    }
};
</pre></td>  </tr>




<tr>
    <td><pre>
class stacktrace {
    <span style="font-weight:bold">small_vector&lt;stack_frame&gt; frames_;</span>
    <span style="font-weight:bold">platform-specific-cache-of-internals;</span>

public:
    <span style="font-weight:bold">operator bool() const noexcept;</span>
    // almost all the vector interface
};
</pre></td>
    <td><pre>
template&lt;class Allocator = allocator&lt;stack_frame&gt;&gt;
<span style="font-weight:bold">vector&lt;stack_frame, Allocator&gt;</span>
  stacktrace(const Allocator& alloc = Allocator{}) noexcept;


template&lt;class Allocator = allocator&lt;stack_frame&gt;&gt;
<span style="font-weight:bold">vector&lt;stack_frame, Allocator&gt;</span>
  stacktrace(size_type skip, size_type max_depth,
    const Allocator& alloc = Allocator{}) noexcept;
</pre></td>
  </tr>


<tr>
    <td><pre>

template&lt;class Allocator&gt;
string to_string(const <span style="font-weight:bold">basic_stacktrace&lt;Allocator&gt;&amp;</span> st);

template&lt;class charT, class traits, class Allocator&gt;
basic_ostream&lt;charT, traits&gt;&amp; operator&lt;&lt;
    (basic_ostream&lt;charT, traits&gt;&amp; os,
        const <span style="font-weight:bold">basic_stacktrace&lt;Allocator&gt;&amp;</span> st);
</pre></td>
    <td><pre>
template&lt;class Allocator&gt;
string to_string(const <span style="font-weight:bold">vector&lt;stack_frame, Allocator&gt;&amp;</span> st);

template&lt;class charT, class traits, class Allocator&gt;
basic_ostream&lt;charT, traits&gt;&amp; operator&lt;&lt;
    (basic_ostream&lt;charT, traits&gt;&amp; os,
        const <span style="font-weight:bold">vector&lt;stack_frame, Allocator&gt;&amp;</span> st);
</pre></td>
  </tr>


<tr>
    <td><pre>
    <span style="font-weight:bold">stacktrace s;
    if (s) {</span>
        std::cout << "backtrace: " << s;
    }
</pre></td>
    <td><pre>
    <span style="font-weight:bold">auto s = stacktrace();
    if (!s.empty()) {</span>
        std::cout << "backtrace: " << s;
    }</pre></td>
  </tr>


</table>
<p><b>LEWG</b> decided to leave it a separate type: "Prefer stacktrace as a type rather than `vector`." SF:0, F:3, N:5, A:0, SA:0 </p>








    <h2>III. Significant changes to review</h2>



    <p>Kona questions to LEWG:</p>
    <ol>
    <li><p><code>stack_frame</code> is actually a pointer to some instruction. It's a static frame, not a dynamic one (the latter including the local variables and coroutines etc). <b>Should <code>stack_frame</code> be renamed into <code><s>invocation_info</s> stacktrace::entry</code>?</b> Also note that the name <code>stack_frame</code> could be usable in the coroutines and fibers worlds.</p>
     <p><b>LEWG:</b> Naming for stack_frame:<br> 2 stack_frame<br> 3 invocation_info<br> 9 stacktrace::entry<br> 3 stacktrace::frame<br> 5 stacktrace_entry<br> 1 stacktrace_frame<br> 2 frame_descriptor<br> 4 call_info<br> 2 call_descriptor<br> 2 frame_info.<br> <b>stacktrace::entry</b> wins (Would be backtrace::entry if rename occurs).</p>
    <p><b>LEWG:</b> Nest class inside stacktrace: SF 4 F 3 N 1 A 3 SA 1. Not concensus, status quo is against.</p>
    </li>
    <li><p>If we now have <code>invocation_info</code>, <b>should <code>stacktrace</code> be renamed into <code>backtrace</code>?</b> Note that there is a <code>::backtrace</code> function on GNU Linux.</p>
    <p><b>LEWG:</b> stacktrace vs backtrace: SS 1 S 4 N 2 B 3 SB 3. Author decides. </p>
    </li>
    <li><p>Querying information about the frame is a heavy operation. To be consistent with the Filesystem approach <b>should the query functions become a free functions?</b></p>
    <p><b>LEWG:</b> Leave expensive ops as member functions.  Unanimous consent.</p>
    </li>
    <li><p>There is a difference between "physical" and "logical" invocations. In other words <code>std::stacktrace</code> may have size <code>N</code>, while the implementation could decode <code>N</code> <code>stack_frames</code> into <code>N+X</code> records in the <code>to_string</code> function. <b>Is LEWG OK with shipping the current design that gives no way to retrieve the logical invocations size?</b></p>
    <p><b>LEWG:</b> We are OK with the fact that N physical entries can become N+X logical entries after decoding (because of expanding inline functions). Unanimous consent.</p>
    </li>
    </ol>

 <table id="invocation_info" style="width:100%; border: solid" border=1>
  <tr>
    <th>stack_frame</th>
    <th>invocation_info</th>
  </tr>
  <tr>
    <td valign="top"><pre>
  unordered_map&lt;<span style="font-weight:bold">stack_frame</span>, string&gt; cache;
  // ...
  for (<span style="font-weight:bold">stack_frame</span> f : <span style="font-weight:bold">stacktrace</span>{}) {
      auto it = cache.find(f);
      if (it == cache.end()) {
          it = cache.emplace(f, <span style="font-weight:bold">f.description()</span>)-&gt;first;
      }
      cerr &lt;&lt; it-&gt;second;
  }
</pre></td>
    <td valign="top"><pre>
  unordered_map&lt;<span style="font-weight:bold">invocation_info</span>, string&gt; cache;
  // ...
  for (<span style="font-weight:bold">invocation_info</span> f : <span style="font-weight:bold">backtrace</span>{}) {
      auto it = cache.find(f);
      if (it == cache.end()) {
          it = cache.emplace(f, <span style="font-weight:bold">description(f)</span>)-&gt;first;
      }
      cerr &lt;&lt; it-&gt;second;
  }
</pre></td>  </tr>

  <tr>
    <td valign="top"><pre>
  void assertion_failed_msg(char const* expr) {
    <span style="font-weight:bold">std::stacktrace</span> st(1, 1);
    <span style="font-weight:bold">stack_frame</span> inf = st[0];
    std::cerr &lt;&lt; "Expression '" &lt;&lt; expr &lt;&lt; "' is false in '"
        &lt;&lt; <span style="font-weight:bold">inf.description()</span> &lt;&lt; " at " 
        &lt;&lt; <span style="font-weight:bold">inf.source_file()</span> &lt;&lt; ':' &lt;&lt; <span style="font-weight:bold">inf.source_line()</span>
        &lt;&lt; ".\n";
    std::abort();
  }
</pre></td>
    <td valign="top"><pre>
  void assertion_failed_msg(char const* expr) {
    <span style="font-weight:bold">std::backtrace</span> st(1, 1);
    <span style="font-weight:bold">invocation_info</span> inf = st[0];
    std::cerr &lt;&lt; "Expression '" &lt;&lt; expr &lt;&lt; "' is false in '"
        &lt;&lt; <span style="font-weight:bold">description(inf)</span> &lt;&lt; " at " 
        &lt;&lt; <span style="font-weight:bold">source_file(inf)</span> &lt;&lt; ':' &lt;&lt; <span style="font-weight:bold">source_line(inf)</span>
        &lt;&lt; ".\n";
    std::abort();
  }
</pre></td>  </tr>




<tr>
    <td><pre>
struct promise_type {
    std::vector&lt;<span style="font-weight:bold">stack_frame</span>&gt; trace;

    void append(const <span style="font-weight:bold">stacktrace</span>&amp; s) {
        trace.insert(trace.end(), s.begin(), s.end());
    }
    // ...
};
</pre></td>
    <td><pre>
struct promise_type {
    std::vector&lt;<span style="font-weight:bold">invocation_info</span>&gt; trace;

    void append(const <span style="font-weight:bold">backtrace</span>&amp; s) {
        trace.insert(trace.end(), s.begin(), s.end());
    }
    // ...
};
</pre></td>
  </tr>



</table>

<p>If the <code>invocation_info</code> and <code>stack_frame</code> are both not acceptable, the following input could be used to preview the above table with other names (like <code>call_info</code>,<code>trace_info</code>, <code>stacktrace::record</code>...):
<input type="text" id="stack_frame_name" maxlength="50" size="50" value="backtrace::entry" oninput="on_input_change(this)">
</p>


    <p>LEWG:</p>
    <ul>
    <li>Added hash support.</li>
    <li>Removed <code>stack_frame</code> constructors from function pointers and <code>stack_frame::native_ptr_t</code> alias.</li>
    <li>LWG requested <code>rbegin</code> like functions for <code>basic_stacktrace</code>, so now <code>basic_stacktrace</code> satisfies the requirements
    of an allocator-aware container, of a sequence container and reversible container except that only operations defined for const-qualified sequence containers are
    supported and that the semantics of comparison functions and default constructor are different from those required for a container.</li>
    </ul>
    <p><b>LEWG</b> was OK with the above changes.</p>

    <p>SG16:</p>
    <ul>
    <li><code>stack_frame::source_file()</code> and encodings.</li>
    </ul>
    <p><b>SG16</b> discussed a number of options including the possibility of <code>source_file()</code> returning <code>std::filesystem::path</code>. SG16 converged on the 
    following recommendation: "Align behavior with source_location; remove wording regarding 
conversion; string contents are implementation defined.
   ". No objection to unanimous consent.</p>

    <p>CWG question to LEWG:</p>
    <ul>
    <li><code>stack_frame::address()</code> function should return instruction pointer, or stack address (that may have contained the instruction pointer), or both? </li>
    </ul>
    <p><b>LEWG</b> in favour of instruction pointer: "<code>stack_frame::address()</code> should return (something like) the instruction pointer (only)." SF:4, F:7, N:0, A:0, SA:0.</p>

    <p>Points of special interest for CWG:</p>
    <ul>
    <li><i>stacktrace</i> definition in [stacktrace.def] and member functions in [stack_frame.query]. Wording should not prevent any optimizations.</li>
    </ul>

    <h2>IV. Wording Intent</h2>
    <p>Key features that should be preserved by implementations:</p>
    <ul>
    <li>All the functions are lazy and do not query the pointer information if there was no explicit request.</li>
    <li>No fixed max size for trace - all the available invokers must be stored in a <code>stacktrace</code>.</li>
    <li>Implementations should allow to disable/enable gathering stacktraces by a link-time switch.</li>
    <li>Stacktracing does not prevent any of the optimizations.</li>
    <li>No info for a pointer is OK (it's not an error, do not throw!).</li>
    <li><code>stacktrace_entry::description()</code> should return a demangled function signature if possible.</li>
    <li><code>to_string(stacktrace)</code> should query information from debug symbols, symbol export tables and any other sources, returning demangled signatures if possible.</li>
    <li class="changed-added">Providing information about inlined functions that have no separate stacktrace entries is welcomed in <code>to_string(stacktrace)</code>.</li>
    <li class="changed-added">Detecting inlined functions and doing other heavy operations is not welcomed in basic_stacktrace constructors.</li>
    <li class="changed-added"><code>stacktrace</code> should be usable in contract violation handler, coroutines, handler functions [handler.functions], parallel algorithms, etc.</li>
</ul>


    <h2>V. Wording</h2>
    <p class="notes"><i><b>[Note for editor: </b></i>Add the header &lt;stacktrace&gt; into the Table 19 in [headers] <i><b> - end note]</b></i></p>

    <h3>20.? Stacktrace <span class="right">[stacktrace]</span></h3>

    <p>This subclause describes components that C++ programs may use to store the stacktrace of the current thread of execution and
    query information about the stored stacktrace at runtime.</p>

    <h3>20.?.1 Stacktrace definition<span class="right">[stacktrace.def]</span></h3>


    <p>The <i>invocation sequence</i> of the current evaluation <code>x<sub>0</sub></code> in the current thread of execution is a sequence <code>(x<sub>0</sub>, ..., x<sub>n</sub>)</code> of evaluations such that, for <code>i ><span class="changed-added">=</span> 0</code>, <code>x<sub>i</sub></code> is within the function invocation <code>x<sub>i<span class="changed-deleted">-</span><span class="changed-added">+</span>1</sub></code> (6.8.1 [intro.execution]).</p>

    <p>A <i>stacktrace</i> is an approximate representation of an invocation sequence and consists of <i><span class="changed-deleted">stack frame</span><span class="changed-added">stacktrace entrie</span>s</i><span class="changed-deleted">, where each</span><span class="changed-added">. A </span><span class="changed-deleted">stack frame</span><span class="changed-added">stacktrace entry</span> represents an evaluation<span class="changed-added"> in a stacktrace</span>.</p>



    <h3>20.?.2 Header &lt;stacktrace&gt; synopsis <span class="right">[stacktrace.syn]</span></h3>
    <pre>
namespace std {
  // 20.?.3, class <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>
  class <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>;

  // 20.?.4, class basic_stacktrace
  template&lt;class Allocator&gt;
  class basic_stacktrace;

  // basic_stacktrace typedef names
  using stacktrace = basic_stacktrace&lt;allocator&lt;<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&gt;&gt;;

  // 20.?.5, non-member functions
  void swap(<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&amp; a, <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&amp; b) noexcept;

  template&lt;class Allocator&gt;
  void swap(basic_stacktrace&lt;Allocator&gt;&amp; a, basic_stacktrace&lt;Allocator&gt;&amp; b);

  template&lt;class Allocator&gt;
  string to_string(const basic_stacktrace&lt;Allocator&gt;&amp; st);

  string to_string(const <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&amp; f);

  template&lt;class charT, class traits, class Allocator&gt;
  basic_ostream&lt;charT, traits&gt;&amp; operator&lt;&lt;(basic_ostream&lt;charT, traits&gt;&amp; os, const basic_stacktrace&lt;Allocator&gt;&amp; st);

  template&lt;class charT, class traits&gt;
  basic_ostream&lt;charT, traits&gt;&amp; operator&lt;&lt;(basic_ostream&lt;charT, traits&gt;&amp; os, const <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&amp; f);

  // 20.?.6, hash support
  template&lt;class T&gt; struct hash;
  template&lt;&gt; struct hash&lt;<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&gt;;
  template&lt;class Allocator&gt; struct hash&lt;basic_stacktrace&lt;Allocator&gt;&gt;;
}
        </pre>


    <h3>20.?.3 Class <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span> <span class="right">[<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>]</span></h3>
    <pre>
namespace std {
  class <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span> {
  public:
    // 20.?.3.1, constructors
    constexpr <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>() noexcept;
    constexpr <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>(const <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&amp; other) noexcept = default;
    constexpr <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&amp; operator=(const <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&amp; other) noexcept = default;

    ~<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>() = default;

    // 20.?.3.2, observers
    constexpr <span class="changed-deleted">const void* address</span><span class="changed-added"><i>implementation-defined</i> native_handle</span>() const noexcept;
    constexpr explicit operator bool() const noexcept;

    // 20.?.3.3, query
    string description() const;
    string source_file() const;
    uint_least32_t source_line() const;

    // 20.?.3.4, modifiers
    void swap(<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&amp; other) noexcept;

    // 20.?.3.5, comparison
    constexpr bool operator==(const stacktrace_entry&amp; other) const noexcept;
    constexpr strong_ordering operator&lt;=&gt;(const stacktrace_entry&amp; other) const noexcept;
  };
}
        </pre>
    <p>An object of class <code><span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span></code> represents a <span class="changed-deleted">stack frame</span><span class="changed-added">stacktrace entry</span> and provides operations for querying information about it.</p>


    <h3>20.?.3.1 Construct <span class="right">[<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>.cons]</span></h3>
    <pre>constexpr <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>() noexcept;</pre>
    <div class="desc changed-deleted"><i>Ensures:</i> <code>address() == nullptr</code>.</div>
    <div class="desc changed-added"><i>Effects:</i> Constructs a <code><span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span></code> object that does not represent a <span class="changed-deleted">stack frame</span><span class="changed-added">stacktrace entry</span>.</div>

    <h3>20.?.3.2 Observers <span class="right">[<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>.obs]</span></h3>
    <pre>constexpr <span class="changed-deleted">const void* address</span><span class="changed-added"><i>implementation-defined</i> native_handle</span>() const noexcept;</pre>
    <div class="desc"><i>Returns:</i> An unspecified representation of the evaluation represented by <code>*this</code>.</div>
    <div class="desc"><i>Remarks:</i> Successive invocations of the <code><span class="changed-deleted">address()</span><span class="changed-added">native_handle()</span></code> function for the same <code><span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span></code> object return identical values.</div>

    <pre>constexpr explicit operator bool() const noexcept;</pre>
    <div class="desc changed-deleted"><i>Returns:</i> <code>address() != nullptr</code>.</div>
    <div class="desc changed-added"><i>Returns:</i> <code>true</code> only if <code>*this</code> represents a <span class="changed-deleted">stack frame</span><span class="changed-added">stacktrace entry</span>.</div>


    <h3>20.?.3.3 Query <span class="right">[<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>.query]</span></h3>
    <p><i>[Note:</i> All the <code><span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span></code> query functions treat errors other than memory allocation errors as "no information available"
    and do not throw in that case. <i>- end note]</i></p>

    <pre>string description() const;</pre>
    <div class="desc"><i>Returns:</i> A description of the evaluation represented by <code>*this</code>, <span class="changed-deleted">if such information is available,</span> or an empty string<span class="changed-deleted">otherwise</span>.</div>
    <div class="desc"><i>Throws:</i> <code>bad_alloc</code> if memory for the internal data structures or the resulting string cannot be allocated.</div>

    <pre>string source_file() const;</pre>
    <div class="desc"><i>Returns:</i> The presumed or actual name of the source file [cpp.predefined] that lexically contains the expression or statement whose evaluation is represented by <code>*this</code>, <span class="changed-deleted">if such information is available,</span> or an empty string<span class="changed-deleted">otherwise</span>.</div>
    <div class="desc"><i>Throws:</i> <code>bad_alloc</code> if memory for the internal data structures or the resulting string cannot be allocated.</div>

    <pre>uint_least32_t source_line() const;</pre>
    <div class="desc"><i>Returns:</i> <span class="changed-added"> <code>0</code>, or a </span> <span class="changed-added">1-based</span> line number that lexically relates to the evaluation represented by <code>*this</code>. If <code>source_file</code> returns the presumed name of the source file, returns the presumed line number; if <code>source_file</code> returns the actual name of the source file, returns the actual line number.<span class="changed-deleted"> If such information is not available, returns 0.</span></div>
    <div class="desc"><i>Throws:</i> <code>bad_alloc</code> if memory for the internal data structures cannot be allocated.</div>

    <h3>20.?.3.4 Modifiers <span class="right">[<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>.mod]</span></h3>
    <pre>void swap(<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&amp; other) noexcept;</pre>
    <div class="desc"><i>Effects:</i> Exchanges the contents of <code>*this</code> and <code>other</code>.</div>

    <h3>20.?.3.5 Comparison <span class="right">[<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>.cmp]</span></h3>
    <pre>constexpr bool operator==(const stacktrace_entry&amp; other) const noexcept;</pre>
    <div class="desc changed-added"><i>Returns:</i> <code>true</code> only if <code>*this</code> and <code>other</code> represent the same stacktrace entry or neither <code>*this</code> nor <code>other</code> represent a stacktrace entry.</div>

    <pre>constexpr strong_ordering operator&lt;=&gt; (const stacktrace_entry&amp; other) const noexcept;</pre>
    <div class="desc changed-added"><i>Returns:</i> A value such that <code>operator&lt;=&gt;</code> is a total ordering as described in [alg.sorting].</div>

    <h3>20.?.4 Class template <code>basic_stacktrace</code> <span class="right">[stacktrace.basic.template]</span></h3>
    <pre>
namespace std {
  template&lt;class Allocator&gt;
  class basic_stacktrace {
  public:
    using value_type = <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>;
    using const_reference = const value_type&amp;;
    using reference = value_type&amp;;
    using const_iterator = <i>implementation-defined</i>;
    using iterator = const_iterator;
    using reverse_iterator = std::reverse_iterator&lt;iterator&gt;;
    using const_reverse_iterator = std::reverse_iterator&lt;const_iterator&gt;;
    using difference_type = typename iterator_traits&lt;iterator&gt;::difference_type;
    using size_type = typename allocator_traits&lt;Allocator&gt;::size_type;
    using allocator_type = Allocator;

    // 20.?.4.1, construct/copy/destroy
    basic_stacktrace() noexcept;
    <span class="changed-deleted">explicit </span>basic_stacktrace(<span class="changed-added">allocator_arg_t, </span>const allocator_type&amp; alloc) noexcept;
    basic_stacktrace(size_type skip, size_type max_depth<span class="changed-deleted">, const allocator_type&amp; alloc = allocator_type()</span>) noexcept;
    <span class="changed-added">basic_stacktrace(allocator_arg_t, const allocator_type&amp; alloc, size_type skip, size_type max_depth) noexcept;</span>

    basic_stacktrace(const basic_stacktrace&amp; other) = default;
    basic_stacktrace(basic_stacktrace&amp;&amp; other) noexcept = default;
    <span class="changed-added">basic_stacktrace(allocator_arg_t, const allocator_type&amp; alloc, const basic_stacktrace&amp; other);</span>
    <span class="changed-added">basic_stacktrace(allocator_arg_t, const allocator_type&amp; alloc, basic_stacktrace&amp;&amp; other);</span>
    basic_stacktrace&amp; operator=(const basic_stacktrace&amp; other) = default;
    basic_stacktrace&amp; operator=(basic_stacktrace&amp;&amp; other) = default;

    ~basic_stacktrace() = default;

    // 20.?.4.2, observers
    allocator_type get_allocator() const;

    const_iterator begin() const noexcept;
    const_iterator end() const noexcept;
    const_reverse_iterator rbegin() const noexcept;
    const_reverse_iterator rend() const noexcept;

    const_iterator cbegin() const noexcept;
    const_iterator cend() const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend() const noexcept;

    explicit operator bool() const noexcept;
    [[nodiscard]] bool empty() const noexcept;
    size_type size() const noexcept;
    size_type max_size() const noexcept;

    const_reference operator[](size_type ) const;
    const_reference at(size_type ) const;

    // 20.?.4.3, comparisons
    template &lt;class Allocator2&gt;
    bool operator==(const basic_stacktrace&lt; Allocator2 &gt;&amp; other) const noexcept;
    template &lt;class Allocator2&gt;
    strong_ordering operator&lt;=&gt;(const basic_stacktrace&lt; Allocator2 &gt;&amp; other) const noexcept;

    // 20.?.4.4, modifiers
    void swap(basic_stacktrace&amp; other);

  private:
    vector&lt;value_type, allocator_type&gt; frames; // exposition only
  };

}
        </pre>
    <p>The <code>basic_stacktrace</code> template class stores the stacktrace of the current thread of execution on construction and provides access to the stored stacktrace.</p>

    <p>The class template <code>basic_stacktrace</code> satisfies the requirements of an allocator-aware container, of a sequence
    container and reversible container (21.2.1, 21.2.3) except that only operations defined for const-qualified sequence containers are
    supported and that the semantics of comparison functions and default constructor are different from those required for a container.</p>

    <h3>20.?.4.1 Construct/copy/destroy <span class="right">[stacktrace.basic.cons]</span></h3>
    <pre>basic_stacktrace() noexcept;
<span class="changed-deleted">explicit </span>basic_stacktrace(<span class="changed-added">allocator_arg_t, </span>const allocator_type&amp; alloc) noexcept;</pre>

    <div class="desc"><i>Effects:</i> Stores the stacktrace of the current evaluation in the current thread of execution in <code>frames</code>. <code>alloc</code> is passed to the <code>frames</code> constructor. </div>
    <div class="desc"><i>[Note:</i> If the stacktrace was successfully obtained, then <code>frames.front()</code> is the <code><span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span></code> representing approximately the current evaluation, and <code>frames.back()</code> is the <code><span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span></code> representing approximately the initial function of the current thread of execution.<i> - end note]</i></div>
    <div class="desc"><i>Ensures:</i> <code>!*this</code> if failed to store stacktrace of the current thread of execution; <code>!!*this</code> otherwise.</div>

    <pre>basic_stacktrace(size_type skip, size_type max_depth<span class="changed-deleted">, const allocator_type&amp; alloc = allocator_type()</span>) noexcept;</pre>
    <div class="desc">Let <code>t</code> be a stacktrace as-if obtained via <code>basic_stacktrace()</code>. Let <code>n</code> be <code>t.size()</code>.</div>
    <div class="desc changed-added"><i>Expects:</i> <code>skip &lt;= skip + max_depth</code>.</div>
    <div class="desc"><i>Effects:</i> <code>frames(t.begin() + min(n, skip), t.begin() + min(n, skip + max_depth))</code>.</div>

    <pre><span class="changed-added">basic_stacktrace(allocator_arg_t, const allocator_type&amp; alloc, size_type skip, size_type max_depth) noexcept;</span></pre>
    <div class="desc">Let <code>t</code> be a stacktrace as-if obtained via <code>basic_stacktrace(alloc)</code>. Let <code>n</code> be <code>t.size()</code>.</div>
    <div class="desc changed-added"><i>Expects:</i> <code>skip &lt;= skip + max_depth</code>.</div>
    <div class="desc"><i>Effects:</i> <code>frames(t.begin() + min(n, skip), t.begin() + min(n, skip + max_depth), alloc)</code>.</div>

<div class="changed-added">
    <pre>basic_stacktrace(const basic_stacktrace&amp; other) = default;
basic_stacktrace(allocator_arg_t, const allocator_type&amp; alloc, const basic_stacktrace&amp; other);
basic_stacktrace(allocator_arg_t, const allocator_type&amp; alloc, basic_stacktrace&amp;&amp; other);
basic_stacktrace&amp; operator=(const basic_stacktrace&amp; other) = default;
basic_stacktrace&amp; operator=(basic_stacktrace&amp;&amp; other) = default;</pre>
    <div class="desc"><i>Remarks:</i> Implementations may strengthen the exception specification for those functions [res.on.exception.handling] by ensuring that <code>!*this</code> is <code>true</code> on failed allocation.</div>
</div>

    <h3>20.?.4.2 Observers <span class="right">[stacktrace.basic.obs]</span></h3>

    <pre>allocator_type get_allocator() const;</pre>
    <div class="desc"><i>Returns:</i> <code>frames.get_allocator()</code>.</div>

    <pre>const_iterator begin() const noexcept;
const_iterator cbegin() const noexcept;</pre>
    <div class="desc"><i>Returns:</i> <code>frames.cbegin()</code>.</div>

    <pre>const_iterator end() const noexcept;
const_iterator cend() const noexcept;</pre>
    <div class="desc"><i>Returns:</i> <code>frames.cend()</code>.</div>

    <pre>const_iterator rbegin() const noexcept;
const_iterator crbegin() const noexcept;</pre>
    <div class="desc"><i>Returns:</i> <code>frames.crbegin()</code>.</div>

    <pre>const_iterator rend() const noexcept;
const_iterator crend() const noexcept;</pre>
    <div class="desc"><i>Returns:</i> <code>frames.crend()</code>.</div>

    <pre>explicit operator bool() const noexcept;</pre>
    <div class="desc"><i>Returns:</i> <code>!frames.empty()</code>.</div>

    <pre>[[nodiscard]] bool empty() const noexcept;</pre>
    <div class="desc"><i>Returns:</i> <code>frames.empty()</code>.</div>

    <pre>size_type size() const noexcept;</pre>
    <div class="desc"><i>Returns:</i> <code>frames.size()</code>.</div>

    <pre>size_type max_size() const noexcept;</pre>
    <div class="desc"><i>Returns:</i> <code>frames.max_size()</code>.</div>

    <pre>const_reference operator[](size_type frame_no) const;</pre>
    <div class="desc"><i>Expects:</i> <code>frame_no &lt; size()</code>.</div>
    <div class="desc"><i>Returns:</i> <code>frames[frame_no]</code>.</div>
    <div class="desc"><i>Throws:</i> Nothing.</div>

    <pre>const_reference at(size_type frame_no) const;</pre>
    <div class="desc"><i>Throws:</i> <code>out_of_range</code> if <code>frame_no &gt;= size()</code>.</div>
    <div class="desc"><i>Returns:</i> <code>frames[frame_no]</code>.</div>


    <h3>20.?.4.3 Comparisons <span class="right">[stacktrace.basic.comp]</span></h3>
    <pre>template &lt;class Allocator2&gt;
bool operator==(const basic_stacktrace&lt; Allocator2 &gt;&amp; other) const noexcept;</pre>
    <div class="desc"><i>Returns:</i> <code>this-&gt;size() == other.size() && equal(this-&gt;begin(), this-&gt;end(), other.begin(), other.end())</code></div>
    <pre>template &lt;class Allocator2&gt;
strong_ordering operator&lt;=&gt;(const basic_stacktrace&lt; Allocator2 &gt;&amp; other) const noexcept;</pre>
    <div class="desc"><i>Returns:</i> <code>this-&gt;size() &lt;=&gt; other.size()</code> if <code>this-&gt;size() != other.size()</code>.
    <code>lexicographical_compare_3way(this-&gt;begin(), this-&gt;end(), other.begin(), other.end())</code> otherwise.</div>

    <h3>20.?.4.4 Modifiers <span class="right">[stacktrace.basic.mod]</span></h3>
    <pre>void swap(basic_stacktrace&amp; other);</pre>
    <div class="desc"><i>Effects:</i> Exchanges the contents of <code>*this</code> and <code>other</code>.</div>


    <h3>20.?.5 Non-member functions <span class="right">[stacktrace.nonmembers]</span></h3>
    <pre>void swap(<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&amp; a, <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&amp; b) noexcept;</pre>
    <div class="desc"><i>Effects:</i> Equivalent to <code>a.swap(b)</code>.</div>
    
    <pre>template&lt;class Allocator&gt;
void swap(basic_stacktrace&lt;Allocator&gt;&amp; a, basic_stacktrace&lt;Allocator&gt;&amp; b);</pre>
    <div class="desc"><i>Effects:</i> Equivalent to <code>a.swap(b)</code>.</div>

    <pre>template&lt;class Allocator&gt;
string to_string(const basic_stacktrace&lt;Allocator&gt;&amp; st);</pre>
    <div class="desc"><i>Returns:</i> A multiline string with a description of a stacktrace.</div>
    <div class="desc changed-added"><i>[Note:</i> Number of lines is not guaranteed to be equal to <code>st.size()</code>.<i> - end note]</i></div>

    <pre>string to_string(const <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&amp; f);</pre>
    <div class="desc"><i>Returns:</i> A string with a description of <code>f</code>.</div>
    <div class="desc"><i>[Note:</i> The description should provide information about contained evaluation, including information from <code>source_file()</code> and <code>source_line()</code>.<i> - end note]</i></div>

    <pre>template&lt;class charT, class traits, class Allocator&gt;
basic_ostream&lt;charT, traits&gt;&amp; operator&lt;&lt;(basic_ostream&lt;charT, traits&gt;&amp; os, const basic_stacktrace&lt;Allocator&gt;&amp; st);</pre>
    <div class="desc"><i>Effects:</i> As if by <code>os &lt;&lt; to_string(bt);</code></div>
    <div class="desc"><i>Returns:</i> <code>os</code>.</div>

  <pre>template&lt;class charT, class traits&gt;
basic_ostream&lt;charT, traits&gt;&amp; operator&lt;&lt;(basic_ostream&lt;charT, traits&gt;&amp; os, const <span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&amp; f);</pre>
    <div class="desc"><i>Returns:</i> <code>os &lt;&lt; to_string(f)</code>.</div>


    <h3>20.?.6 Hash support <span class="right">[stacktrace.hash]</span></h3>
    <pre>template&lt;&gt; struct hash&lt;<span class="changed-deleted">stack_frame</span><span class="changed-added">stacktrace_entry</span>&gt;;
template&lt;class Allocator&gt; struct hash&lt;basic_stacktrace&lt;Allocator&gt;&gt;;</pre>
    <div class="desc">The specialization is enabled (23.14.15).</div>


    <h3>Feature-testing macro</h3>
    <p class="notes"><i><b>[Note for editor: </b></i>Add a row into the "Standard library feature-test macros" table [support.limits.general] <i><b> - end note]</b></i></p>
    <table border="1"><tr><td><code>__cpp_lib_stacktrace</code></td><td>201<span class="changed-deleted">811</span><span class="changed-added">907</span></td><td><code>&lt;stacktrace&gt;</code></td></tr></table>





    <h2>VI. Acknowledgements</h2>
    <p>Many thanks to Jens Maurer, JF Bastien and Marshall Clow for pointing out many issues in the early wordings.</p>
    <p>Special thanks to Jens Maurer for doing the core wordings.</p>
    <p>Many many thanks to all the people who participated in the LWG meeting on 20th of August and reviewed early version of the wording.</p>





        <script type="text/javascript">
            function colorize_texts(texts) {
                for (var i = 0; i < texts.length; ++i) {
                    var text = texts[i].innerHTML;
                    text = text.replace(/namespace|for |if |char |enum|void|constexpr|extern|noexcept|bool|template|class |struct|auto|const |typename|explicit|public|private|#include|inline|typedef|static_assert|static_cast|static/g,"<span class='cppkeyword'>$&<\/span>");
                    text = text.replace(/\/\/[\s\S]+?\n/g,"<span class='cppcomment'>$&<\/span>");
                    texts[i].innerHTML = text;
                }
            }

            colorize_texts(document.getElementsByTagName("pre"));
            colorize_texts(document.getElementsByTagName("code"));

            function show_hide_deleted_d() {
                var to_change = document.getElementsByClassName('changed-deleted');
                for (var i = 0; i < to_change.length; ++i) {
                    to_change[i].style.display = (document.getElementById("show_deletions_d").checked ? 'block' : 'none');
                }
            }
            show_hide_deleted_d()

            initial_text = document.getElementById('invocation_info').innerHTML
            function on_input_change(self) {
                document.getElementById('invocation_info').innerHTML = initial_text.replace(/invocation_info/g, self.value);
            }
            on_input_change(document.getElementById('stack_frame_name'))
        </script>
</body></html>

