Menu
▾
▴
[libcw-cvs] [CVS] Module src
|
From: Carlo W. <li...@us...> - 2001-12-02 01:01:46
|
CVSROOT : /cvsroot/libcw
Module : src
Branch tags: branch-threading
Commit time: 2001-11-02 01:01:42 UTC
Modified files:
Tag: branch-threading
libcwd/NEWS libcwd/bfd.cc libcwd/debug.cc libcwd/debugmalloc.cc
libcwd/demangle3.cc libcwd/documentation/custom-debug.h.dox
libcwd/documentation/custom_do.dox
libcwd/documentation/deallocation_pointer_validation.dox
libcwd/documentation/doxygen.config
libcwd/documentation/location.dox
libcwd/documentation/mainpage.dox
libcwd/documentation/memory_leak_checking.dox
libcwd/documentation/nested.dox
libcwd/documentation/preparation.dox libcwd/include/libcw/bfd.h
libcwd/include/libcw/buf2str.h libcwd/include/libcw/char2str.h
libcwd/include/libcw/class_alloc.h
libcwd/include/libcw/class_channel.h
libcwd/include/libcw/class_channel_set.h
libcwd/include/libcw/class_continued_channel.h
libcwd/include/libcw/class_debug.h
libcwd/include/libcw/class_debug_string.h
libcwd/include/libcw/class_fatal_channel.h
libcwd/include/libcw/class_location.h
libcwd/include/libcw/class_marker.h
libcwd/include/libcw/control_flag.h
libcwd/include/libcw/core_dump.h libcwd/include/libcw/cwprint.h
libcwd/include/libcw/debug.h
libcwd/include/libcw/debug_config.ho.in
libcwd/include/libcw/debugmalloc.h
libcwd/include/libcw/demangle.h
libcwd/include/libcw/enum_memblk_types.h
libcwd/include/libcw/lockable_auto_ptr.h
libcwd/include/libcw/macro_ForAllDebugChannels.h
libcwd/include/libcw/macro_ForAllDebugObjects.h
libcwd/include/libcw/macro_Libcwd_macros.h
libcwd/include/libcw/max_label_len.h
libcwd/include/libcw/pc_mangled_function_name.h
libcwd/include/libcw/private_TSD.h
libcwd/include/libcw/private_allocator.h
libcwd/include/libcw/private_assert.h
libcwd/include/libcw/private_debug_stack.h
libcwd/include/libcw/private_internal_string.h
libcwd/include/libcw/private_internal_stringstream.h
libcwd/include/libcw/private_internal_vector.h
libcwd/include/libcw/private_set_alloc_checking.h
libcwd/include/libcw/private_threading.h
libcwd/include/libcw/strerrno.h libcwd/include/libcw/sysd.ho.in
libcwd/include/libcw/type_info.h
Added files:
Tag: branch-threading
libcwd/documentation/alloc_intro.dox
libcwd/documentation/allocated_memory_overview.dox
libcwd/documentation/debug_channels.dox
libcwd/documentation/magic.dox libcwd/documentation/modules.dox
libcwd/documentation/why_macro.dox
libcwd/documentation/images/libcw_magic.gif
libcwd/include/libcw/macro_AllocTag.h
Removed files:
Tag: branch-threading
libcwd/documentation/reference.dox
Log message:
Work in progress. The structure of the documentation is reasonable now.
Most documentation is transfered.
---------------------- diff included ----------------------
Index: src/libcwd/NEWS
diff -u src/libcwd/NEWS:1.45.2.8 src/libcwd/NEWS:1.45.2.9
--- src/libcwd/NEWS:1.45.2.8 Thu Oct 11 21:15:49 2001
+++ src/libcwd/NEWS Sat Dec 1 17:01:30 2001
@@ -11,12 +11,16 @@
API changes:
- IMPORTANT: 'channel_ct const' -> 'channel_ct'.
- Debug channels should no longer be declared constant.
- Declarations like
+ IMPORTANT: Debug channels have globally been renamed to Debug
+ selectors. The word 'channel' had too much association with output
+ destinations (streams).
+
+ IMPORTANT: 'channel_ct const' -> 'selector_ct'.
+ Debug selectors (previously channels) should no longer be declared
+ constant. Declarations like
libcw::debug::channel_ct const my_channel("FOO");
will have to be changed to
- libcw::debug::channel_ct my_channel("FOO");
+ libcw::debug::selector_ct my_channel("FOO");
`long memblks()' has been renamed to `unsigned long mem_blocks()'.
Index: src/libcwd/bfd.cc
diff -u src/libcwd/bfd.cc:1.85.2.30 src/libcwd/bfd.cc:1.85.2.31
--- src/libcwd/bfd.cc:1.85.2.30 Tue Nov 20 18:23:17 2001
+++ src/libcwd/bfd.cc Sat Dec 1 17:01:30 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/bfd.cc,v 1.85.2.30 2001/11/21 02:23:17 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/bfd.cc,v 1.85.2.31 2001/12/02 01:01:30 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -97,7 +97,7 @@
// New debug channel
namespace channels {
namespace dc {
- /** /addtogroup default_dc */
+ /** \addtogroup group_default_dc */
/* \{ */
/** The BFD channel. */
@@ -1098,6 +1098,9 @@
} // namespace cwbfd
+ /** \addtogroup chapter_locations */
+ /** \{ */
+
char const* const unknown_function_c = "<unknown function>";
//
@@ -1121,6 +1124,8 @@
return symbol->get_symbol()->name;
}
+ /** \} */ // End of group 'chapter_locations'.
+
struct bfd_location_ct : public location_ct {
friend _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, bfd_location_ct const& data);
};
@@ -1374,6 +1379,14 @@
return *this;
}
+ /**
+ * \brief Write \a location to ostream \a os.
+ *
+ * Write the contents of a location_ct object to an ostream in
+ * the form source-%file:line-number, or writes "<unknown location>"
+ * when the location is unknown.
+ * \ingroup chapter_locations
+ */
std::ostream& operator<<(std::ostream& os, location_ct const& location)
{
if (location.M_filepath)
Index: src/libcwd/debug.cc
diff -u src/libcwd/debug.cc:1.46.2.38 src/libcwd/debug.cc:1.46.2.39
--- src/libcwd/debug.cc:1.46.2.38 Mon Nov 19 20:32:39 2001
+++ src/libcwd/debug.cc Sat Dec 1 17:01:30 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/debug.cc,v 1.46.2.38 2001/11/20 04:32:39 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/debug.cc,v 1.46.2.39 2001/12/02 01:01:30 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -146,7 +146,7 @@
}
/**
- * \brief The default %debug stream object.
+ * \brief The default %debug object.
*
* The %debug object that is used by default by Dout and DoutFatal, the only %debug object used by libcwd itself.
* \sa \ref custom_do
@@ -162,7 +162,7 @@
namespace channels {
namespace dc {
- /** \defgroup default_dc Pre-defined debug channels
+ /** \addtogroup group_default_dc Pre-Defined Debug Channels
*
* These are the default %debug %channels pre-defined in libcwd.
*/
@@ -990,14 +990,14 @@
return tmp;
}
- /** \interface list_channels_on debug.h libcw/debug.h
+ /** \fn void list_channels_on(debug_ct const& debug_object)
*
- * \brief List all %debug %channels to a given %debug stream object.
+ * \brief List all %debug %channels to a given %debug object.
*
- * \par Example:
+ * <b>Example:</b>
*
* \code
- * Dout( list_channels_on(libcw_do) ); // libcw_do is the (default) debug stream object of libcwd.
+ * Dout( list_channels_on(libcw_do) ); // libcw_do is the (default) debug object of libcwd.
* \endcode
*
* Example of output:
Index: src/libcwd/debugmalloc.cc
diff -u src/libcwd/debugmalloc.cc:1.61.2.44 src/libcwd/debugmalloc.cc:1.61.2.45
--- src/libcwd/debugmalloc.cc:1.61.2.44 Mon Nov 19 20:32:39 2001
+++ src/libcwd/debugmalloc.cc Sat Dec 1 17:01:30 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/debugmalloc.cc,v 1.61.2.44 2001/11/20 04:32:39 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/debugmalloc.cc,v 1.61.2.45 2001/12/02 01:01:30 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -1535,7 +1535,7 @@
return memblks;
}
-std::ostream& operator<<(std::ostream& o, debugmalloc_report_ct)
+std::ostream& operator<<(std::ostream& o, malloc_report_nt)
{
ACQUIRE_READ_LOCK
size_t memsize = const_dm_alloc_ct::get_memsize();
@@ -1545,18 +1545,24 @@
return o;
}
-/** \interface list_allocations_on debug.h libcw/debug.h
+/** \fn void list_allocations_on(debug_ct& debug_object)
*
- * \brief List all current allocations to a given %debug stream object.
+ * \brief List all current allocations to a given %debug object.
*
- * \par Example:
+ * With both, \link enable_libcwd_debugm DEBUGMALLOC \endlink and
+ * \link enable_libcwd_debug DEBUGDEBUG \endlink defined, it is possible
+ * to write the \ref chapter_overview "overview of allocated memory" to
+ * a \ref chapter_debug_object "Debug Object".
+ * The syntax to do this is:
*
* \code
- * Debug( list_allocations_on(libcw_do) ); // libcw_do is the (default) debug stream object of libcwd.
+ * Debug( list_allocations_on(libcw_do) ); // libcw_do is the (default) debug object.
* \endcode
*
- * output example here...
+ * which would print on \link libcw::debug::libcw_do libcw_do \endlink using
+ * \ref chapter_debug_channels "debug channel" \link libcw::debug::dc::malloc dc::malloc \endlink.
*
+ * \sa \ref chapter_overview
*/
void list_allocations_on(debug_ct& debug_object)
{
Index: src/libcwd/demangle3.cc
diff -u src/libcwd/demangle3.cc:1.8.2.17 src/libcwd/demangle3.cc:1.8.2.18
--- src/libcwd/demangle3.cc:1.8.2.17 Tue Nov 20 18:23:17 2001
+++ src/libcwd/demangle3.cc Sat Dec 1 17:01:31 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/demangle3.cc,v 1.8.2.17 2001/11/21 02:23:17 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/demangle3.cc,v 1.8.2.18 2001/12/02 01:01:31 libcw Exp $
//
// Copyright (C) 2001, by
//
@@ -12,7 +12,8 @@
//
/*!
-\defgroup demangle demangle_type() and demangle_symbol()
+\addtogroup group_demangle demangle_type() And demangle_symbol()
+\ingroup chapter_type_info
Libcwd comes with its own demangler functions.
@@ -26,8 +27,7 @@
by libbfd), which is what is returned by \ref location_ct::mangled_function_name()
and pc_mangled_function_name().
-The direct use of these functions should be avoided, instead use the
-function \ref type_info_of.
+The direct use of these functions should be avoided, instead use the function type_info_of().
*/
@@ -1993,7 +1993,7 @@
extern void demangle_symbol(char const* input, _private_::internal_string& output);
extern void demangle_type(char const* input, _private_::internal_string& output);
-/** \ingroup demangle */
+/** \ingroup group_demangle */
void demangle_symbol(char const* input, std::string& output)
{
LIBCWD_TSD_DECLARATION
@@ -2008,7 +2008,7 @@
_private_::set_alloc_checking_on(LIBCWD_TSD);
}
-/** \ingroup demangle */
+/** \ingroup group_demangle */
void demangle_type(char const* input, std::string& output)
{
LIBCWD_TSD_DECLARATION
Index: src/libcwd/documentation/alloc_intro.dox
diff -u /dev/null src/libcwd/documentation/alloc_intro.dox:1.1.2.1
--- /dev/null Sat Dec 1 17:01:44 2001
+++ src/libcwd/documentation/alloc_intro.dox Sat Dec 1 17:01:31 2001
@@ -0,0 +1,26 @@
+/*!
+
+\addtogroup chapter_allocations_intro
+
+Unless \link enable_libcwd_alloc --disable-libcwd-alloc \endlink was specified during configuration then
+the following memory allocation and de-allocation debugging features are provided by libcwd:
+
+-# Checking if a pointer that is passed to a memory de-allocation function is valid;
+ and if this pointer was previously returned by a corresponding allocation function.
+-# Finding the start, size, place of allocation in the source code and allocator type of an
+ allocated memory block when given a pointer which points inside of it.
+-# Providing means to add type info and a description to the Allocated memory Overview (using <CODE>AllocTag()</CODE></a>).
+-# Listing \ref chapter_overview "an overview of allocated memory" to a \ref chapter_debug_object "Debug Object".
+-# Boundary checks of allocated blocks, by means of \ref chapter_magic_numbers "magic numbers" (see also \ref enable_libcwd_magic).
+
+Unfortunately it is impossible to support feature 3. in C++ without putting hooks in your code:
+
+- After every memory allocation, the returned pointer should be passed to <CODE>AllocTag()</CODE>,
+ passing information that needs to be included in the Allocated memory Overview (this is not needed,
+ though allowed, after a call to <CODE>%realloc()</CODE>).
+
+A missing <CODE>AllocTag()</CODE> will only have effect on the Allocated memory Overview,
+showing <TT><unknown type></TT> instead of the type and a description of the allocated object.
+
+*/
+
Index: src/libcwd/documentation/allocated_memory_overview.dox
diff -u /dev/null src/libcwd/documentation/allocated_memory_overview.dox:1.1.2.1
--- /dev/null Sat Dec 1 17:01:44 2001
+++ src/libcwd/documentation/allocated_memory_overview.dox Sat Dec 1 17:01:31 2001
@@ -0,0 +1,206 @@
+/*!
+
+\addtogroup chapter_overview
+
+An example output, using libcw-0.2.5, is given below.
+Please follow the links to get a short explanation.
+
+\htmlonly
+<PRE class="output">
+MALLOC : Allocated memory: 3100 bytes in 14 blocks.
+<A HREF="#AMO_allocator">malloc</A> 0x819f068 sock.cc:92 sockaddr_in []; (sz = 16) <A HREF="#AMO_description">sockbuf_dbct::addr</A>
+malloc 0x819dea0 <A HREF="#AMO_location">dbstreambuf.h:582</A> char []; (sz = 512) dbstreambuf_ct::dbstreambuf_block_dct::block
+ 0x8122240 dbstreambuf.cc:68 dbstreambuf_ct::dbstreambuf_block_dct; (sz = 20)
+ 0x81400e8 <A HREF="#AMO_location">streambuf::streambuf(int)</A> <unknown type>; <A HREF="#AMO_size">(sz = 24)</A>
+ 0x8122400 sock.h:225 dbstreambuf_ct; (sz = 144)
+malloc 0x8140678 dbstreambuf.h:582 char []; (sz = 2048) dbstreambuf_ct::dbstreambuf_block_dct::block
+ 0x81405c8 dbstreambuf.cc:68 dbstreambuf_ct::dbstreambuf_block_dct; (sz = 20)
+ 0x8140558 streambuf::streambuf(int) <unknown type>; (sz = 24)
+ 0x8140428 sock.h:225 dbstreambuf_ct; (sz = 144)
+ 0x8140320 reduce_tst.cc:263 sock_dtct<socket_input_ct, socket_ostream_ct>; (sz = 100)
+ <A HREF="#AMO_start">0x813fd80</A> select.cc:106 list_tct<sbll_list_ct, fd_dct>; (sz = 8) fd_dct::write_fd_list
+ 0x8122360 select.cc:104 <A HREF="#AMO_type">list_tct<sbll_list_ct, fd_dct></A>; (sz = 8) fd_dct::readwrite_fd_list
+ 0x81221e0 select.cc:102 list_tct<sbll_list_ct, fd_dct>; (sz = 8) fd_dct::read_fd_list
+ 0x80545c8 libcw_app.h:140 reduce_tst_app_ct; (sz = 24) The application object
+</PRE>
+\endhtmlonly
+
+\subsection AMO_allocator allocator type
+
+A label in the first column of the Allocated memory Overview indicates
+with which type of allocator the memory block was allocated.
+Table 3 lists the labels that are being used for each of the
+allocator types (see \link libcw::debug::memblk_types_nt memblk_types_nt \endlink for their meaning).
+
+\htmlonly
+<H5 ALIGN=CENTER>Table 3. The values of memblk_types_nt and the corresponding label in the Allocated memory Overview</H5>
+<CENTER>
+<TABLE BGCOLOR=Wheat BORDERCOLOR=#503c2c WIDTH=577 BORDER=1 CELLPADDING=4 CELLSPACING=0>
+ <TR>
+ <TD BGCOLOR="#a98061"><FONT COLOR="#ffffff">Type</FONT></TD>
+ <TD BGCOLOR="#a98061"><FONT COLOR="#ffffff">Label</FONT></TD>
+ </TR>
+ <TR>
+ <TD><CODE>memblk_type_new</CODE></TD>
+ <TD> </TD>
+ </TR>
+ <TR>
+ <TD><CODE>memblk_type_deleted</CODE></TD>
+ <TD><CODE>(deleted)</CODE></TD>
+ </TR>
+ <TR>
+ <TD><CODE>memblk_type_new_array</CODE></TD>
+ <TD><CODE>new[]</CODE></TD>
+ </TR>
+ <TR>
+ <TD><CODE>memblk_type_deleted_array</CODE></TD>
+ <TD><CODE>(deleted)</CODE></TD>
+ </TR>
+ <TR>
+ <TD><CODE>memblk_type_malloc</CODE></TD>
+ <TD><CODE>malloc</CODE></TD>
+ </TR>
+ <TR>
+ <TD><CODE>memblk_type_realloc</CODE></TD>
+ <TD><CODE>realloc</CODE></TD>
+ </TR>
+ <TR>
+ <TD><CODE>memblk_type_freed</CODE></TD>
+ <TD><CODE>(freed)</CODE></TD>
+ </TR>
+ <TR>
+ <TD><CODE>memblk_type_noheap</CODE></TD>
+ <TD><CODE>(NO HEAP)</CODE></TD>
+ </TR>
+ <TR>
+ <TD><CODE>memblk_type_removed</CODE></TD>
+ <TD><CODE>(No heap)</CODE></TD>
+ </TR>
+ <TR>
+ <TD><CODE>memblk_type_marker</CODE></TD>
+ <TD><CODE>(MARKER)</CODE></TD>
+ </TR>
+ <TR>
+ <TD><CODE>memblk_type_deleted_marker</CODE></TD>
+ <TD><CODE>(deleted)</CODE></TD>
+ </TR>
+</TABLE>
+</CENTER>
+\endhtmlonly
+
+\subsection AMO_start start address
+
+The second column of the Allocated memory Overview gives the hexadecimal start address of the allocated memory block.
+This is the value returned by the allocator (<CODE>malloc</CODE>, <CODE>new</CODE> etc).
+Note that, when \ref enable_libcwd_magic "DEBUGMAGICMALLOC" is defined, a magic number is
+put <I>in front of</I> this hexadecimal start address.
+The result is that you can ignore completely whether or not DEBUGMAGICMALLOC is defined, in your own program.
+
+\subsection AMO_location source file location
+
+The third column of the Allocated memory Overview gives the source file
+location where the memory was allocated, or reallocated in the case of
+of <CODE>realloc</CODE>.
+The format is <TT><filename>:<line number></TT>.
+
+When the allocation is done in an object file without debug information
+and no source file or line number is known, then instead the name of the
+function in which the allocation was done is given.
+
+\subsection AMO_type type
+
+The fourth column of the Allocated memory Overview starts with the <TT>type</TT> of the allocated object
+(i.e., the <CODE>class</CODE> name).
+This information is only available when <CODE>AllocTag()</CODE>
+was called correctly for this allocation.
+Otherwise <TT><unknown type></TT> is shown instead.
+
+The given <TT>type</TT> is derived, but different,
+from what \ref libcw::debug::type_info_ct::demangled_name "type_info_ct::demangled_name()" returns.
+The <CODE>*</CODE> at the end of the type of the pointer is omitted when the
+memory block was allocated with <CODE>new</CODE>, it is replaced with
+<CODE>[<I>size</I>]</CODE> when the memory block was allocated with
+<CODE>new[]</CODE> and it is replaced with <CODE>[]</CODE> when the memory
+block was allocated with <CODE>malloc</CODE>.
+
+Examples were already given, but a summary is given in table 4 nonetheless.
+The <I><length></I> that is given between square brackets is the <I>rounded down</I> value of the size
+of the allocated memory block divided by the size of the object that is being pointed to.
+This will always be accurate for an <CODE>operator new []</CODE> of course,
+but its kinda fuzzy for an allocation with <CODE>malloc</CODE> et al.
+
+\htmlonly
+<H5 ALIGN=CENTER>Table 4. The format of the <I>type</I> field in the Allocated memory Overview, as function of the allocator.</H5>
+<CENTER>
+<TABLE BGCOLOR=Wheat BORDERCOLOR=#503c2c BORDER=1 CELLPADDING=4 CELLSPACING=0>
+<TR>
+ <TR>
+ <TD BGCOLOR="#a98061">
+ <FONT COLOR="#ffffff">Allocator</FONT>
+ </TD>
+ <TD BGCOLOR="#a98061">
+ <FONT COLOR="#ffffff">Type</FONT>
+ </TD>
+ <TD BGCOLOR="#a98061">
+ <FONT COLOR="#ffffff">Format</FONT>
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ <CODE>malloc/calloc/realloc</CODE>
+ </TD>
+ <TD>
+ <CODE>void*</CODE>
+ </TD>
+ <TD>
+ <CODE>void*</CODE>
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ <CODE>malloc/calloc/realloc</CODE>
+ </TD>
+ <TD>
+ <CODE>int*</CODE>
+ </TD>
+ <TD>
+ <CODE>int [<I><length></I>]</CODE>
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ <CODE>new</CODE>
+ </TD>
+ <TD>
+ <CODE>MyClass*</CODE>
+ </TD>
+ <TD>
+ <CODE>MyClass</CODE>
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ <CODE>new []</CODE>
+ </TD>
+ <TD>
+ <CODE>MyClass*</CODE>
+ </TD>
+ <TD>
+ <CODE>MyClass [<I><length></I>]</CODE>
+ </TD>
+ </TR>
+</TABLE>
+</CENTER>
+\endhtmlonly
+
+\subsection AMO_size size
+
+The number of allocated bytes is printed as
+<TT>(sz = </TT><I><size></I><TT>)</TT>,
+where <I><size></I> is the size of the returned memory block in bytes.
+
+\subsection AMO_description description
+
+Finally, the description that was passed along with <CODE>AllocTag()</CODE> is printed.
+
+*/
Index: src/libcwd/documentation/custom-debug.h.dox
diff -u src/libcwd/documentation/custom-debug.h.dox:1.1.2.2 src/libcwd/documentation/custom-debug.h.dox:1.1.2.3
--- src/libcwd/documentation/custom-debug.h.dox:1.1.2.2 Mon Nov 19 20:32:39 2001
+++ src/libcwd/documentation/custom-debug.h.dox Sat Dec 1 17:01:31 2001
@@ -3,7 +3,7 @@
/*!
-\page custom_debug_h The Custom debug.h file
+\defgroup custom_debug_h The Custom debug.h file
\section debug_channels_and_namespace Debug channels and namespace
Index: src/libcwd/documentation/custom_do.dox
diff -u src/libcwd/documentation/custom_do.dox:1.1.2.1 src/libcwd/documentation/custom_do.dox:1.1.2.2
--- src/libcwd/documentation/custom_do.dox:1.1.2.1 Tue Nov 13 19:01:07 2001
+++ src/libcwd/documentation/custom_do.dox Sat Dec 1 17:01:31 2001
@@ -5,7 +5,8 @@
Each %debug object is associated with one ostream.
The default %debug output macros Dout and DoutFatal use the \em default debug object libcw::debug::libcw_do.
Other %debug objects may be created as global objects;
-it is convenient to define new macros for each (custom) %debug object using the generic macros LibcwDout and LibcwDoutFatal.
+it is convenient to define new macros for each (custom) %debug object using the generic macros
+\link libcw::debug::LibcwDout LibcwDout \endlink and \link libcw::debug::LibcwDoutFatal LibcwDoutFatal \endlink.
For example, add something like the following to your own \link custom_debug_h "debug.h" \endlink file:
@@ -19,5 +20,8 @@
#define MyDoutFatal(a, b) LibcwDoutFatal(::std,, a, b)
#endif // !CWDEBUG
\endcode
+
+\sa \ref chapter_debug_object
+\sa \ref libcw::debug::libcw_do
*/
Index: src/libcwd/documentation/deallocation_pointer_validation.dox
diff -u src/libcwd/documentation/deallocation_pointer_validation.dox:1.1.2.1 src/libcwd/documentation/deallocation_pointer_validation.dox:1.1.2.2
--- src/libcwd/documentation/deallocation_pointer_validation.dox:1.1.2.1 Mon Nov 19 20:32:39 2001
+++ src/libcwd/documentation/deallocation_pointer_validation.dox Sat Dec 1 17:01:31 2001
@@ -1,6 +1,6 @@
/*!
-\page deallocation_pointer_validation De-allocation pointer validation
+\addtogroup chapter_validation
A pointer passed to a de-allocation (or re-allocation) function is checked to be valid;
it should be previously returned by a corresponding (re-)allocation function and not
@@ -40,7 +40,7 @@
Note: When libcwd was configured with \link enable_libcwd_magic --disable-libcwd-magic \endlink
then the check whether or not the de-allocated memory block was allocated with the corresponding
-allocation function is \em not performed when the memory block is \ref invisible.
+allocation function is \em not performed when the memory block is \ref chapter_invisible "invisible".
The reason for this is that invisible memory blocks are simply not stored in the internal data structure:
No information is known about them.
Index: src/libcwd/documentation/debug_channels.dox
diff -u /dev/null src/libcwd/documentation/debug_channels.dox:1.1.2.1
--- /dev/null Sat Dec 1 17:01:44 2001
+++ src/libcwd/documentation/debug_channels.dox Sat Dec 1 17:01:31 2001
@@ -0,0 +1,76 @@
+/*!
+
+\addtogroup chapter_debug_channels
+
+Whenever debug output is written, one or more <i>debug channels</i> must be specified.
+The debug output is then written to the ostream of the debug object
+unless the debug object is turned off or when all specified <i>debug channels</i> are off.
+Each <i>debug channel</i> can be turned \link libcw::debug::channel_ct::on on \endlink
+and \link libcw::debug::channel_ct::off off \endlink independently.
+
+Libcwd has defined six <i>debug channels</i> in namespace \link libcw::debug::channels::dc channels::dc \endlink
+(See \ref group_default_dc).
+New <i>debug channels</i> can be defined by the user, which is as simple as creating
+a new \link libcw::debug::channel_ct channel_ct \endlink object.
+
+Example,
+
+\code
+namespace dc {
+ channel_ct mychan("MYLABEL");
+}
+\endcode
+
+This declaration must be inside the namespace \ref DEBUGCHANNELS.
+
+Multiple <i>debug channels</i> can be given by using
+<CODE>operator|</CODE> between the channel names.
+This shouldn't be read as `or' but merely
+be seen as the bit-wise OR operation on the bit-masks that these
+channels actually represent.
+
+\sa chapter_control_flags
+
+<b>Example:</b>
+
+\code
+Dout(dc::notice, "Libcw is a great library");
+\endcode
+
+gives as result
+
+\exampleoutput <PRE>
+NOTICE: Libcw is a great library</PRE>
+\endexampleoutput
+
+and
+
+\code
+#ifdef CWDEBUG
+namespace myapplication {
+ namespace debug {
+ namespace channels { // Assuming DEBUGCHANNELS is ::myapplication::debug::channels
+
+ namespace dc {
+ libcw::debug::channel_ct hello("HELLO");
+ }
+
+ } // namespace DEBUGCHANNELS
+ }
+}
+#endif
+
+Dout(dc::hello, "Hello World!");
+Dout(dc::kernel|dc::io, "This is written when either the <i>kernel</i>"
+"or <i>io</i> channel is turned on.");
+\endcode
+
+gives as result
+
+\exampleoutput <PRE>
+HELLO : Hello World!
+KERNEL: This is written when either the kernel or io channel is turned on.</PRE>
+\endexampleoutput
+
+*/
+
Index: src/libcwd/documentation/doxygen.config
diff -u src/libcwd/documentation/doxygen.config:1.1.2.7 src/libcwd/documentation/doxygen.config:1.1.2.8
--- src/libcwd/documentation/doxygen.config:1.1.2.7 Tue Nov 20 18:23:18 2001
+++ src/libcwd/documentation/doxygen.config Sat Dec 1 17:01:31 2001
@@ -22,7 +22,7 @@
STRIP_CODE_COMMENTS = YES
CASE_SENSE_NAMES = YES
SHORT_NAMES = NO
-HIDE_SCOPE_NAMES = YES
+HIDE_SCOPE_NAMES = NO
VERBATIM_HEADERS = YES
SHOW_INCLUDE_FILES = YES
JAVADOC_AUTOBRIEF = NO
Index: src/libcwd/documentation/images/libcw_magic.gif
Index: src/libcwd/documentation/location.dox
diff -u src/libcwd/documentation/location.dox:1.1.2.1 src/libcwd/documentation/location.dox:1.1.2.2
--- src/libcwd/documentation/location.dox:1.1.2.1 Mon Nov 19 20:32:39 2001
+++ src/libcwd/documentation/location.dox Sat Dec 1 17:01:31 2001
@@ -1,9 +1,9 @@
/*!
-\page Source_file_and_line_number_information Source file and line number information
+\addtogroup chapter_alloc_locations Memory allocation debugging and locations
-\section BFD_library The BFD library
-
+\par The BFD library
+\n
Libcwd attempts to determine the source file and line number where memory is allocated.
It does this by directly reading the .stabs section of the ELF32 object files.
If you are using an Operating System that isn't ELF then you need to enable the use of libbfd for
@@ -11,32 +11,30 @@
If you don't have an ELF system and you don't have libbfd installed and are not able to install it
yourself (note: you also need libiberty and libdl) then you can disable it
using \link enable_libcwd_location --disable-libcwd-location \endlink.
-There is a seperate \link BFD chapter \endlink that deals with libcwd and <EM>location</EM> support.
+There is a seperate page that deals with libcwd and \link chapter_locations location \endlink support.
This paragraph describes the effect of disabling source file and line number location support in
relation to the memory allocation debugging support.
-
-\section With_location_support With location support
+\par With location support
+\n
With \link enable_libcwd_location --enable-libcwd-location \endlink, libcwd
will write the source file and line number information about where memory allocations are done to the
-\link Debug_Channel_objects debug channel \endlink \link libcw::debug::channels::dc::bfd dc::bfd \endlink.
-
+\link chapter_debug_channels debug channels \endlink \link libcw::debug::channels::dc::bfd dc::bfd \endlink.
+<br><br>
For example,
-
\exampleoutput <PRE>
MALLOC : operator new (size = 4) = <unfinished>
BFD : 0x804bc9b is at (deb.cc:179)
MALLOC : <continued> 0x8137220</PRE>
\endexampleoutput
-
which means that <CODE>operator new</CODE> was called
at address 0x804bc9b corresponding to line 179 of source file <TT>deb.cc</TT>.
-
-Source file and line number information is also shown in the \link Allocated_memory_Overview Allocated memory Overview \endlink
-and when a memory block is freed.
-
-\section Without_location_support Without location support
+<br><br>
+Source file and line number information is also shown in the
+\ref chapter_overview "overview of allocated memory" and when a memory block is freed.
+\par Without location support
+\n
Without support the source file and line number information will not be available.
%Debug channel \link libcw::debug::channels::dc::bfd dc::bfd \endlink doesn't exist and
the Allocated memory Overview will lack the source file location in column three.
Index: src/libcwd/documentation/magic.dox
diff -u /dev/null src/libcwd/documentation/magic.dox:1.1.2.1
--- /dev/null Sat Dec 1 17:01:44 2001
+++ src/libcwd/documentation/magic.dox Sat Dec 1 17:01:31 2001
@@ -0,0 +1,60 @@
+/*!
+
+\addtogroup chapter_magic_numbers Overflow/Underflow Protection (Red Zones)
+
+Memory corruption bugs are usually very hard to find because they often lead to a program
+crash in a source line far from the point of the actual bug.
+Buffer overruns are an important reason for memory corruption.
+Libcwd tries to help with finding buffer overruns by means of so called <i>magic numbers</i>.
+
+When \ref enable_libcwd_magic is defined, magic numbers are added to
+the beginning and the end of each allocated memory block.
+In addition to these two magic numbers, extra memory is allocated to hold the allocated <i>size</i>, this is necessary
+to find back the location of the magic number at the end with only a pointer to the beginning of the allocated memory block.
+The total size of actually allocated memory is therefore larger than was requested.
+The size of each field is equal to the size of a <CODE>size_t</CODE>.
+Moreover, a few bytes might be allocated extra just in front of the last magic number in order to word align this number.
+
+<CODE>new</CODE> and <CODE>malloc</CODE> etc. return a pointer just beyond this <i>size</i> field, see figure 1.
+
+\htmlonly
+<p STYLE="margin-left: 1.27cm"> <br>
+<img width=340 height=165 src="../images/libcw_magic.gif" alt="Memory layout of magic numbers" border=0>
+<br CLEAR=ALL> <br>
+Figure 1. Memory layout of an allocated memory block with <CODE>DEBUGMAGICMALLOC</CODE> defined.
+\endhtmlonly
+
+The magic numbers are checked when the memory is freed again.
+Libcwd uses twelve different magic numbers for six pairs, existing each of
+a <i>start</i> magic number and an <i>end</i> magic number.
+The six pairs consist of two groups: for memory allocated by the user
+and for memory allocated internally by libcwd as part of the debug malloc code itself.
+Thus, each group consists of three pairs: for memory allocated with
+<CODE>malloc</CODE>, <CODE>operator new</CODE> and <CODE>operator new[]</CODE> respectively.
+
+For example, the following code snippet:
+
+\code
+int* p = new int[4];
+AllocTag(p, "Test array");
+
+Debug( list_allocations_on(libcw_do) );
+
+p[4] = 5; // Buffer overflow
+delete[] p;
+\endcode
+
+results in output like
+
+\exampleoutput <PRE>
+MALLOC : operator new[] (size = 16) = 0x8116460
+
+MALLOC : Allocated memory: 16 bytes in 1 blocks.
+new[] 0x8116460 magic_tst.cc:174 int [4]; (sz = 16) Test array
+
+MALLOC : delete[] 0x8116460 magic_tst.cc:174 int [4]; (sz = 16) Test array <unfinished>
+COREDUMP: delete[]: magic number corrupt!
+Quit (core dumped)</PRE>
+\endexampleoutput
+
+*/
Index: src/libcwd/documentation/mainpage.dox
diff -u src/libcwd/documentation/mainpage.dox:1.1.2.3 src/libcwd/documentation/mainpage.dox:1.1.2.4
--- src/libcwd/documentation/mainpage.dox:1.1.2.3 Mon Nov 19 20:32:39 2001
+++ src/libcwd/documentation/mainpage.dox Sat Dec 1 17:01:31 2001
@@ -14,7 +14,7 @@
\li \ref downloading
\li \ref preparation
-\li \ref reference
+\li \htmlonly <A href="modules.html">Reference manual</A> \endhtmlonly
\section output_example Example output
Index: src/libcwd/documentation/memory_leak_checking.dox
diff -u src/libcwd/documentation/memory_leak_checking.dox:1.1.2.1 src/libcwd/documentation/memory_leak_checking.dox:1.1.2.2
--- src/libcwd/documentation/memory_leak_checking.dox:1.1.2.1 Mon Nov 19 20:32:39 2001
+++ src/libcwd/documentation/memory_leak_checking.dox Sat Dec 1 17:01:31 2001
@@ -1,6 +1,6 @@
/*!
-\page memory_leak_checking Memory leak checking
+\addtogroup chapter_markers Memory Allocation Markers: Memory Leak Checking
Libcwd does a weak attempt to support debugging of memory leaks.
I hope to greatly improve this in the future.
Index: src/libcwd/documentation/modules.dox
diff -u /dev/null src/libcwd/documentation/modules.dox:1.1.2.1
--- /dev/null Sat Dec 1 17:01:44 2001
+++ src/libcwd/documentation/modules.dox Sat Dec 1 17:01:31 2001
@@ -0,0 +1,46 @@
+/** \addtogroup chapter_writing Writing Debug Output */
+/** \{ */
+/** \addtogroup chapter_writing_intro Writing Debug Output: Introduction */
+/** \addtogroup chapter_destination Setting The Output Destination */
+/** \{ */
+/** \addtogroup chapter_debug_object The Output Device (Debug Object) */
+/** \addtogroup custom_do Custom Debug Objects */
+/** \} */
+/** \addtogroup chapter_debug_channels Controlling The Output Level (Debug Channels) */
+/** \{ */
+/** \addtogroup group_default_dc */
+/** \} */
+/** \addtogroup chapter_formatting Format Of The Debug Output */
+/** \addtogroup chapter_control_flags Control Flags */
+/** \addtogroup chapter_fatal_output Fatal Debug Output */
+/** \addtogroup chapter_nesting Nesting Debug Output */
+/** \addtogroup chapter_special Special Functions And Utilities */
+/** \} */
+
+/** \addtogroup chapter_allocations Memory Allocation Debug Support */
+/** \{ */
+/** \addtogroup chapter_allocations_intro Memory Allocation Debug Support: Introduction */
+/** \addtogroup chapter_validation De-Allocation Pointer Validation */
+/** \addtogroup chapter_magic_numbers Overflow/Underflow Protection (Red Zones) */
+/** \addtogroup chapter_annotation Allocation Annotation */
+/** \addtogroup chapter_overview Overview Of Allocated Memory */
+/** \{ */
+/** \addtogroup chapter_invisible */
+/** \} */
+/** \addtogroup chapter_finding Finding (Information About) Memory Allocations */
+/** \addtogroup chapter_markers Memory Allocation Markers: Memory Leak Checking */
+/** \} */
+
+/** \addtogroup chapter_symbols Program Symbols Access And Interpretation */
+/** \{ */
+/** \addtogroup chapter_symbols_intro Program Symbols Access And Interpretation: Introduction */
+/** \addtogroup chapter_locations Source File And Line Number Information */
+/** \addtogroup chapter_type_info Getting Type Information Of Types And Symbols */
+/** \} */
+
+/** \addtogroup chapter_start Configuration, Installation And Getting Started */
+/** \{ */
+/** \addtogroup group_configuration Configuration Options And Macros */
+/** \addtogroup chapter_alloc_locations */
+/** \} */
+
Index: src/libcwd/documentation/nested.dox
diff -u src/libcwd/documentation/nested.dox:1.1.2.2 src/libcwd/documentation/nested.dox:1.1.2.3
--- src/libcwd/documentation/nested.dox:1.1.2.2 Mon Nov 19 20:32:39 2001
+++ src/libcwd/documentation/nested.dox Sat Dec 1 17:01:31 2001
@@ -1,11 +1,10 @@
/*!
-\page nested_debug_calls Nested debug calls
+\addtogroup chapter_nesting Nesting Debug Output
-\section inside Calling functions inside Dout
-
+\par Calling functions inside Dout
+\n
Consider the following code:
-
\code
int foobar(void) __attribute__ ((const));
@@ -23,46 +22,37 @@
return foobar();
}
\endcode
-
This code would start a new debug message before the previous debug message is finished.
Libcwd detects this and will output:
-
\exampleoutput <PRE>
NOTICE: Entering foobar()
NOTICE: Leaving foobar()
KERNEL: The value of foobar() = 2, aint that nice?</PRE>
\endexampleoutput
-
Note the indentation and the fact that the printing of the label KERNEL was delayed.
-\section using_continued Using continued_cf, dc::continued and dc::finish
-
+\anchor using_continued
+\par Using continued_cf, dc::continued and dc::finish
+\n
In the previous section <CODE>foobar()</CODE> was a const function: it didn't matter
whether or not it was called for the functionality of the application. But when
it does matter, then one might want to do something like this:
-
\code
Dout( dc::kernel|flush_cf|continued_cf, "Generating tables... " );
generate_tables();
Dout( dc::finish, "done" );
\endcode
-
If generate_tables() would not print debug messages, then the output will look like:
-
\exampleoutput <PRE>
KERNEL: Generating tables... done</PRE>
\endexampleoutput
-
When it does generated debug output, then the <unfinished> and <continued> labels are printed also:
-
\exampleoutput <PRE>
KERNEL: Generating tables... <unfinished>
NOTICE: Inside generate_tables()
KERNEL: <continued> done</PRE>
\endexampleoutput
-
Finally, it is also possible to split a debug line into more then two parts by using the special dc::continued debug channel.
-
\code
Dout( dc::notice|flush_cf|continued_cf, "Generating tables." );
for(int i = 0; i < 8; ++i)
@@ -72,21 +62,16 @@
}
Dout( dc::finish, " done" );
\endcode
-
When generate_table(i) doesn't print debug messages, then the output will look like:
-
\exampleoutput <PRE>
NOTICE: Generating tables......... done</PRE>
\endexampleoutput
-
When it does generate debug output, then each dot would be surrounded by a <continued> .<unfinished> :
-
\exampleoutput <PRE>
NOTICE: Generating tables.<unfinished>
TABLE : Inside generate_table(0)
NOTICE: <continued> .<unfinished></PRE>
\endexampleoutput
-
etc.
*/
Index: src/libcwd/documentation/preparation.dox
diff -u src/libcwd/documentation/preparation.dox:1.1.2.2 src/libcwd/documentation/preparation.dox:1.1.2.3
--- src/libcwd/documentation/preparation.dox:1.1.2.2 Mon Nov 19 20:32:39 2001
+++ src/libcwd/documentation/preparation.dox Sat Dec 1 17:01:31 2001
@@ -13,8 +13,9 @@
\htmlonly<A HREF="../external/INSTALL">\endhtmlonly
INSTALL\htmlonly</A>\endhtmlonly
file that is included in the source distribution.<BR>
-See also: \ref configuration
+See also: \ref group_configuration
+\anchor preparation_step2
\subsection header_files Step 2: Creating the custom header files
You need to add two custom header files to your application.<BR>
Index: src/libcwd/documentation/reference.dox
diff -u src/libcwd/documentation/reference.dox:1.1.2.1 src/libcwd/documentation/reference.dox:removed
--- src/libcwd/documentation/reference.dox:1.1.2.1 Tue Nov 13 19:01:07 2001
+++ src/libcwd/documentation/reference.dox Sat Dec 1 17:01:44 2001
@@ -1,56 +0,0 @@
-/*! \page reference Reference Manual
-
-\section Writing_debug_output Writing debug output
-
-\subsection The_Debug_Object The Debug Object
-<ul>
- <li> Class: \ref libcw::debug::debug_ct
- <li> Default debug object: \link libcw::debug::libcw_do libcw_do \endlink
- <li> Writing debug output to libcw_do: \ref Dout
- <li> Custom debug objects: \ref custom_do
-</ul>
-
-\subsection Debug_Channel_objects Debug Channel objects
-<ul>
- <li> Class: \ref libcw::debug::channel_ct
- <li> Pre-defined channels: \ref default_dc
- <li> Custom channels: \ref preparation
-</ul>
-
-\subsection Format_of_the_debug_output Format of the debug output
-<ul>
- <li> \ref debug_ct_formatting
-</ul>
-
-\subsection Debug_output_Control_Flags Debug output Control Flags
-<ul>
- <li> Overview: \ref control_flags
-</ul>
-
-\subsection Fatal_debug_output Fatal debug output
-<ul>
- <li> Macro: \ref DoutFatal
- <li> Pre-defined channels: \ref dc::fatal, \ref dc::core
-</ul>
-
-\subsection Nested_debug_calls Nested debug calls
-<ul>
- <li> \ref nested_debug_calls
-</ul>
-
-\subsection Special_functions Special functions
-<ul>
- <li> \ref ForAllDebugObjects ( )
- <li> \ref ForAllDebugChannels ( )
- <li> \ref Debug ( \link libcw::debug::check_configuration list_channels_on() \endlink )
- <li> \ref Debug ( \link libcw::debug::list_channels_on list_channels_on \endlink (\link libcw::debug::libcw_do libcw_do \endlink) )
- <li> \ref Debug ( \link libcw::debug::list_allocations_on list_allocations_on \endlink (\link libcw::debug::libcw_do libcw_do \endlink) )
- <li> \ref Debug ( \link libcw::debug::make_all_allocations_invisible_except make_all_allocations_invisible_except(ptr) \endlink )
-</ul>
-
-\section Memory_allocation_debugging_support Memory allocation debug support
-
-\section Runtime_debug_symbols_handling Runtime debug symbols handling
-
-*/
-
Index: src/libcwd/documentation/why_macro.dox
diff -u /dev/null src/libcwd/documentation/why_macro.dox:1.1.2.1
--- /dev/null Sat Dec 1 17:01:44 2001
+++ src/libcwd/documentation/why_macro.dox Sat Dec 1 17:01:31 2001
@@ -0,0 +1,122 @@
+/*!
+
+\page page_why_macro Design Consideration Concerning Macros
+
+This page describes why we use a macro in stead of an inline
+function for <CODE>Dout()</CODE>.
+
+Good C++ code should not use macros, but <CODE>inline</CODE> functions which
+have the advantage of type checking, overloading and easier debugging with a debugger.
+It is therefore a very relevant question to ask why a macro was used for <CODE>Dout()</CODE>.
+
+Using a macro has also advantages:
+
+<OL>
+ <LI>It inlines the debug code even when we don't use optimization.
+ <LI>It allows us to use tricks that make the code run faster when debug code is included.
+ <LI>It allows us to omit variables in the program that are only used for debugging and which are written to a debug <CODE>ostream</CODE>.
+ <LI>It compiles faster when debugging is omitted.
+ <LI>No optimization is needed to really get rid of the debug code when debugging is omitted.
+</OL>
+
+Points 1., 2. and 3. are the most important reasons that lead to the decision to use a macro.
+Please note that the author of %libcw used the alternative for <B>two years</B> before finally was decided
+to <B>rewrite</B> the debug facility, being convinced that it was better to do it the way it is done now.
+While points 4. and 5. are trivial, the first three advantages might need some explanation:
+
+1. Usually a developer won't use compiler optimization because that makes debugging harder.
+In most cases the debug code will be compiled and used <B>without</B> compiler optimization; including
+the fact that <B>no</B> inlining is done at all.
+Moreover, we expect to use a lot of inserter operators and without
+optimization, each of these which will be called.
+[ Note that when omitting debug code we can't get rid of the content of all
+<CODE>%operator<<</CODE> functions because they might be used for
+non-debug code too, so we'd need to use a trick and write to
+something else than an <CODE>ostream</CODE> (lets say to a class <CODE>no_dstream</CODE>).
+Each call to <CODE>template<class T> no_dstream %operator<<(T) { };</CODE> would actually be done(!),
+without inlining (point 5. above) ].
+
+2. Lets develop an example, step by step which is writing debug output.
+
+Lets start with writing some example debug output to <CODE>cerr</CODE>.
+
+\code
+std::cerr << "i = " << i << "; j = " << j << "; s = " << s << std::endl;
+\endcode
+
+This line calls seven functions, if we want to save cpu when we
+<B>don't</B> want to write this output, then we need to test
+whether the debugging output (for this specific channel) is turned
+on or off <B>before</B> calling the <CODE>%operator<<()</CODE>'s.
+After all, such an operator call can use a lot of cpu for arbitrary objects.
+
+We can not pass <CODE>"i = " << i << "; j = " << j << "; s = " << s << std::endl</CODE>
+to an inline function without causing all <CODE>%operator<<</CODE>
+functions to be called.
+The only way, not using a macro, to achieve that no <CODE>%operator<<</CODE> is called is by not calling them
+in the first place: We can't write to an <CODE>ostream</CODE>.
+It is necessary to write to a new class (lets call that class <CODE>dstream</CODE>) which
+checks if the debug channel we are writing to is turned on before
+calling the <CODE>ostream %operator<<()</CODE>:
+
+\code
+template<class T>
+ inline dstream&
+ operator<<(dstream& ds, T const& data)
+ {
+ if (on)
+ std::cerr << data;
+ }
+\endcode
+
+Nevertheless, even with inlining (needing often the maximium optimization), most compilers would turn that into:
+
+\code
+if (on)
+ std::cerr << "i = ";
+if (on)
+ std::cerr << i;
+if (on)
+ std::cerr << "; j = ";
+if (on)
+ std::cerr << j;
+if (on)
+ std::cerr << "; s = ";
+if (on)
+ std::cerr << s;
+if (on)
+ std::cerr << std::endl;
+\endcode
+
+checking <CODE>on</CODE> seven times.
+
+With a macro we can easily achieve the best result, even without any optimization:
+
+\code
+if (on)
+ std::cerr << "i = " << i << "; j = " << j << "; s = " << s << std::endl;
+\endcode
+
+3. Sometimes a variable is specific to debug code and only being used for writing to a debug ostream.
+When the debug is omitted and inline functions are used for the <CODE>Dout()</CODE> calls, then these
+variables still need to exist: they are passed to the <CODE>Dout()</CODE>
+function (or actually, to the <CODE>no_dstream %operator<<()</CODE>'s).
+Using a macro allows one to really get rid of such variables by
+surrounding them with <CODE>#ifdef CWDEBUG ... #endif</CODE> preprocessor directives.
+
+Example:
+
+\code
+ if (need_close)
+ {
+ Dout(dc::system|continued_cf, "close(" << __fd << ") = ");
+#ifdef CWDEBUG
+ int ret =
+#endif
+ ::close(__fd);
+ Dout(dc::finish|cond_error_cf(ret < 0), ret);
+ return false;
+ }
+\endcode
+
+*/
Index: src/libcwd/include/libcw/bfd.h
diff -u src/libcwd/include/libcw/bfd.h:1.20.2.16 src/libcwd/include/libcw/bfd.h:1.20.2.17
--- src/libcwd/include/libcw/bfd.h:1.20.2.16 Tue Oct 23 07:17:08 2001
+++ src/libcwd/include/libcw/bfd.h Sat Dec 1 17:01:31 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/bfd.h,v 1.20.2.16 2001/10/23 14:17:08 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/bfd.h,v 1.20.2.17 2001/12/02 01:01:31 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -10,6 +10,10 @@
// version 1.0 as appearing in the file LICENSE.QPL included in the
// packaging of this file.
//
+
+/** \file bfd.h
+ * Do not include this header file directly, instead include "\ref preparation_step2 "debug.h"".
+ */
#ifndef LIBCW_BFD_H
#define LIBCW_BFD_H
Index: src/libcwd/include/libcw/buf2str.h
diff -u src/libcwd/include/libcw/buf2str.h:1.5.2.8 src/libcwd/include/libcw/buf2str.h:1.5.2.9
--- src/libcwd/include/libcw/buf2str.h:1.5.2.8 Mon Nov 19 20:32:39 2001
+++ src/libcwd/include/libcw/buf2str.h Sat Dec 1 17:01:31 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/buf2str.h,v 1.5.2.8 2001/11/20 04:32:39 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/buf2str.h,v 1.5.2.9 2001/12/02 01:01:31 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -46,7 +46,9 @@
* characters by either printing the character itself, the octal representation or one of
* \c \a, \c \b, \c \t, \c \n, \c \f, \c \r, \c \e or \c \\.
*
- * \par Example:
+ * \sa libcw::debug::char2str
+ *
+ * <b>Example:</b>
*
* \code
* char const* buf = "\e[31m;Hello\e[0m;\n";
@@ -54,8 +56,6 @@
*
* Dout(dc::notice, "The buffer contains: \"" << buf2str(buf, size) << '"');
* \endcode
- *
- * \sa libcw::debug::char2str
*/
class buf2str {
Index: src/libcwd/include/libcw/char2str.h
diff -u src/libcwd/include/libcw/char2str.h:1.5.2.8 src/libcwd/include/libcw/char2str.h:1.5.2.9
--- src/libcwd/include/libcw/char2str.h:1.5.2.8 Mon Nov 19 20:32:39 2001
+++ src/libcwd/include/libcw/char2str.h Sat Dec 1 17:01:31 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/char2str.h,v 1.5.2.8 2001/11/20 04:32:39 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/char2str.h,v 1.5.2.9 2001/12/02 01:01:31 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -38,15 +38,15 @@
* sequence when needed using the octal representation or one of \c \a, \c \b, \c \t, \c \n,
* \c \f, \c \r, \c \e or \c \\.
*
- * \par Example:
+ * \sa libcw::debug::buf2str
+ *
+ * <b>Example:</b>
*
* \code
* char c = '\f';
*
* Dout(dc::notice, "The variable c contains: '" << char2str(c) << '\'');
* \endcode
- *
- * \sa libcw::debug::buf2str
*/
class char2str {
Index: src/libcwd/include/libcw/class_alloc.h
diff -u src/libcwd/include/libcw/class_alloc.h:1.1.2.2 src/libcwd/include/libcw/class_alloc.h:1.1.2.3
--- src/libcwd/include/libcw/class_alloc.h:1.1.2.2 Mon Nov 19 20:32:39 2001
+++ src/libcwd/include/libcw/class_alloc.h Sat Dec 1 17:01:31 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_alloc.h,v 1.1.2.2 2001/11/20 04:32:39 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_alloc.h,v 1.1.2.3 2001/12/02 01:01:31 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -11,6 +11,10 @@
// packaging of this file.
//
+/** \file class_alloc.h
+ * Do not include this header file directly, instead include "\ref preparation_step2 "debug.h"".
+ */
+
#ifndef LIBCW_CLASS_ALLOC_H
#define LIBCW_CLASS_ALLOC_H
@@ -100,7 +104,7 @@
*
* \returns a non-const \ref location_ct reference corresponding to the place where the allocation was done.
* Class\ref location_ct describes a source file and line number location and in which function that location resides.
- * \sa \ref Source_file_and_line_number_information
+ * \sa \ref chapter_alloc_locations
*/
location_ct& location_reference(void) { return M_location; }
@@ -109,7 +113,7 @@
*
* \returns a const \ref location_ct reference corresponding to the place where the allocation was done.
* Class \ref location_ct describes a source file and line number location and in which function that location resides.
- * \sa \ref Source_file_and_line_number_information
+ * \sa \ref chapter_alloc_locations
*/
location_ct const& location(void) const { return M_location; }
#endif
Index: src/libcwd/include/libcw/class_channel.h
diff -u src/libcwd/include/libcw/class_channel.h:1.1.2.5 src/libcwd/include/libcw/class_channel.h:1.1.2.6
--- src/libcwd/include/libcw/class_channel.h:1.1.2.5 Mon Nov 19 20:32:39 2001
+++ src/libcwd/include/libcw/class_channel.h Sat Dec 1 17:01:31 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_channel.h,v 1.1.2.5 2001/11/20 04:32:39 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_channel.h,v 1.1.2.6 2001/12/02 01:01:31 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -11,6 +11,10 @@
// packaging of this file.
//
+/** \file class_channel.h
+ * Do not include this header file directly, instead include "\ref preparation_step2 "debug.h"".
+ */
+
#ifndef LIBCW_CLASS_CHANNEL_H
#define LIBCW_CLASS_CHANNEL_H
@@ -43,8 +47,8 @@
*
* Whenever %debug output is written, one or more %debug %channels must be specified (as first
* parameter of the \ref Dout macro).
- * The %debug output is then written to the \link debug_ct_device ostream \endlink of the
- * \link libcw::debug::debug_ct debug object \endlink unless the %debug object
+ * The %debug output is then written to the \link chapter_destination ostream \endlink of the
+ * \link debug_ct debug object \endlink unless the %debug object
* is turned off or when all specified %debug %channels are off.
* Each %debug channel can be turned on and off independently.
*
@@ -52,7 +56,7 @@
* This shouldn't be read as `or' but merely be seen as the bit-wise OR operation on the bit-masks
* that these %channels actually represent.
*
- * \par Example:
+ * <b>Example:</b>
*
* \code
* Dout( dc::notice, "Libcw is a great library" );
Index: src/libcwd/include/libcw/class_channel_set.h
diff -u src/libcwd/include/libcw/class_channel_set.h:1.1.2.3 src/libcwd/include/libcw/class_channel_set.h:1.1.2.4
--- src/libcwd/include/libcw/class_channel_set.h:1.1.2.3 Fri Oct 26 15:58:03 2001
+++ src/libcwd/include/libcw/class_channel_set.h Sat Dec 1 17:01:31 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_channel_set.h,v 1.1.2.3 2001/10/26 22:58:03 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_channel_set.h,v 1.1.2.4 2001/12/02 01:01:31 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -10,6 +10,10 @@
// version 1.0 as appearing in the file LICENSE.QPL included in the
// packaging of this file.
//
+
+/** \file class_channel_set.h
+ * Do not include this header file directly, instead include "\ref preparation_step2 "debug.h"".
+ */
#ifndef LIBCW_CLASS_CHANNEL_SET_H
#define LIBCW_CLASS_CHANNEL_SET_H
Index: src/libcwd/include/libcw/class_continued_channel.h
diff -u src/libcwd/include/libcw/class_continued_channel.h:1.1.2.3 src/libcwd/include/libcw/class_continued_channel.h:1.1.2.4
--- src/libcwd/include/libcw/class_continued_channel.h:1.1.2.3 Fri Oct 26 15:58:03 2001
+++ src/libcwd/include/libcw/class_continued_channel.h Sat Dec 1 17:01:31 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_continued_channel.h,v 1.1.2.3 2001/10/26 22:58:03 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_continued_channel.h,v 1.1.2.4 2001/12/02 01:01:31 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -10,6 +10,10 @@
// version 1.0 as appearing in the file LICENSE.QPL included in the
// packaging of this file.
//
+
+/** \file class_continued_channel.h
+ * Do not include this header file directly, instead include "\ref preparation_step2 "debug.h"".
+ */
#ifndef LIBCW_CONTINUED_CHANNEL_H
#define LIBCW_CONTINUED_CHANNEL_H
Index: src/libcwd/include/libcw/class_debug.h
diff -u src/libcwd/include/libcw/class_debug.h:1.1.2.7 src/libcwd/include/libcw/class_debug.h:1.1.2.8
--- src/libcwd/include/libcw/class_debug.h:1.1.2.7 Mon Nov 19 20:32:39 2001
+++ src/libcwd/include/libcw/class_debug.h Sat Dec 1 17:01:31 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_debug.h,v 1.1.2.7 2001/11/20 04:32:39 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_debug.h,v 1.1.2.8 2001/12/02 01:01:31 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -11,6 +11,10 @@
// packaging of this file.
//
+/** \file class_debug.h
+ * Do not include this header file directly, instead include "\ref preparation_step2 "debug.h"".
+ */
+
#ifndef LIBCW_CLASS_DEBUG_H
#define LIBCW_CLASS_DEBUG_H
@@ -57,20 +61,19 @@
*
* \brief The %Debug Stream class.
*
- * Libcwd declares a %debug class (debug_ct) which can be assigned an ostream to which %debug output
- * will be written. Such a %debug object can dynamically be turned \link on() on \endlink and
- * \link off() off \endlink.
- * When the %debug object is turned off, no %debug output is written to its
- * \link debug_ct_device ostream \endlink; in fact, the data that otherwise would be written is not
- * even evaluated (see \ref eval_example "example" below).
+ * Libcwd declares a %debug class (debug_ct) which can be assigned an ostream to which %debug output will be written.
+ * Such a %debug object can dynamically be turned \link debug_ct::on on \endlink
+ * and \link debug_ct::off off \endlink.
+ * When the %debug object is turned off, no %debug output is written to its \link chapter_destination ostream \endlink;
+ * in fact, the data that otherwise would be written is not even evaluated (see \ref eval_example "example" below).
* The %debug code can also completely be omitted, by not defining the macro CWDEBUG.
*
- * Libcwd defines and uses only one %debug object: \link libcw::debug::libcw_do libcw_do \endlink (the _do stands for %Debug Object).
+ * Libcwd defines and uses only one %debug object: \ref libcw_do (the _do stands for %Debug Object).
* However, it is possible to \link custom_do create more \endlink %debug objects which would allow one to write %debug output to
* two or more different output devices at the same time (for instance, the screen and a file).
*
* For each %debug object it is possible to set a margin and a marker string and to set the size of the current indentation.
- * The methods used for setting or changing these prefix formatting attributes are listed in \ref debug_ct_formatting.
+ * The methods used for setting or changing these prefix formatting attributes are listed in \ref chapter_formatting.
*/
class debug_ct {
public: // Direct access needed in macro LibcwDout(). Do not write to these.
@@ -136,10 +139,8 @@
public:
- /** \defgroup debug_ct_formatting Formatting methods and attributes of class debug_ct
+ /** \addtogroup chapter_formatting
*
- * \brief Public attributes of libcw::debug::debug_ct for setting or changing the format of the debug output.
- *
* All debug output is written in the following format:
*
* <margin> <label> <marker> <indentation> <data> <suffix>
@@ -161,8 +162,10 @@
* Finally, the <suffix> field is by default a new-line, optionally followed by a flush.
* The %debug control flag error_cf however, causes an error message to be inserted first.
* The suffix field could become for example ": EAGAIN (Try again)\\n".
+ *
+ * \sa chapter_control_flags
*
- * \par Example:
+ * <b>Example:</b>
*
* \code
* Debug( libcw_do.margin.assign("*** ", 4) );
@@ -214,7 +217,7 @@
// Manipulators and accessors for the above "format" attributes:
//
- /** \addtogroup debug_ct_formatting */
+ /** \addtogroup chapter_formatting */
/* \{ */
/** \brief Set number of spaces to indent. */
@@ -247,12 +250,12 @@
// Other accessors
//
- /** \defgroup debug_ct_device libcw::debug::debug_ct ostream Manipulation Methods
+ /** \addtogroup chapter_destination
*
- * Basically, a %debug object (debug_ct) is a pointer to an ostream with a few extra attributes
- * added to give it an internal state for \link libcw::debug::debug_ct::on() on \endlink (pass
- * output on) and \link libcw::debug::debug_ct::off() off \endlink (don't pass output on)
- * as well as some \link debug_ct_formatting formatting \endlink information of how to write the
+ * Basically, a %debug object (\link libcw::debug::debug_ct debug_ct \endlink) is a pointer to an ostream
+ * with a few extra attributes added to give it an internal state for \link libcw::debug::debug_ct::on() on \endlink
+ * (pass output on) and \link libcw::debug::debug_ct::off() off \endlink (don't pass output on)
+ * as well as some \link chapter_formatting formatting \endlink information of how to write the
* data that is passed on to its ostream.
*
* The methods of \link libcw::debug::debug_ct debug_ct \endlink given here allow you to set
@@ -321,7 +324,7 @@
// Manipulators:
//
- /** \addtogroup debug_ct_device */
+ /** \addtogroup chapter_destination */
/* \{ */
/**
@@ -345,7 +348,7 @@
* These pairs can be nested.
*
* \anchor eval_example
- * \par Example:
+ * <b>Example:</b>
*
* \code
* int i = 0;
Index: src/libcwd/include/libcw/class_debug_string.h
diff -u src/libcwd/include/libcw/class_debug_string.h:1.1.2.5 src/libcwd/include/libcw/class_debug_string.h:1.1.2.6
--- src/libcwd/include/libcw/class_debug_string.h:1.1.2.5 Mon Nov 19 20:32:39 2001
+++ src/libcwd/include/libcw/class_debug_string.h Sat Dec 1 17:01:31 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_debug_string.h,v 1.1.2.5 2001/11/20 04:32:39 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_debug_string.h,v 1.1.2.6 2001/12/02 01:01:31 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -11,6 +11,10 @@
// packaging of this file.
//
+/** \file cla...
[truncated message content] |
