ceph/src/boost/boost/test/debug.hpp

   1 //  (C) Copyright Gennadiy Rozental 2001.
   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 //  See http://www.boost.org/libs/test for the library home page.
   7 //
   8 //! @file
   9 //! @brief defines portable debug interfaces
  10 //!
  11 //! Intended to standardize interface of programs with debuggers
  12 // ***************************************************************************
  13
  14 #ifndef BOOST_TEST_DEBUG_API_HPP_112006GER
  15 #define BOOST_TEST_DEBUG_API_HPP_112006GER
  16
  17 // Boost.Test
  18 #include <boost/test/detail/config.hpp>
  19 #include <boost/test/utils/basic_cstring/basic_cstring.hpp>
  20
  21 // Boost
  22 #include <boost/function/function1.hpp>
  23
  24 // STL
  25 #include <string>
  26
  27 #include <boost/test/detail/suppress_warnings.hpp>
  28
  29 //____________________________________________________________________________//
  30
  31 namespace boost {
  32 /// Contains debugger and debug C Runtime interfaces
  33 namespace debug {
  34
  35 /// @defgroup DebuggerInterface Debugger and debug C Runtime portable interfaces
  36 /// @{
  37 /// These interfaces are intended to be used by application to:
  38 /// - check if we are running under debugger
  39 /// - attach the debugger to itself
  40 ///
  41 /// Unfortunately these actions differ widely between different debuggers available in a field. These interface present generalized standard form of
  42 /// performing these actions. Implementation depends a lot on the environment application is running in and thus there are several custom implementations
  43 /// supported by the Boost.Test
  44 ///
  45 /// In addition here you find interfaces for memory leaks detection and reporting.
  46 ///
  47 /// All these interfaces are defined in namespace boost::debug
  48
  49 // ************************************************************************** //
  50 /// Checks if programs runs under debugger
  51
  52 /// @returns true if current process is under debugger. False otherwise
  53 // ************************************************************************** //
  54 bool BOOST_TEST_DECL under_debugger();
  55
  56 // ************************************************************************** //
  57 /// Cause program to break execution in debugger at call point
  58 // ************************************************************************** //
  59
  60 void BOOST_TEST_DECL debugger_break();
  61
  62 // ************************************************************************** //
  63 /// Collection of data, which is used by debugger starter routine
  64 // ************************************************************************** //
  65
  66 struct dbg_startup_info {
  67     long                    pid;                ///< pid of a program to attach to
  68     bool                    break_or_continue;  ///< what to do after debugger is attached
  69     unit_test::const_string binary_path;        ///< path to executable for current process
  70     unit_test::const_string display;            ///< if debugger has a GUI, which display to use (on UNIX)
  71     unit_test::const_string init_done_lock;     ///< path to a uniquely named lock file, which is used to pause current application while debugger is being initialized
  72 };
  73
  74 /// Signature of debugger starter routine. Takes an instance of dbg_startup_into as only argument
  75 typedef boost::function<void (dbg_startup_info const&)> dbg_starter;
  76
  77 // ************************************************************************** //
  78 /// Specifies which debugger to use when attaching and optionally what routine to use to start that debugger
  79
  80 /// There are  many different debuggers available for different platforms. Some of them also can be used in a different setups/configuratins.
  81 /// For example, gdb can be used in plain text mode, inside ddd, inside (x)emacs or in a separate xterm window.
  82 /// Boost.Test identifies each configuration with unique string.
  83 /// Also different debuggers configurations require different routines which is specifically tailored to start that debugger configuration.
  84 /// Boost.Test comes with set of predefined configuration names and corresponding routines for these configurations:
  85 ///   - TODO
  86 ///
  87 /// You can use this routine to select which one of the predefined debugger configurations to use in which case you do not need to provide starter
  88 /// routine (the one provided by Boost.Test will be used). You can also use this routine to select your own debugger by providing unique configuration
  89 /// id and starter routine for this configuration.
  90 ///
  91 /// @param[in] dbg_id   Unique id for debugger configuration (for example, gdb)
  92 /// @param[in] s        Optional starter routine for selected configuration (use only you want to define your own configuration)
  93 /// @returns            Id of previously selected debugger configuration
  94 std::string BOOST_TEST_DECL set_debugger( unit_test::const_string dbg_id, dbg_starter s = dbg_starter() );
  95
  96 // ************************************************************************** //
  97 /// Attaches debugger to the current process
  98
  99 /// Using  currently selected debugger, this routine attempts to attach the debugger to this process.
 100 /// @param[in] break_or_continue tells what we wan to do after the debugger is attached. If true - process execution breaks
 101 ///                              in the point in invocation of this function. Otherwise execution continues, but now it is
 102 ///                              under the debugger
 103 /// @returns true if debugger successfully attached. False otherwise
 104 // ************************************************************************** //
 105
 106 bool BOOST_TEST_DECL attach_debugger( bool break_or_continue = true );
 107
 108 // ************************************************************************** //
 109 /// Switches on/off memory leaks detection
 110
 111 /// On platforms where memory leak detection is possible inside of running application (at the moment this is only Windows family) you can
 112 /// switch this feature on and off using this interface. In addition you can specify the name of the file to write a report into. Otherwise
 113 /// the report is going to be generated in standard error stream.
 114 /// @param[in] on_off boolean switch
 115 /// @param[in] report_file file, where the report should be directed to
 116 // ************************************************************************** //
 117
 118 void BOOST_TEST_DECL detect_memory_leaks( bool on_off, unit_test::const_string report_file = unit_test::const_string() );
 119
 120 // ************************************************************************** //
 121 /// Causes program to break execution in debugger at specific allocation point
 122
 123 /// On some platforms/memory managers (at the moment only on Windows/Visual Studio) one can tell a C Runtime to break
 124 /// on specific memory allocation. This can be used in combination with memory leak detection (which reports leaked memory
 125 /// allocation number) to locate the place where leak initiated.
 126 /// @param[in] mem_alloc_order_num Specific memory allocation number
 127 // ************************************************************************** //
 128
 129 void BOOST_TEST_DECL break_memory_alloc( long mem_alloc_order_num );
 130
 131 } // namespace debug
 132 /// @}
 133
 134 } // namespace boost
 135
 136 #include <boost/test/detail/enable_warnings.hpp>
 137
 138 #endif