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

Revision as of 09:51, 1 May 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]
std::formatter<std::basic_stacktrace> (C++23)	formatting support for `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
`__cpp_lib_formatters`	202302L	(C++23)	Formatting std::thread::id and std::stacktrace

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:
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

@@ Line 99: / Line 99: @@
 {{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.
-===Notes===
 {{ftm begin|std=1|comment=1}}
 {{ftm|__cpp_lib_stacktrace|std=C++23|value=202011L|[[#top|Stacktrace]] library}}

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 09:51, 1 May 2023

Contents

Template parameters

Member types

Member functions

Iterators

Capacity

Element access

Modifiers

Non-member functions

Helper classes

Notes

Example

See also

Navigation

Toolbox