Class template basic_stacktrace

boost::stacktrace::basic_stacktrace

Synopsis

// In header: <boost/stacktrace/stacktrace.hpp>

template<typename Allocator> 
class basic_stacktrace {
public:
  // types
  typedef std::vector< boost::stacktrace::frame, Allocator >::value_type             value_type;            
  typedef std::vector< boost::stacktrace::frame, Allocator >::allocator_type         allocator_type;        
  typedef std::vector< boost::stacktrace::frame, Allocator >::const_pointer          pointer;               
  typedef std::vector< boost::stacktrace::frame, Allocator >::const_pointer          const_pointer;         
  typedef std::vector< boost::stacktrace::frame, Allocator >::const_reference        reference;             
  typedef std::vector< boost::stacktrace::frame, Allocator >::const_reference        const_reference;       
  typedef std::vector< boost::stacktrace::frame, Allocator >::size_type              size_type;             
  typedef std::vector< boost::stacktrace::frame, Allocator >::difference_type        difference_type;       
  typedef std::vector< boost::stacktrace::frame, Allocator >::const_iterator         iterator;              
  typedef std::vector< boost::stacktrace::frame, Allocator >::const_iterator         const_iterator;        
  typedef std::vector< boost::stacktrace::frame, Allocator >::const_reverse_iterator reverse_iterator;      
  typedef std::vector< boost::stacktrace::frame, Allocator >::const_reverse_iterator const_reverse_iterator;

  // construct/copy/destruct
  basic_stacktrace() noexcept;
  explicit basic_stacktrace(const allocator_type &) noexcept;
  basic_stacktrace(std::size_t, std::size_t, 
                   const allocator_type & = allocator_type()) noexcept;
  basic_stacktrace(const basic_stacktrace &);
  basic_stacktrace(basic_stacktrace &&) noexcept;
  basic_stacktrace & operator=(const basic_stacktrace &);
  basic_stacktrace & 
  operator=(basic_stacktrace &&) noexcept((std::is_nothrow_move_assignable< std::vector< boost::stacktrace::frame, Allocator > >::value));
  ~basic_stacktrace();

  // public member functions
  size_type size() const noexcept;
  const_reference operator[](std::size_t) const noexcept;
  const_iterator begin() const noexcept;
  const_iterator cbegin() const noexcept;
  const_iterator end() const noexcept;
  const_iterator cend() const noexcept;
  const_reverse_iterator rbegin() const noexcept;
  const_reverse_iterator crbegin() const noexcept;
  const_reverse_iterator rend() const noexcept;
  const_reverse_iterator crend() const noexcept;
  explicit constexpr operator bool() const noexcept;
  bool empty() const noexcept;
  const std::vector< boost::stacktrace::frame, Allocator > & 
  as_vector() const noexcept;

  // public static functions
  template<typename Char, typename Trait> 
    static basic_stacktrace 
    from_dump(std::basic_istream< Char, Trait > &, 
              const allocator_type & = allocator_type());
  static basic_stacktrace 
  from_dump(const void *, std::size_t, 
            const allocator_type & = allocator_type());
  static basic_stacktrace< Allocator > 
  from_current_exception(const allocator_type & = allocator_type()) noexcept;
};

Description

Class that on construction copies minimal information about call stack into its internals and provides access to that information.

Template Parameters

```
typename Allocator
```
Allocator to use during stack capture.

`basic_stacktrace` public construct/copy/destruct

```
basic_stacktrace() noexcept;
```
Stores the current function call sequence inside *this without any decoding or any other heavy platform specific operations.
Complexity: O(N) where N is call sequence length, O(1) if BOOST_STACKTRACE_USE_NOOP is defined.

Async-Handler-Safety: Theoretically async signal safe if Allocator construction, copying, Allocator::allocate and Allocator::deallocate are async signal safe.
```
explicit basic_stacktrace(const allocator_type & a) noexcept;
```
Stores the current function call sequence inside *this without any decoding or any other heavy platform specific operations.
Complexity: O(N) where N is call sequence length, O(1) if BOOST_STACKTRACE_USE_NOOP is defined.

Async-Handler-Safety: Theoretically async signal safe if Allocator construction, copying, Allocator::allocate and Allocator::deallocate are async signal safe.

Parameters:

a

Allocator that would be passed to underlying storage.

basic_stacktrace(std::size_t skip, std::size_t max_depth, 
                 const allocator_type & a = allocator_type()) noexcept;

Stores [skip, skip + max_depth) of the current function call sequence inside *this without any decoding or any other heavy platform specific operations.

Complexity: O(N) where N is call sequence length, O(1) if BOOST_STACKTRACE_USE_NOOP is defined.

Async-Handler-Safety: Theoretically async signal safe if Allocator construction, copying, Allocator::allocate and Allocator::deallocate are async signal safe.

Parameters:

`a`	Allocator that would be passed to underlying storage.
`max_depth`	Max call sequence depth to collect.
`skip`	How many top calls to skip and do not store in *this.

Throws:

