| Home | Libraries | People | FAQ | More

## 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 &&);
      ~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 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());
    };

## Description

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

### Template Parameters

1.     typename Allocator

   Allocator to use during stack capture.

### `basic_stacktrace` public construct/copy/destruct

1.     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: Safe if Allocator construction, copying, Allocator::allocate and Allocator::deallocate are async signal safe.

2.     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: Safe if Allocator construction, copying, Allocator::allocate and Allocator::deallocate are async signal safe.

   Parameters:

   `a` | Allocator that would be passed to underlying storeage.

3.     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: Safe if Allocator construction, copying, Allocator::allocate and Allocator::deallocate are async signal safe.

   Parameters:

   `a` | Allocator that would be passed to underlying storeage.
   `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`.

4.     basic_stacktrace(const basic_stacktrace & st);

   Complexity: O(st.size())

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

5.     basic_stacktrace(basic_stacktrace && st) noexcept;

   Complexity: O(1)

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

6.     basic_stacktrace & operator=(const basic_stacktrace & st);

   Complexity: O(st.size())

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

7.     basic_stacktrace & operator=(basic_stacktrace && st);

   Complexity: O(st.size())

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

8.     ~basic_stacktrace();

   Complexity: O(1)

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

### `basic_stacktrace` public member functions

1.     size_type size() const noexcept;

   Complexity: O(1)

   Async-Handler-Safety: Safe.

   Returns: | Number of function names stored inside the class.

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

   Complexity: O(1).

   Async-Handler-Safety: 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.

3.     const_iterator begin() const noexcept;

   Complexity: O(1)

   Async-Handler-Safety: Safe.

4.     const_iterator cbegin() const noexcept;

   Complexity: O(1)

   Async-Handler-Safety: Safe.

5.     const_iterator end() const noexcept;

   Complexity: O(1)

   Async-Handler-Safety: Safe.

6.     const_iterator cend() const noexcept;

   Complexity: O(1)

   Async-Handler-Safety: Safe.

7.     const_reverse_iterator rbegin() const noexcept;

   Complexity: O(1)

   Async-Handler-Safety: Safe.

8.     const_reverse_iterator crbegin() const noexcept;

   Complexity: O(1)

   Async-Handler-Safety: Safe.

9.     const_reverse_iterator rend() const noexcept;

   Complexity: O(1)

   Async-Handler-Safety: Safe.

10.     const_reverse_iterator crend() const noexcept;

    Complexity: O(1)

    Async-Handler-Safety: Safe.

11.     explicit operator bool() const noexcept;

    Allows to check that stack trace capturing was successful.

    Complexity: O(1)

    Async-Handler-Safety: Safe.

    Returns: | `true` if `this->size() != 0`

12.     bool empty() const noexcept;

    Allows to check that stack trace failed.

    Complexity: O(1)

    Async-Handler-Safety: Safe.

    Returns: | `true` if `this->size() == 0`

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

### `basic_stacktrace` public static functions

1.     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)

2.     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` | Begining 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