Difference between revisions of "cpp/utility/basic stacktrace"

Latest revision as of 01:38, 1 January 2024

Defined in header `<stacktrace>`
template< class Allocator > class basic_stacktrace;	(1)	(since C++23)
using stacktrace = std::basic_stacktrace<std::allocator<std::stacktrace_entry>>;	(2)	(since C++23)
namespace pmr { using stacktrace = std::basic_stacktrace<std::pmr::polymorphic_allocator<std::stacktrace_entry>>; }	(3)	(since C++23)

1) The basic_stacktrace class template represents a snapshot of the whole stacktrace or its given part. It satisfies the requirement of AllocatorAwareContainer, SequenceContainer, and ReversibleContainer, except that only move, assignment, swap, and operations for const-qualified sequence containers are supported, and the semantics of comparison functions are different from those required for a container.

2) Convenience type alias for the basic_stacktrace using the default std::allocator.

3) Convenience type alias for the basic_stacktrace using the polymorphic allocator.

The invocation sequence of the current evaluation $\small{ {x}_{0} }$ $x 0$ in the current thread of execution is a sequence $\small{ ({x}_{0}, \dots, {x}_{n})}$ $(x 0, ..., x n)$ of evaluations such that, for $\small{i \ge 0}$ $i\geq0$ , $\small{ {x}_{i} }$ $x i$ is within the function invocation $\small{ {x}_{i+1} }$ $x i+1$ .

A stacktrace is an approximate representation of an invocation sequence and consists of stacktrace entries.

A stacktrace entry represents an evaluation in a stacktrace. It is represented by std::stacktrace_entry in the C++ standard library.

Member type	Definition
`value_type`	std::stacktrace_entry
`const_reference`	const value_type&
`reference`	value_type&
`const_iterator`	implementation-defined const LegacyRandomAccessIterator type that models `random_access_iterator`
`iterator`	`const_iterator`
`reverse_iterator`	std::reverse_iterator<iterator>
`reverse_const_iterator`	std::reverse_iterator<const_iterator>
`difference_type`	implementation-defined signed integer type
`size_type`	implementation-defined unsigned integer type
`allocator_type`	`Allocator`

[edit] Member functions

(constructor)	creates a new `basic_stacktrace` (public member function) [edit]
(destructor)	destroys the `basic_stacktrace` (public member function) [edit]
operator=	assigns to the `basic_stacktrace` (public member function) [edit]
current [static]	obtains the current stacktrace or its given part (public static member function) [edit]
get_allocator	returns the associated allocator (public member function) [edit]
Iterators
begincbegin	returns an iterator to the beginning (public member function) [edit]
endcend	returns an iterator to the end (public member function) [edit]
rbegincrbegin	returns a reverse iterator to the beginning (public member function) [edit]
rendcrend	returns a reverse iterator to the end (public member function) [edit]
Capacity
empty	checks whether the `basic_stacktrace` is empty (public member function) [edit]
size	returns the number of stacktrace entries (public member function) [edit]
max_size	returns the maximum possible number of stacktrace entries (public member function) [edit]
Element access
operator[]	access specified stacktrace entry (public member function) [edit]
at	access specified stacktrace entry with bounds checking (public member function) [edit]
Modifiers
swap	swaps the contents (public member function) [edit]

[edit] Non-member functions

operator==operator<=> (C++23)	compares the sizes and the contents of two `basic_stacktrace` values (function template)
std::swap(std::basic_stacktrace) (C++23)	specializes the std::swap algorithm (function template) [edit]
to_string (C++23)	returns a string with a description of the `basic_stacktrace` (function template) [edit]
operator<< (C++23)	performs stream output of `basic_stracktrace` (function template) [edit]

[edit] Helper classes

std::hash<std::basic_stacktrace> (C++23)	hash support for `std::basic_stacktrace` (class template specialization) [edit]
std::formatter<std::basic_stacktrace> (C++23)	formatting support for `basic_stacktrace` (class template specialization) [edit]

[edit] Notes

Support for custom allocators is provided for using basic_stacktrace on a hot path or in embedded environments. Users can allocate stacktrace_entry objects on the stack or in some other place, where appropriate.

The sequence of std::stacktrace_entry objects owned by a std::basic_stacktrace is immutable, and either is empty or represents a contiguous interval of the whole stacktrace.