Nothing. Note that default construction of allocator may throw, however it is performed outside the constructor and exception in allocator_type() would not result in calling std::terminate.

```
basic_stacktrace(const basic_stacktrace & st);
```
Complexity: O(st.size())

Async-Handler-Safety: Theoretically async signal safe if Allocator construction, copying, Allocator::allocate and Allocator::deallocate are async signal safe.
```
basic_stacktrace(basic_stacktrace && st) noexcept;
```
Complexity: O(1)

Async-Handler-Safety: Theoretically async signal safe if Allocator construction and copying are async signal safe.
```
basic_stacktrace & operator=(const basic_stacktrace & st);
```
Complexity: O(st.size())

Async-Handler-Safety: Theoretically async signal safe if Allocator construction, copying, Allocator::allocate and Allocator::deallocate are async signal safe.

basic_stacktrace & 
operator=(basic_stacktrace && st) noexcept((std::is_nothrow_move_assignable< std::vector< boost::stacktrace::frame, Allocator > >::value));

Complexity: O(st.size())

Async-Handler-Safety: Theoretically async signal safe if Allocator construction and copying are async signal safe.

```
~basic_stacktrace();
```
Complexity: O(1)

Async-Handler-Safety: Theoretically async signal safe if Allocator::deallocate is async signal safe.

`basic_stacktrace` public member functions

```
size_type size() const noexcept;
```
Complexity: O(1)

Async-Handler-Safety: Theoretically async signal safe .

Returns:

Number of function names stored inside the class.

const_reference operator[](std::size_t frame_no) const noexcept;

Complexity: O(1).

Async-Handler-Safety: Theoretically async signal safe .

Parameters:

frame_no

Zero based index of frame to return. 0 is the function index where stacktrace was constructed and index close to this->size() contains function main().

Returns:

frame that references the actual frame info, stored inside *this.

```
const_iterator begin() const noexcept;
```
Complexity: O(1)

Async-Handler-Safety: Theoretically async signal safe .
```
const_iterator cbegin() const noexcept;
```
Complexity: O(1)

Async-Handler-Safety: Theoretically async signal safe .
```
const_iterator end() const noexcept;
```
Complexity: O(1)

Async-Handler-Safety: Theoretically async signal safe .
```
const_iterator cend() const noexcept;
```
Complexity: O(1)

Async-Handler-Safety: Theoretically async signal safe .
```
const_reverse_iterator rbegin() const noexcept;
```
Complexity: O(1)

Async-Handler-Safety: Theoretically async signal safe .
```
const_reverse_iterator crbegin() const noexcept;
```
Complexity: O(1)

Async-Handler-Safety: Theoretically async signal safe .
```
const_reverse_iterator rend() const noexcept;
```
Complexity: O(1)

Async-Handler-Safety: Theoretically async signal safe .
```
const_reverse_iterator crend() const noexcept;
```
Complexity: O(1)

Async-Handler-Safety: Theoretically async signal safe .
```
explicit constexpr operator bool() const noexcept;
```
Allows to check that stack trace capturing was successful.
Complexity: O(1)

Async-Handler-Safety: Theoretically async signal safe .

Returns:

true if this->size() != 0
```
bool empty() const noexcept;
```
Allows to check that stack trace failed.
Complexity: O(1)

Async-Handler-Safety: Theoretically async signal safe .

Returns:

true if this->size() == 0

const std::vector< boost::stacktrace::frame, Allocator > & 
as_vector() const noexcept;

`basic_stacktrace` public static functions

template<typename Char, typename Trait> 
  static basic_stacktrace 
  from_dump(std::basic_istream< Char, Trait > & in, 
            const allocator_type & a = allocator_type());

Constructs stacktrace from basic_istreamable that references the dumped stacktrace. Terminating zero frame is discarded.

Complexity: O(N)

static basic_stacktrace 
from_dump(const void * begin, std::size_t buffer_size_in_bytes, 
          const allocator_type & a = allocator_type());

Constructs stacktrace from raw memory dump. Terminating zero frame is discarded.

Complexity: O(size) in worst case

Parameters:

`begin`	Beginning of the memory where the stacktrace was saved using the boost::stacktrace::safe_dump_to
`buffer_size_in_bytes`	Size of the memory. Usually the same value that was passed to the boost::stacktrace::safe_dump_to

```
static basic_stacktrace< Allocator > 
from_current_exception(const allocator_type & alloc = allocator_type()) noexcept;
```
Returns a basic_stacktrace object containing a stacktrace captured at the point where the currently handled exception was thrown by its initial throw-expression (i.e. not a rethrow), or an empty basic_stacktrace object if:
- the boost_stacktrace_from_exception library is not linked to the current binary, or
- the initialization of stacktrace failed, or
- stacktrace captures are not enabled for the throwing thread, or
- no exception is being handled, or
- due to implementation-defined reasons.
alloc is passed to the constructor of the stacktrace object. Rethrowing an exception using a throw-expression with no operand does not alter the captured stacktrace.

Implements https://wg21.link/p2370r1

Boost C++ Libraries