home | help 
std::basic_stacktrace(3)       C++ Standard Libary	std::basic_stacktrace(3)

NAME
     std::basic_stacktrace - std::basic_stacktrace

Synopsis
      Defined in header <stacktrace>
      template< 		class		      Allocator 	       >
     (1) (since
      class						       basic_stacktrace;
     C++23)
      using				stacktrace			       =
     (2) (since
	  std::basic_stacktrace<std::allocator<std::stacktrace_entry>>;
     C++23)
      namespace pmr {

      using				stacktrace			       =
     (since
										     (3)
     C++23)
      std::basic_stacktrace<std::pmr::polymorphic_allocator<std::stacktrace_en-
     try>>;

      }

	1)  The  basic_stacktrace  class  template  represents a snapshot of the
     whole stacktrace
	or its given part. It satisfies the  requirement  of  AllocatorAwareCon-
     tainer,
	SequenceContainer,  and  ReversibleContainer, except that only move, as-
     signment, 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}\)iaY0,
	\(\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 rep-
     resented by
	std::stacktrace_entry in the C++ standard library.

Template parameters
		    An allocator that is used to acquire/release memory and to
	Allocator - 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.

Member types
	Member type	       Definition
	value_type	       std::stacktrace_entry
	const_reference        const value_type&
	reference	       value_type&
	const_iterator	       implementation-defined  const  LegacyRandomAcces-
     sIterator 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

Member functions
	constructor   creates a new basic_stacktrace
		      (public member function)
	destructor    destroys the basic_stacktrace
		      (public member function)
	operator=     assigns to the basic_stacktrace
		      (public member function)
	current       obtains the current stacktrace or its given part
	[static]      (public static member function)
	get_allocator returns the associated allocator
		      (public member function)

Iterators
	begin	      returns an iterator to the beginning
	cbegin	      (public member function)
	end	      returns an iterator to the end
	cend	      (public member function)
	rbegin	      returns a reverse iterator to the beginning
	crbegin       (public member function)
	rend	      returns a reverse iterator to the end
	crend	      (public member function)

Capacity
	empty	      checks whether the basic_stacktrace is empty
		      (public member function)
	size	      returns the number of stacktrace entries
		      (public member function)
	max_size      returns the maximum possible number of stacktrace entries
		      (public member function)

Element access
	operator[]    access specified stacktrace entry
		      (public member function)
	at	      access specified stacktrace entry with bounds checking
		      (public member function)

Modifiers
	swap	      swaps the contents
		      (public member function)

Non-member functions
	operator==			  compares the sizes and the contents of
     two
	operator<=>			 basic_stacktrace values
	(C++23) 			 (function template)
	std::swap(std::basic_stacktrace) specializes the std::swap algorithm
	(C++23) 			 (function template)
	to_string			 returns a string with a description  of
     the
	(C++23) 			 basic_stacktrace
					 (function template)
	operator<<			 performs stream output of basic_strack-
     trace
	(C++23) 			 (function template)

Helper classes
	std::hash<std::basic_stacktrace>      hash support for std::basic_stack-
     trace
	(C++23) 			      (class template specialization)
	std::formatter<std::basic_stacktrace>	formatting   support   for   ba-
     sic_stacktrace
	(C++23) 			      (class template specialization)

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::ba-
     sic_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 (the lines ending with 'ax<paragraph>' arrows are split to
     fit the width):
      0>   C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-
     compiler20221122-ax<paragraph>
      31624-2ja1sf.8ytzw\example.cpp(6): output_s!nested_func+0x1F
      1>   C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-
     compiler20221122-ax<paragraph>
      31624-2ja1sf.8ytzw\example.cpp(12): output_s!func+0x15
      2>   C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-
     compiler20221122-ax<paragraph>
      31624-2ja1sf.8ytzw\example.cpp(15): output_s!main+0xE
      3>	   D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_com-
     mon.inl(288): output_s!ax<paragraph>
      __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
	stacktrace_entry representation of an evaluation in a stacktrace
	(C++23) 	 (class)

http://cppreference.com 	   2024.06.10		std::basic_stacktrace(3)
home | help