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

Revision as of 14:34, 19 February 2023

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`(C++23)	std::stacktrace_entry
`const_reference`(C++23)	const value_type&
`reference`(C++23)	value_type&
`const_iterator`(C++23)	implementation-defined const LegacyRandomAccessIterator type that models `random_access_iterator`
`iterator`(C++23)	`const_iterator`
`reverse_iterator`(C++23)	std::reverse_iterator<iterator>
`reverse_const_iterator`(C++23)	std::reverse_iterator<const_iterator>
`difference_type`(C++23)	implementation-defined signed integer type
`size_type`(C++23)	implementation-defined unsigned integer type
`allocator_type`(C++23)	`Allocator`

Member functions

(constructor)	creates a new `basic_stacktrace` (public member function) [edit]
(destructor) (C++23)	destroys the `basic_stacktrace` (public member function)
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 (C++23)	returns the associated allocator (public member function)
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]

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]

Helper classes

std::hash<std::basic_stacktrace>

(C++23)

hash support for std::basic_stacktrace
(class template specialization) [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

Example

output obtained using https://godbolt.org/z/sjxvc97a7

Run this 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);
}

Possible output:

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

@@ 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 40: / Line 40: @@
 {{dsc hitem|Member type|Definition }}
 {{dsc|{{tt|value_type}}{{mark c++23}}|{{lc|std::stacktrace_entry}}}}
-{{dsc|{{tt|const_reference}}{{mark c++23}}|{{c|const value_type&}}}}
+{{dsc|{{tt|const_reference}}{{mark c++23}}|{{co|const value_type&}}}}
-{{dsc|{{tt|reference}}{{mark c++23}}|{{c|value_type&}}}}
+{{dsc|{{tt|reference}}{{mark c++23}}|{{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|iterator}}{{mark c++23}}|{{tt|const_iterator}}}}
-{{dsc|{{tt|reverse_iterator}}{{mark c++23}}|{{c|std::reverse_iterator<iterator>}}}}
+{{dsc|{{tt|reverse_iterator}}{{mark c++23}}|{{co|std::reverse_iterator<iterator>}}}}
-{{dsc|{{tt|reverse_const_iterator}}{{mark c++23}}|{{c|std::reverse_iterator<const_iterator>}}}}
+{{dsc|{{tt|reverse_const_iterator}}{{mark c++23}}|{{co|std::reverse_iterator<const_iterator>}}}}
 {{dsc|{{tt|difference_type}}{{mark c++23}}|implementation-defined signed integer type}}
 {{dsc|{{tt|size_type}}{{mark c++23}}|implementation-defined unsigned integer type}}
@@ Line 71: / Line 71: @@
 {{dsc h2|Element access}}
 {{dsc inc|cpp/utility/basic_stacktrace/dsc operator at}}
 {{dsc inc|cpp/utility/basic_stacktrace/dsc at}}
@@ Line 99: / Line 98: @@
 {{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.
-{{feature test macro|__cpp_lib_stacktrace|std=C++23|value=202011L|[[#Top|Stacktrace]] library}}
+{{feature test macro|__cpp_lib_stacktrace|std=C++23|value=202011L|[[#top|Stacktrace]] library}}
 ===Example===
@@ Line 110: / Line 109: @@
 {
      std::cout << std::stacktrace::current() << '\n';
-     return c+1;
+     return c + 1;
 }
-int func(int b) {
+int func(int b)
-     return nested_func(b+1);
+{
+     return nested_func(b + 1);
 }
-int main() {
+int main()
+{
      std::cout << func(777);
 }

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"

Revision as of 14:34, 19 February 2023

Contents

Template parameters

Member types

Member functions

Iterators

Capacity

Element access

Modifiers

Non-member functions

Helper classes

Notes

Example

See also

Navigation

Toolbox