boost::stacktrace::basic_stacktrace (available in Boost.Stacktrace) can be used instead when std::basic_stacktrace is not available.

Feature-test macro	Value	Std	Feature
`__cpp_lib_stacktrace`	202011L	(C++23)	Stacktrace library
`__cpp_lib_formatters`	202302L	(C++23)	Formatting std::thread::id and std::stacktrace

[edit] Example

The output obtained using Compiler Explorer: msvc and gcc.

Run this code

#include <iostream>
#include <stacktrace>
 
int nested_func(int c)
{
    std::cout << std::stacktrace::current() << '\n';
    return c + 1;
}
 
int func(int b)
{
    return nested_func(b + 1);
}
 
int main()
{
    std::cout << func(777);
}

Possible output:

// msvc output (the lines ending with '⤶' arrows are split to fit the width):
0> C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-compiler20221122-⤶
31624-2ja1sf.8ytzw\example.cpp(6): output_s!nested_func+0x1F
1> C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-compiler20221122-⤶
31624-2ja1sf.8ytzw\example.cpp(12): output_s!func+0x15
2> C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-compiler20221122-⤶
31624-2ja1sf.8ytzw\example.cpp(15): output_s!main+0xE
3> D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288): output_s!⤶
__scrt_common_main_seh+0x10C
4> KERNEL32!BaseThreadInitThunk+0x14
5> ntdll!RtlUserThreadStart+0x21
779
 
gcc output:
   0# nested_func(int) at /app/example.cpp:7
   1# func(int) at /app/example.cpp:13
   2#      at /app/example.cpp:18
   3#      at :0
   4#      at :0
   5# 
 
779

[edit] See also

stacktrace_entry

(C++23)

representation of an evaluation in a stacktrace
(class) [edit]

@@ Line 2: / Line 2: @@
 {{cpp/utility/basic_stacktrace/navbar}}
 {{dcl begin}}
