src/lib/stack.hpp

   1 // Copyright 2007 Edd Dawson.
   2 // Distributed under the Boost Software License, Version 1.0.
   3 // (See accompanying file LICENSE_1_0.txt or copy at
   4 // http://www.boost.org/LICENSE_1_0.txt)
   5
   6 #ifndef STACK_HPP_0022_01092007
   7 #define STACK_HPP_0022_01092007
   8
   9 #include <string>
  10 #include <list>
  11 #include <iosfwd>
  12
  13 namespace dbg
  14 {
  15     //! stack_frame objects are collected by a stack object. They contain information about the instruction pointer,
  16     //! the name of the corresponding function and the "module" (executable or library) in which the function resides.
  17     struct stack_frame
  18     {
  19         stack_frame(const void *instruction, const std::string &function, unsigned int line, const std::string &module);
  20
  21         const void *instruction;
  22         std::string function;
  23         unsigned int line;
  24         std::string module;
  25     };
  26
  27     //! Allows you to write a stack_frame object to an std::ostream
  28     std::ostream &operator<< (std::ostream &out, const stack_frame &frame);
  29
  30     //! Instantiate a dbg::stack object to collect information about the current call stack. Once created, a stack object
  31     //! may be freely copied about and will continue to contain the information about the scope in which collection occurred.
  32     class stack
  33     {
  34         public:
  35             typedef std::list<stack_frame>::size_type depth_type;
  36             typedef std::list<stack_frame>::const_iterator const_iterator;
  37
  38             //! Collect information about the current call stack. Information on the most recent frames will be collected
  39             //! up to the specified limit. 0 means unlimited.
  40             //! An std::runtime_error may be thrown on failure.
  41             stack(depth_type limit = 0);
  42
  43             //! Returns an iterator referring to the "top" stack frame
  44             const_iterator begin() const;
  45
  46             //! Returns an iterator referring to one past the "bottom" stack frame
  47             const_iterator end() const;
  48
  49             //! Returns the number of frames collected
  50             depth_type depth() const;
  51
  52         private:
  53             std::list<stack_frame> frames_;
  54     };
  55
  56 } // close namespace dbg
  57
  58 #endif // STACK_HPP_0022_01092007