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 139