Added Forty Thieves

[wxWidgets.git] / docs / latex / wx / tdebug.tex

\section{Debugging overview}\label{debuggingoverview}

Classes: \helpref{wxDebugContext}{wxdebugcontext}, \helpref{wxDebugStreamBuf}{wxdebugstreambuf},
\rtfsp\helpref{wxObject}{wxobject}

Various classes, functions and macros are provided in wxWindows to help you debug
your application. Most of these are only available if you compile both wxWindows,
your application and {\it all} libraries that use wxWindows with the DEBUG flag
set to 1 or more.

wxDebugContext is a class that never gets instantiated, but ties together
various functions and variables. It allows you to set the debugging stream, dump
all objects to that stream, write statistics about object allocation, and
check memory for errors.

You can use the \helpref{WXTRACE}{trace} macro to output debugging information in DEBUG mode;
it will be defined to nothing for non-debugging code.

It is good practice to define a Dump member function for each class you derive
from a wxWindows class, so that wxDebugContext::Dump can call it and
give valuable information about the state of the application.

For wxDebugContext to do its work, the {\it new} and {\it delete}\rtfsp
operators for wxObject have been redefined to store extra information
about dynamically allocated objects (but not statically declared
objects). This slows down a debugging version of an application, but can
in theory find difficult-to-detect memory leaks (objects are not
deallocated), overwrites (writing past the end of your object) and
underwrites (writing to memory in front of the object).

If you have difficulty tracking down a memory leak, recompile
in debugging mode and call wxDebugContext::Dump and wxDebugContext::Statistics
at appropriate places. They will tell you what objects have not yet been
deleted, and what kinds of object they are.

If you use the macro WXDEBUG\_NEW instead of the normal 'new', the debugging
output (and error messages reporting memory problems) will also tell you what
file and on what line you allocated the object.

To avoid the need for replacing existing new operators with WXDEBUG\_NEW, you
can write this at the top of each application file:

\begin{verbatim}
#define new WXDEBUG\_NEW
\end{verbatim}

In non-debugging mode, this will revert to the usual interpretation
of new. Note that for this not to mess up new-based allocation of non-wxObject derived classes and
built-in types, there are global definitions of new and delete which match
the syntax required for storing filename and line numbers. These merely
call malloc and free, and so do not do anything interesting. The definitions
may possibly cause multiple symbol problems for some compilers and so might
need to be omitted by setting the USE\_GLOBAL\_MEMORY\_OPERATORS to 0 in wx\_setup.h

\subsection{wxDebugContext overview}\label{wxdebugcontextoverview}

\overview{Debugging overview}{debuggingoverview}

Class: \helpref{wxDebugContext}{wxdebugcontext}

wxDebugContext is a class for performing various debugging and memory tracing
operations. wxDebugContext, and the related macros and function WXTRACE and
wxTrace, are only present if USE\_DEBUG\_CONTEXT is used.

This class has only static data and function members, and there should be
no instances. Probably the most useful members are SetFile (for directing output
to a file, instead of the default standard error or debugger output);
Dump (for dumping the dynamically allocated objects) and PrintStatistics
(for dumping information about allocation of objects). You can also call
Check to check memory blocks for integrity.

Here's an example of use. The SetCheckpoint ensures that only the
allocations done after the checkpoint will be dumped. Unfortunately
the define of new to WXDEBUG\_NEW does not work for Borland C++ (and
perhaps other compilers) because it fails to find the correct overloaded
operator for non-object usage of new. Instead, you need to use WXDEBUG\_NEW
explicitly if there are any examples of non-object new usage in the file.

\begin{verbatim}
#define new WXDEBUG_NEW

  wxDebugContext::SetCheckpoint();

  wxDebugContext::SetFile("c:\\temp\\debug.log");

  wxString *thing = new wxString;

  // Proves that defining 'new' to be 'WXDEBUG_NEW' doesn't mess up
  // non-object allocation. Doesn't work for Borland C++.
  char *ordinaryNonObject = new char[1000];

  wxDebugContext::Dump();
  wxDebugContext::PrintStatistics();
\end{verbatim}

You can use wxDebugContext if DEBUG is 1 or more, or you can use it
at any other time (if USE\_DEBUG\_CONTEXT is 1). It is not disabled
for DEBUG = 1 (as in earlier versions of wxWindows) because you
may not wish to recompile wxWindows and your entire application
just to make use of the error logging facility. This is especially
true in a Windows NT or Windows 95 environment, where you cannot
easily output to a debug window: wxDebugContext can be used to
write to log files instead.