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
31namespace boost {
32/// Contains debugger and debug C Runtime interfaces
33namespace 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// ************************************************************************** //
54bool BOOST_TEST_DECL under_debugger();
55
56// ************************************************************************** //
57/// Cause program to break execution in debugger at call point
58// ************************************************************************** //
59
60void BOOST_TEST_DECL debugger_break();
61
62// ************************************************************************** //
63/// Collection of data, which is used by debugger starter routine
64// ************************************************************************** //
65
66struct 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
75typedef 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
94std::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
106bool 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
118void 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
129void 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

source code of include/boost/test/debug.hpp