-{{dcl header | stacktrace}}
+{{dcl header|stacktrace}}
-{{dcl | num=1 | since=c++23 |
+{{dcl|num=1|since=c++23|
 template< class Allocator >
 class basic_stacktrace;
 }}
-{{dcl | num=2 | since=c++23 | 1=
+{{dcl|num=2|since=c++23|1=
 using stacktrace =
      std::basic_stacktrace<std::allocator<std::stacktrace_entry>>;
 }}
-{{dcl | num=3 | since=c++23 | 1=
+{{dcl|num=3|since=c++23|1=
 namespace pmr {
-    using stacktrace =
+using stacktrace =
-        std::basic_stacktrace<std::polymorphic_allocator<std::stacktrace_enty>>
+    std::basic_stacktrace<std::pmr::polymorphic_allocator<std::stacktrace_entry>>;
 }
 }}
@@ Line 23: / Line 23: @@
 @2@ Convenience type alias for the {{tt|basic_stacktrace}} using the default {{lc|std::allocator}}.
-@3@ Convenience type alias for the {{tt|basic_stacktrace}} using the [[cpp/memory/polymorphic_allocator|polymorphic allocator]].
+@3@ Convenience type alias for the {{tt|basic_stacktrace}} using the {{lt|cpp/memory/polymorphic allocator}}.
 The ''invocation sequence'' of the current evaluation {{mathjax-or|\(\small{ {x}_{0} }\)|x<sub>0</sub>}} in the current thread of execution is a sequence {{mathjax-or|\(\small{ ({x}_{0}, \dots, {x}_{n})}\)|(x<sub>0</sub>, ..., x<sub>n</sub>)}} of evaluations such that, for {{mathjax-or|\(\small{i \ge 0}\)|i≥0}}, {{mathjax-or|\(\small{ {x}_{i} }\)|x<sub>i</sub>}} is within the function invocation {{mathjax-or|\(\small{ {x}_{i+1} }\)|x<sub>i+1</sub>}}.
@@ Line 33: / Line 33: @@
 ===Template parameters===
 {{par begin}}
-{{par | Allocator | An allocator that is used to acquire/release memory and to construct/destroy the elements in that memory. The type must meet the requirements of {{named req|Allocator}}. The program is ill-formed if {{tt|Allocator::value_type}} is not {{lc|std::stacktrace_entry}}.}}
+{{par|Allocator|An allocator that is used to acquire/release memory and to construct/destroy the elements in that memory. The type must meet the requirements of {{named req|Allocator}}. The program is ill-formed if {{tt|Allocator::value_type}} is not {{lc|std::stacktrace_entry}}.}}
 {{par end}}
 ===Member types===
 {{dsc begin}}
-{{dsc hitem | Member type | Definition }}
+{{dsc hitem|Member type|Definition}}
-{{dsc | {{tt|value_type}}{{mark c++23}} | {{lc|std::stacktrace_entry}} }}
+{{dsc|{{tt|value_type}}|{{lc|std::stacktrace_entry}}}}
-{{dsc | {{tt|const_reference}}{{mark c++23}} | {{c|const value_type&}} }}
+{{dsc|{{tt|const_reference}}|{{co|const value_type&}}}}
-{{dsc | {{tt|reference}}{{mark c++23}} | {{c|value_type&}} }}
+{{dsc|{{tt|reference}}|{{co|value_type&}}}}
-{{dsc | {{tt|const_iterator}}{{mark c++23}} | implementation-defined const {{named req|RandomAccessIterator}} type that models {{lconcept|random_access_iterator}} }}
+{{dsc|{{tt|const_iterator}}|implementation-defined const {{named req|RandomAccessIterator}} type that models {{lconcept|random_access_iterator}}}}
-{{dsc | {{tt|iterator}}{{mark c++23}} | {{tt|const_iterator}} }}
+{{dsc|{{tt|iterator}}|{{tt|const_iterator}}}}
-{{dsc | {{tt|reverse_iterator}}{{mark c++23}} | {{c|std::reverse_iterator<iterator>}} }}
+{{dsc|{{tt|reverse_iterator}}|{{co|std::reverse_iterator<iterator>}}}}
-{{dsc | {{tt|reverse_const_iterator}}{{mark c++23}} | {{c|std::reverse_iterator<const_iterator>}} }}
+{{dsc|{{tt|reverse_const_iterator}}|{{co|std::reverse_iterator<const_iterator>}}}}
-{{dsc | {{tt|difference_type}}{{mark c++23}} | implementation-defined signed integer type}}
+{{dsc|{{tt|difference_type}}|implementation-defined signed integer type}}
-{{dsc | {{tt|size_type}}{{mark c++23}} | implementation-defined unsigned integer type}}
+{{dsc|{{tt|size_type}}|implementation-defined unsigned integer type}}
-{{dsc | {{tt|allocator_type}}{{mark c++23}} | {{tt|Allocator}} }}
+{{dsc|{{tt|allocator_type}}|{{tt|Allocator}}}}
 {{dsc end}}
 ===Member functions===
 {{dsc begin}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc constructor}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc constructor}}
-{{dsc mem dtor | cpp/utility/basic_stacktrace/~basic_stacktrace | notes={{mark c++23}} | destroys the {{tt|basic_stacktrace}} }}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc destructor}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc operator{{=}}}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc operator{{=}}}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc current}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc current}}
-{{dsc mem fun | cpp/utility/basic_stacktrace/get_allocator | notes={{mark c++23}} | returns the associated allocator}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc get_allocator}}
-{{dsc h2 | Iterators}}
+{{dsc h2|Iterators}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc begin}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc begin}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc end}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc end}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc rbegin}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc rbegin}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc rend}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc rend}}
-{{dsc h2 | Capacity}}
+{{dsc h2|Capacity}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc empty}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc empty}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc size}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc size}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc max_size}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc max_size}}
-{{dsc h2 | Element access}}
+{{dsc h2|Element access}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc operator at}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc at}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc operator at}}
+{{dsc h2|Modifiers}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc at}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc swap}}
-{{dsc h2 | Modifiers}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc swap}}
 {{dsc end}}
 ===Non-member functions===
 {{dsc begin}}
-{{dsc tfun | cpp/utility/basic_stacktrace/operator cmp | title=operator==<br>operator<=> | notes={{mark c++23}} | compares the sizes and the contents of two {{tt|basic_stacktrace}} values}}
+{{dsc tfun|cpp/utility/basic_stacktrace/operator cmp|title=operator==<br>operator<=>|notes={{mark c++23}}|compares the sizes and the contents of two {{tt|basic_stacktrace}} values}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc swap2}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc swap2}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc to_string}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc to_string}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc operator ltlt}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc operator ltlt}}
 {{dsc end}}
 ===Helper classes===
 {{dsc begin}}
