src/lib/stack.hpp

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