[stacktrace] (original) (raw)

19 Diagnostics library [diagnostics]

19.6.1 General [stacktrace.general]

Subclause [stacktrace] describes components that C++ programs may use to store the stacktrace of the current thread of execution and query information about the stored stacktrace at runtime.

The invocation sequence of the current evaluation in the current thread of execution is a sequence of evaluations such that, for i ≥ 0, is within the function invocation ([intro.execution]).

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

A stacktrace entry represents an evaluation in a stacktrace.

19.6.3 Class stacktrace_entry [stacktrace.entry]

19.6.3.1 Overview [stacktrace.entry.overview]

namespace std { class stacktrace_entry { public: using native_handle_type = implementation-defined;constexpr stacktrace_entry() noexcept;constexpr stacktrace_entry(const stacktrace_entry& other) noexcept;constexpr stacktrace_entry& operator=(const stacktrace_entry& other) noexcept;~stacktrace_entry();constexpr native_handle_type native_handle() const noexcept;constexpr explicit operator bool() const noexcept; string description() const; string source_file() const; uint_least32_t source_line() const;friend constexpr bool operator==(const stacktrace_entry& x,const stacktrace_entry& y) noexcept;friend constexpr strong_ordering operator<=>(const stacktrace_entry& x,const stacktrace_entry& y) noexcept;};}

19.6.3.2 Constructors [stacktrace.entry.cons]

constexpr stacktrace_entry() noexcept;

Postconditions: *this is empty.

19.6.3.3 Observers [stacktrace.entry.obs]

constexpr native_handle_type native_handle() const noexcept;

The semantics of this function areimplementation-defined.

Remarks: Successive invocations of the native_handle function for an unchanged stacktrace_entry object return identical values.

constexpr explicit operator bool() const noexcept;

Returns: false if and only if *this is empty.

19.6.3.4 Query [stacktrace.entry.query]

[Note 1:

All the stacktrace_entry query functions treat errors other than memory allocation errors as “no information available” and do not throw in that case.

— _end note_]

string description() const;

Returns: A description of the evaluation represented by *this, or an empty string.

Throws: bad_alloc if memory for the internal data structures or the resulting string cannot be allocated.

string source_file() const;

Returns: The presumed or actual name of the source file ([cpp.predefined]) that lexically contains the expression or statement whose evaluation is represented by *this, or an empty string.

Throws: bad_alloc if memory for the internal data structures or the resulting string cannot be allocated.

uint_least32_t source_line() const;

Returns: 0, or a 1-based line number that lexically relates to the evaluation represented by *this.

If source_file returns the presumed name of the source file, returns the presumed line number; if source_file returns the actual name of the source file, returns the actual line number.

Throws: bad_alloc if memory for the internal data structures cannot be allocated.

19.6.3.5 Comparison [stacktrace.entry.cmp]

friend constexpr bool operator==(const stacktrace_entry& x, const stacktrace_entry& y) noexcept;

Returns: true if and only if x and y represent the same stacktrace entry or both x and y are empty.

19.6.4 Class template basic_stacktrace [stacktrace.basic]

19.6.4.1 Overview [stacktrace.basic.overview]

