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 38: / Line 38: @@
 ===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}}|{{co|const value_type&}}}}
+{{dsc|{{tt|const_reference}}|{{co|const value_type&}}}}
-{{dsc|{{tt|reference}}{{mark c++23}}|{{co|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}}|{{co|std::reverse_iterator<iterator>}}}}
+{{dsc|{{tt|reverse_iterator}}|{{co|std::reverse_iterator<iterator>}}}}
-{{dsc|{{tt|reverse_const_iterator}}{{mark c++23}}|{{co|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}}
@@ Line 54: / Line 54: @@
 {{dsc begin}}
 {{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 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}}
@@ Line 89: / Line 89: @@
 {{dsc begin}}
 {{dsc inc|cpp/utility/basic_stacktrace/dsc hash}}
+{{dsc inc|cpp/utility/basic_stacktrace/dsc formatter}}
 {{dsc end}}
@@ Line 96: / 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/release/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.
-{{feature test macro|__cpp_lib_stacktrace|std=C++23|value=202011L|[[#top|Stacktrace]] library}}
+{{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}}
-===GCC Example===
+===Example===
-{{example|output obtained using https://godbolt.org/z/v117ccshs
+{{example
+|The output obtained using Compiler Explorer: [https://godbolt.org/z/sjxvc97a7 msvc] and [https://godbolt.org/z/v117ccshs gcc].
 |code=
-#include <stacktrace>
 #include <iostream>
+#include <stacktrace>
 int nested_func(int c)
@@ Line 116: / Line 121: @@
      return nested_func(b + 1);
 }
 int main()
 {
@@ Line 123: / Line 128: @@
 |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
@@ Line 130: / Line 149: @@
 #
-}}
-===Example===
-{{example|output obtained using https://godbolt.org/z/sjxvc97a7
-|code=
-#include <stacktrace>
-#include <iostream>
-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=
-> C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-compiler20221122-31624-2ja1sf.8ytzw\example.cpp(6): output_s!nested_func+0x1F
-> C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-compiler20221122-31624-2ja1sf.8ytzw\example.cpp(12): output_s!func+0x15
-> C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-compiler20221122-31624-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
 }}

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