Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

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


PrevUpHomeNext