namespace std { template<class Allocator> class basic_stacktrace { public: using value_type = stacktrace_entry;using const_reference = const value_type&;using reference = value_type&;using const_iterator = implementation-defined; using iterator = const_iterator;using reverse_iterator = std::reverse_iterator<iterator>;using const_reverse_iterator = std::reverse_iterator<const_iterator>;using difference_type = implementation-defined;using size_type = implementation-defined;using allocator_type = Allocator;static basic_stacktrace current(const allocator_type& alloc = allocator_type()) noexcept;static basic_stacktrace current(size_type skip,const allocator_type& alloc = allocator_type()) noexcept;static basic_stacktrace current(size_type skip, size_type max_depth,const allocator_type& alloc = allocator_type()) noexcept; basic_stacktrace() noexcept(is_nothrow_default_constructible_v<allocator_type>);explicit basic_stacktrace(const allocator_type& alloc) noexcept; basic_stacktrace(const basic_stacktrace& other); basic_stacktrace(basic_stacktrace&& other) noexcept; basic_stacktrace(const basic_stacktrace& other, const allocator_type& alloc); basic_stacktrace(basic_stacktrace&& other, const allocator_type& alloc); basic_stacktrace& operator=(const basic_stacktrace& other); basic_stacktrace& operator=(basic_stacktrace&& other) noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value || allocator_traits<Allocator>::is_always_equal::value);~basic_stacktrace(); allocator_type get_allocator() const noexcept; const_iterator begin() const noexcept; const_iterator end() const noexcept; const_reverse_iterator rbegin() const noexcept; const_reverse_iterator rend() const noexcept; const_iterator cbegin() const noexcept; const_iterator cend() const noexcept; const_reverse_iterator crbegin() const noexcept; const_reverse_iterator crend() const noexcept;bool empty() const noexcept; size_type size() const noexcept; size_type max_size() const noexcept; const_reference operator[](size_type) const; const_reference at(size_type) const;template<class Allocator2> friend bool operator==(const basic_stacktrace& x,const basic_stacktrace<Allocator2>& y) noexcept;template<class Allocator2> friend strong_ordering operator<=>(const basic_stacktrace& x,const basic_stacktrace<Allocator2>& y) noexcept;void swap(basic_stacktrace& other) noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value || allocator_traits<Allocator>::is_always_equal::value);private: vector<value_type, allocator_type> frames_; };}

The class template basic_stacktrace satisfies the requirements of a reversible container ([container.rev.reqmts]), of an allocator-aware container ([container.alloc.reqmts]), and of a sequence container ([sequence.reqmts]), except that

• only move, assignment, swap, and operations defined for const-qualified sequence containers are supported and,
• the semantics of comparison functions are different from those required for a container.

19.6.4.2 Creation and assignment [stacktrace.basic.cons]

static basic_stacktrace current(const allocator_type& alloc = allocator_type()) noexcept;

Returns: A basic_stacktrace object with frames_ storing the stacktrace of the current evaluation in the current thread of execution, or an empty basic_stacktrace object if the initialization of frames_ failed.

alloc is passed to the constructor of the frames_ object.

[Note 1:

If the stacktrace was successfully obtained, then frames_.front() is the stacktrace_entryrepresenting approximately the current evaluation, and_frames__.back() is the stacktrace_entryrepresenting approximately the initial function of the current thread of execution.

— _end note_]

static basic_stacktrace current(size_type skip,const allocator_type& alloc = allocator_type()) noexcept;

Let t be a stacktrace as-if obtained via basic_stacktrace​::​current(alloc).

Let n be t.size().

Returns: A basic_stacktrace object where frames_ is direct-non-list-initialized from argumentst.begin() + min(n, skip), t.end(), and alloc, or an empty basic_stacktrace object if the initialization of frames_ failed.

static basic_stacktrace current(size_type skip, size_type max_depth,const allocator_type& alloc = allocator_type()) noexcept;

Let t be a stacktrace as-if obtained via basic_stacktrace​::​current(alloc).

Let n be t.size().

Preconditions: skip <= skip + max_depth is true.

Returns: A basic_stacktrace object where frames_ is direct-non-list-initialized from argumentst.begin() + min(n, skip), t.begin() + min(n, skip + max_depth), and alloc, or an empty basic_stacktrace object if the initialization of frames_ failed.

basic_stacktrace() noexcept(is_nothrow_default_constructible_v<allocator_type>);

Postconditions: empty() is true.

explicit basic_stacktrace(const allocator_type& alloc) noexcept;

Effects: alloc is passed to the frames_ constructor.

Postconditions: empty() is true.

basic_stacktrace(const basic_stacktrace& other); basic_stacktrace(const basic_stacktrace& other, const allocator_type& alloc); basic_stacktrace(basic_stacktrace&& other, const allocator_type& alloc); basic_stacktrace& operator=(const basic_stacktrace& other); basic_stacktrace& operator=(basic_stacktrace&& other) noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value || allocator_traits<Allocator>::is_always_equal::value);

