Namespaces
Variants
Views
Actions

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

From cppreference.com
< cpp‎ | utility
m (→‎Member functions: templatize)
m (fmt)
 
(20 intermediate revisions by 7 users not shown)
Line 2: Line 2:
 
{{cpp/utility/basic_stacktrace/navbar}}
 
{{cpp/utility/basic_stacktrace/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl header | stacktrace}}
+
{{dcl header|stacktrace}}
−
{{dcl | num=1 | since=c++23 |
+
{{dcl|num=1|since=c++23|
 
template< class Allocator >
 
template< class Allocator >
 
class basic_stacktrace;
 
class basic_stacktrace;
 
}}
 
}}
−
{{dcl | num=2 | since=c++23 | 1=
+
{{dcl|num=2|since=c++23|1=
 
using stacktrace =
 
using stacktrace =
 
     std::basic_stacktrace<std::allocator<std::stacktrace_entry>>;
 
     std::basic_stacktrace<std::allocator<std::stacktrace_entry>>;
 +
}}
 +
{{dcl|num=3|since=c++23|1=
 +
namespace pmr {
 +
using stacktrace =
 +
    std::basic_stacktrace<std::pmr::polymorphic_allocator<std::stacktrace_entry>>;
 +
}
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
Line 16: Line 22:
  
 
@2@ Convenience type alias for the {{tt|basic_stacktrace}} using the default {{lc|std::allocator}}.
 
@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 {{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>}}.
 
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 25: Line 33:
 
===Template parameters===
 
===Template parameters===
 
{{par begin}}
 
{{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}}
 
{{par end}}
  
 
===Member types===
 
===Member types===
 
{{dsc begin}}
 
{{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}}
 
{{dsc end}}
  
 
===Member functions===
 
===Member functions===
 
{{dsc begin}}
 
{{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 mem fun | cpp/utility/basic_stacktrace/begin | title=begin<br>cbegin | notes={{mark c++23}} | returns an iterator to the beginning}}
+
{{dsc inc|cpp/utility/basic_stacktrace/dsc begin}}
−
{{dsc mem fun | cpp/utility/basic_stacktrace/end | title=end<br>cend | notes={{mark c++23}} | returns an iterator to the end}}
+
{{dsc inc|cpp/utility/basic_stacktrace/dsc end}}
−
{{dsc mem fun | cpp/utility/basic_stacktrace/rbegin | title=rbegin<br>crbegin | notes={{mark c++23}} | returns a reverse iterator to the beginning}}
+
{{dsc inc|cpp/utility/basic_stacktrace/dsc rbegin}}
−
{{dsc mem fun | cpp/utility/basic_stacktrace/rend | title=rend<br>crend | notes={{mark c++23}} | returns a reverse iterator to the end}}
+
{{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}}
 
{{dsc end}}
  
 
===Non-member functions===
 
===Non-member functions===
 
{{dsc begin}}
 
{{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}}
 
{{dsc end}}
  
 
===Helper classes===
 
===Helper classes===
 
{{dsc begin}}
 
{{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}}
 
{{dsc end}}
  
 
===Notes===
 
===Notes===
 
Support for custom allocators is provided for using {{tt|basic_stacktrace}} on a hot path or in embedded environments. Users can allocate {{tt|stacktrace_entry}} objects on the stack or in some other place, where appropriate.
 
Support for custom allocators is provided for using {{tt|basic_stacktrace}} on a hot path or in embedded environments. Users can allocate {{tt|stacktrace_entry}} objects on the stack or in some other place, where appropriate.
 +
 +
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.
 +
 +
{{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}}
+
{{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):
 +
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
 +
}}
  
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/utility/dsc stacktrace_entry}}
+
{{dsc inc|cpp/utility/dsc stacktrace_entry}}
 
{{dsc end}}
 
{{dsc end}}
  
−
{{langlinks|es|ja|ru|zh}}
+
{{langlinks|de|es|ja|ru|zh}}

Latest revision as of 01:38, 1 January 2024

 
C++
 
Diagnostics library
 
std::basic_stacktrace
 
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 x0 in the current thread of execution is a sequence (x0, ..., xn) of evaluations such that, for i≥0, xi is within the function invocation xi+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.

Contents

[edit] Template parameters

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 Allocator. The program is ill-formed if Allocator::value_type is not std::stacktrace_entry.

[edit] Member types

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

 creates a new basic_stacktrace
(public member function) [edit]
destroys the basic_stacktrace
(public member function) [edit]
assigns to the basic_stacktrace
(public member function) [edit]
[static]
 obtains the current stacktrace or its given part
(public static member function) [edit]
returns the associated allocator
(public member function) [edit]
Iterators
returns an iterator to the beginning
(public member function) [edit]
returns an iterator to the end
(public member function) [edit]
returns a reverse iterator to the beginning
(public member function) [edit]
returns a reverse iterator to the end
(public member function) [edit]
Capacity
checks whether the basic_stacktrace is empty
(public member function) [edit]
returns the number of stacktrace entries
(public member function) [edit]
returns the maximum possible number of stacktrace entries
(public member function) [edit]
Element access
access specified stacktrace entry
(public member function) [edit]
access specified stacktrace entry with bounds checking
(public member function) [edit]
Modifiers
swaps the contents
(public member function) [edit]

[edit] Non-member functions

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

[edit] Helper classes

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

(C++23)
 representation of an evaluation in a stacktrace
(class) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/utility/basic_stacktrace&oldid=168072"