-{{dsc inc | cpp/utility/basic_stacktrace/dsc hash}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc hash}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc formatter}}
 {{dsc end}}
@@ Line 97: / Line 97: @@
 The sequence of {{lc|std::stacktrace_entry}} objects owned by a {{tt|std::basic_stacktrace}} is immutable, and either is empty or represents a contiguous interval of the whole stacktrace.
-{{tt|boost::stacktrace::basic_stacktrace}} (available in [https://www.boost.org/doc/libs/1_76_0/doc/html/stacktrace.html Boost.Stacktrace]) can be used instead when {{tt|std::basic_stacktrace}} is not available.
+{{co|boost::stacktrace::basic_stacktrace}} (available in [https://www.boost.org/doc/libs/release/doc/html/stacktrace.html Boost.Stacktrace]) can be used instead when {{tt|std::basic_stacktrace}} is not available.
+{{ftm begin|std=1|comment=1}}
+{{ftm|__cpp_lib_stacktrace|std=C++23|value=202011L|[[#top|Stacktrace]] library}}
+{{ftm|__cpp_lib_formatters|Formatting {{lc|std::thread::id}} and {{lc|std::stacktrace}}|value=202302L|std=C++23}}
+{{ftm end}}
 ===Example===
-{{example}}
+{{example
+|The output obtained using Compiler Explorer: [https://godbolt.org/z/sjxvc97a7 msvc] and [https://godbolt.org/z/v117ccshs gcc].
+|code=
+#include <iostream>
+#include <stacktrace>
+int nested_func(int c)
+{
+    std::cout << std::stacktrace::current() << '\n';
+    return c + 1;
+}
+int func(int b)
+{
+    return nested_func(b + 1);
+}
+int main()
+{
+    std::cout << func(777);
+}
+|p=true
+|output=
+// msvc output (the lines ending with '⤶' arrows are split to fit the width):
+> C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-compiler20221122-⤶
+-2ja1sf.8ytzw\example.cpp(6): output_s!nested_func+0x1F
+> C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-compiler20221122-⤶
+-2ja1sf.8ytzw\example.cpp(12): output_s!func+0x15
+> C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-compiler20221122-⤶
+-2ja1sf.8ytzw\example.cpp(15): output_s!main+0xE
+> D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288): output_s!⤶
+__scrt_common_main_seh+0x10C
+> KERNEL32!BaseThreadInitThunk+0x14
+> ntdll!RtlUserThreadStart+0x21
+gcc output:
+# nested_func(int) at /app/example.cpp:7
+# func(int) at /app/example.cpp:13
+#      at /app/example.cpp:18
+#      at :0
+#      at :0
+#
+}}
 ===See also===
 {{dsc begin}}
-{{dsc inc | cpp/utility/dsc stacktrace_entry}}
+{{dsc inc|cpp/utility/dsc stacktrace_entry}}
 {{dsc end}}
-{{langlinks|es|ja|ru|zh}}
+{{langlinks|de|es|ja|ru|zh}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

Member functions
basic_stacktrace::basic_stacktrace
basic_stacktrace::~basic_stacktrace
basic_stacktrace::operator=
basic_stacktrace::current
basic_stacktrace::get_allocator
Iterators
basic_stacktrace::beginbasic_stacktrace::cbegin
basic_stacktrace::endbasic_stacktrace::cend
basic_stacktrace::rbeginbasic_stacktrace::crbegin
basic_stacktrace::rendbasic_stacktrace::crend
Capacity
basic_stacktrace::empty
basic_stacktrace::size
basic_stacktrace::max_size
Element access
basic_stacktrace::operator[]
basic_stacktrace::at
Modifiers
basic_stacktrace::swap
Non-member functions
operator== operator<=>
swap(std::basic_stacktrace)
to_string(std::basic_stacktrace)
operator<<
Helper classes
hash<std::basic_stacktrace>
formatter<std::basic_stacktrace>

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/utility/basic stacktrace"

Latest revision as of 01:38, 1 January 2024

Contents

[edit] Template parameters

[edit] Member types

[edit] Member functions

Iterators

Capacity

Element access

Modifiers

[edit] Non-member functions

[edit] Helper classes

[edit] Notes

[edit] Example

[edit] See also

Navigation

Toolbox