Remarks: Implementations may strengthen the exception specification for these functions ([res.on.exception.handling]) by ensuring that empty() is true on failed allocation.

19.6.4.3 Observers [stacktrace.basic.obs]

using const_iterator = _implementation-defined_;

allocator_type get_allocator() const noexcept;

Returns: frames_.get_allocator().

const_iterator begin() const noexcept; const_iterator cbegin() const noexcept;

Returns: An iterator referring to the first element in frames_.

If empty() is true, then it returns the same value as end().

const_iterator end() const noexcept; const_iterator cend() const noexcept;

Returns: The end iterator.

const_reverse_iterator rbegin() const noexcept; const_reverse_iterator crbegin() const noexcept;

Returns: reverse_iterator(cend()).

const_reverse_iterator rend() const noexcept; const_reverse_iterator crend() const noexcept;

Returns: reverse_iterator(cbegin()).

bool empty() const noexcept;

Returns: frames_.empty().

size_type size() const noexcept;

size_type max_size() const noexcept;

Returns: frames_.max_size().

const_reference operator[](size_type frame_no) const;

Preconditions: frame_no < size() is true.

Returns: _frames__[frame_no].

const_reference at(size_type frame_no) const;

Returns: _frames__[frame_no].

Throws: out_of_range if frame_no >= size().

19.6.4.4 Comparisons [stacktrace.basic.cmp]

template<class Allocator2> friend bool operator==(const basic_stacktrace& x, const basic_stacktrace<Allocator2>& y) noexcept;

Returns: equal(x.begin(), x.end(), y.begin(), y.end()).

template<class Allocator2> friend strong_orderingoperator<=>(const basic_stacktrace& x, const basic_stacktrace<Allocator2>& y) noexcept;

Returns: x.size() <=> y.size() if x.size() != y.size();lexicographical_compare_three_way(x.begin(), x.end(), y.begin(), y.end())otherwise.

19.6.4.5 Modifiers [stacktrace.basic.mod]

void swap(basic_stacktrace& other) noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value || allocator_traits<Allocator>::is_always_equal::value);

Effects: Exchanges the contents of *this and other.

19.6.4.6 Non-member functions [stacktrace.basic.nonmem]

template<class Allocator> void swap(basic_stacktrace<Allocator>& a, basic_stacktrace<Allocator>& b) noexcept(noexcept(a.swap(b)));

Effects: Equivalent to a.swap(b).

string to_string(const stacktrace_entry& f);

Returns: A string with a description of f.

Recommended practice: The description should provide information about the contained evaluation, including information fromf.source_file() and f.source_line().

template<class Allocator>string to_string(const basic_stacktrace<Allocator>& st);

Returns: A string with a description of st.

[Note 1:

The number of lines is not guaranteed to be equal to st.size().

— _end note_]

ostream& operator<<(ostream& os, const stacktrace_entry& f);

Effects: Equivalent to: return os << to_string(f);

template<class Allocator> ostream& operator<<(ostream& os, const basic_stacktrace<Allocator>& st);

Effects: Equivalent to: return os << to_string(st);

19.6.5 Formatting support [stacktrace.format]

template<> struct formatter<stacktrace_entry>;

formatter<stacktrace_entry> interprets _format-spec_as a stacktrace-entry-format-spec.

The syntax of format specifications is as follows:

stacktrace-entry-format-spec :
fill-and-align width

[Note 1:

The productions fill-and-align and _width_are described in [format.string.std].

— _end note_]

A stacktrace_entry object se is formatted as if by copying to_string(se) through the output iterator of the context with additional padding and adjustments as specified by the format specifiers.

template<class Allocator> struct formatter<basic_stacktrace<Allocator>>;

For formatter<basic_stacktrace<Allocator>>,format-spec is empty.

A basic_stacktrace<Allocator> object s is formatted as if by copying to_string(s) through the output iterator of the context.

19.6.6 Hash support [stacktrace.basic.hash]

template<> struct hash<stacktrace_entry>;template<class Allocator> struct hash<basic_stacktrace<Allocator>>;