Menu
▾
▴
[libcw-cvs] [CVS] Module src
|
From: Carlo W. <li...@us...> - 2001-12-08 02:06:35
|
CVSROOT : /cvsroot/libcw
Module : src
Branch tags: branch-threading
Commit time: 2001-11-08 02:06:33 UTC
Modified files:
Tag: branch-threading
libcwd/INSTALL libcwd/bfd.cc libcwd/debug.cc
libcwd/debugmalloc.cc libcwd/demangle3.cc libcwd/maintMakefile.in
libcwd/strerrno.cc libcwd/type_info.cc
libcwd/documentation/Makefile
libcwd/documentation/alloc_intro.dox
libcwd/documentation/allocated_memory_overview.dox
libcwd/documentation/custom_do.dox
libcwd/documentation/debug_channels.dox
libcwd/documentation/debug_object.dox
libcwd/documentation/downloading.dox
libcwd/documentation/doxygen.config
libcwd/documentation/fatal_output.dox
libcwd/documentation/invisible.dox
libcwd/documentation/location.dox
libcwd/documentation/memory_leak_checking.dox
libcwd/documentation/preparation.dox
libcwd/documentation/reference.dox
libcwd/documentation/why_macro.dox
libcwd/documentation/writing_intro.dox
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.inl
libcwd/include/libcw/class_debug.h
libcwd/include/libcw/class_debug.inl
libcwd/include/libcw/class_debug_string.h
libcwd/include/libcw/class_debug_string.inl
libcwd/include/libcw/class_fatal_channel.inl
libcwd/include/libcw/class_location.h
libcwd/include/libcw/class_location.inl
libcwd/include/libcw/class_marker.h
libcwd/include/libcw/control_flag.h
libcwd/include/libcw/core_dump.h libcwd/include/libcw/debug.h
libcwd/include/libcw/debugmalloc.h
libcwd/include/libcw/demangle.h
libcwd/include/libcw/macro_AllocTag.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/sysd.ho.in libcwd/include/libcw/type_info.h
Log message:
Work in progress.
Moved most of the reference manual documentation to doxygen format.
---------------------- diff included ----------------------
Index: src/libcwd/INSTALL
diff -u src/libcwd/INSTALL:1.20.2.2 src/libcwd/INSTALL:1.20.2.3
--- src/libcwd/INSTALL:1.20.2.2 Tue Nov 13 19:01:06 2001
+++ src/libcwd/INSTALL Fri Dec 7 18:06:22 2001
@@ -3,6 +3,7 @@
./configure --prefix=/usr
make
+su
make install
If that doesn't work, mail me: li...@al...
@@ -14,96 +15,97 @@
Check if you have all GNU tools/libraries/packages that libcwd depends on:
- Primary site:
- ftp://ftp.gnu.org/gnu/
+Primary site:
+ftp://ftp.gnu.org/gnu/
- List of mirrors:
- http://www.gnu.org/order/ftp.html
+List of mirrors:
+http://www.gnu.org/order/ftp.html
- Packages/versions needed
- ------------------------
+Packages/versions needed
+------------------------
- i) The GNU compiler, version 2.95.1 or higher.
-
- Location: gnu/gcc/
- Current version: 3.0.2
-
- Alternatively you can install only
- ia) gnu/gcc/gcc-core-<version>.tar.gz and
- ib) gnu/gcc/gcc-g++-<version>.tar.gz
-
- Note: It is very unlikely that you want to install
- the source tree of gcc/g++. Please try to upgrade your
- compiler the usual way if needed.
- If you are using rpm's then you will need to
- install/upgrade the following:
- gcc (2.95.1 or higher),
- gcc-c++ (of same version),
- libstdc++ (of same version) and
- cpp (of same version).
- Check your installation on RedHat with:
- rpm -qa | egrep '(gcc|libstdc|cpp)'
-
- Note: If you don't use rpm's but are using tar balls,
- then you do NOT need to download gnu/libstdc++/* because
- gcc-2.95 and higher comes with libstdc++ included.
- The gnu/libstdc++/ directory on GNU ftp sites are
- for older compilers or to be used as source drop-in
- when you compile g++ (replacing the normal stdc++ with
- an alpha version). You also don't need libg++.
- Don't delete those libraries if you have them though
- since existing binaries might need to link with them.
-
- libcwd-0.99.16 was tested with gcc-2.95.x, gcc-2.96-97 (RedHat)
- and gcc-3.0.x.
-
- Packages needed to run the testsuite
- ------------------------------------
-
- If you want to run the testsuite then you will have to install
- dejagnu-1.4.1 which can be downloaded from ftp://ftp.gnu.org/gnu/dejagnu/,
- or your local GNU mirror. However, this version still contains a bug
- and you'll have to apply the following patch: edit /usr/share/dejagnu/target.exp
- line 275 and remove the newline at the end (so that the word "text" on line
- 276 is added at the end of line 275:
- regsub -all ".*: warning: -f(pic|PIC) ignored for target .*" $text "" text
-
- Alternatively, you can get dejagnu directly from the cvs repository
- at http://www.gnu.org/software/dejagnu/ where this bug already has been
- fixed (as it will be in any version *after* 1.4.1).
-
- You will also need expect-5.32.2 (and tcl/tk 8.3.3?). At least, expect 5.31.2
- is known to hang.
-
- Packages/versions needed as maintainer or when using CVS
- --------------------------------------------------------
-
- If you want to generate maintainer files (and you need that when
- you get this package via CVS) then you also need to have the
- following tools:
-
- iii) GNU make
- iv) GNU m4
- v) GNU which version 2.x
- vi) autoconf version 2.13 (2.52 seems to have problems)
- vii) automake version 1.4pl1 or higher
- viii) libtool version 1.4 or higher
-
- Each of those can be downloaded from your local GNU site.
-
- Moreover, in order to generate the documentation, you need to
- have the following installed:
-
- ix) GNU grep version 2.4.2 is known to work.
- x) doxygen http://www.doxygen.org/
- xi) graphviz http://www.research.att.com/sw/tools/graphviz/
+i) The GNU compiler, version 2.95.1 or higher.
+
+ Location: gnu/gcc/
+ Current version: 3.0.2
+
+Alternatively you can install only
+ia) gnu/gcc/gcc-core-<version>.tar.gz and
+ib) gnu/gcc/gcc-g++-<version>.tar.gz
+
+Note: It is very unlikely that you want to install
+the source tree of gcc/g++. Please try to upgrade your
+compiler the usual way if needed.
+If you are using rpm's then you will need to
+install/upgrade the following:
+ gcc (2.95.1 or higher),
+ gcc-c++ (of same version),
+ libstdc++ (of same version) and
+ cpp (of same version).
+Check your installation on RedHat with:
+ rpm -qa | egrep '(gcc|libstdc|cpp)'
+
+Note: If you don't use rpm's but are using tar balls,
+then you do NOT need to download gnu/libstdc++/* because
+gcc-2.95 and higher comes with libstdc++ included.
+The gnu/libstdc++/ directory on GNU ftp sites are
+for older compilers or to be used as source drop-in
+when you compile g++ (replacing the normal stdc++ with
+an alpha version). You also don't need libg++.
+Don't delete those libraries if you have them though
+since existing binaries might need to link with them.
+
+libcwd-0.99.16 was tested with gcc-2.95.x, gcc-2.96-97 (RedHat)
+and gcc-3.0.x.
+
+Packages needed to run the testsuite
+------------------------------------
+
+ii) If you want to run the testsuite then you will have to install
+dejagnu-1.4.1 which can be downloaded from ftp://ftp.gnu.org/gnu/dejagnu/,
+or your local GNU mirror. However, this version still contains a bug
+and you'll have to apply the following patch: edit /usr/share/dejagnu/target.exp
+line 275 and remove the newline at the end (so that the word "text" on line
+276 is added at the end of line 275:
+regsub -all ".*: warning: -f(pic|PIC) ignored for target .*" $text "" text
+
+Alternatively, you can get dejagnu directly from the cvs repository
+at http://www.gnu.org/software/dejagnu/ where this bug already has been
+fixed (as it will be in any version *after* 1.4.1).
+
+You will also need expect-5.32.2 (and tcl/tk 8.3.3?). At least, expect 5.31.2
+is known to hang.
+
+Packages/versions needed as maintainer or when using CVS
+--------------------------------------------------------
+
+If you want to generate maintainer files (and you need that when you
+get this package via CVS; in that case you also need to configure using
+--enable-maintainer-mode) then you also need to have the following tools:
+
+iii) GNU make
+iv) GNU m4
+v) GNU which version 2.x
+vi) autoconf version 2.13 (2.52 seems to have problems)
+vii) automake version 1.4pl1 or higher
+viii) libtool version 1.4 or higher
+
+Each of those can be downloaded from your local GNU site.
+
+Moreover, in order to generate the documentation, you need to
+have the following installed:
+
+ix) GNU grep version 2.4.2 is known to work.
+x) doxygen version 1.2.12 or higher (http://www.doxygen.org/)
+xi) graphviz http://www.research.att.com/sw/tools/graphviz/
+
Hackers info
============
-=i=-
-`configure' has a few interesting options. You can list them by issuing:
+'configure' has a few interesting options. You can list them by issuing:
./configure --help
@@ -112,7 +114,7 @@
Actually, I forgot why they are there :). You can read more about the
configuration options and what they do in include/libcw/debug_config.h.
-If you want to change Makefile.am files and the-like then you'll need to
+If you want to change Makefile.am files and the like then you'll need to
use --enable-maintainer-mode. If you enable maintainer-mode then you
will need GNU make, other make won't work (you also need a LOT of other
extra tools installed on your system, only for the brave thus).
@@ -139,15 +141,15 @@
Please note that the libbfd that comes with binutils-2.11.x is not compatible
with the libiberty that comes with with gcc-2.95.x.
--=iii=-
+-=iv=-
-You can install libcwd in a `staging' directory by issuing
+You can install libcwd in a 'staging' directory by issuing
make DESTDIR=/tmp/staging install
this can come in handy when you want to build an rpm for instance.
--=iv=-
+-=v=-
The Makefile has the following targets:
@@ -169,9 +171,9 @@
make CC="gcc-3.0.2" CXX="g++-3.0.2" reconfig // Switch compilers keeping the same configuration
make full-check // Iterate over all configurations and all compiler versions
-It is not garanteed that these work on another machine then mine however.
+It is not garanteed that these work on another machine than mine however.
--=v=-
+-=vi=-
Finally, you can also build libcwd in a different directory than the source
tree is in:
Index: src/libcwd/bfd.cc
diff -u src/libcwd/bfd.cc:1.85.2.32 src/libcwd/bfd.cc:1.85.2.33
--- src/libcwd/bfd.cc:1.85.2.32 Wed Dec 5 22:01:14 2001
+++ src/libcwd/bfd.cc Fri Dec 7 18:06:22 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/bfd.cc,v 1.85.2.32 2001/12/06 06:01:14 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/bfd.cc,v 1.85.2.33 2001/12/08 02:06:22 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -1103,9 +1103,12 @@
char const* const unknown_function_c = "<unknown function>";
- //
- // Find the mangled function name of the address `addr'.
- //
+ /**
+ * \brief Find the mangled function name of the address \a addr.
+ *
+ * \returns the same pointer that is returned by location_ct::mangled_function_name() on success,
+ * otherwise \ref unknown_function_c is returned.
+ */
char const* pc_mangled_function_name(void const* addr)
{
using namespace cwbfd;
@@ -1247,7 +1250,7 @@
// that will free `file' again a second call to `bfd_find_nearest_line' (for the
// same value of `abfd': the allocated pointer is stored in a structure
// that is kept for each bfd seperately).
- // The call to `new char [len + 1]' below could cause this function (pc_location)
+ // The call to `new char [len + 1]' below could cause this function (M_pc_location)
// to be called again (in order to store the file:line where the allocation
// is done) and thus a new call to `bfd_find_nearest_line', which then would
// free `file' before we copy it!
@@ -1317,6 +1320,9 @@
M_func = unknown_function_c;
}
+ /**
+ * \brief Reset this location object (frees memory).
+ */
void location_ct::clear(void)
{
if (M_filepath)
@@ -1330,6 +1336,7 @@
M_func = "<cleared location_ct>";
}
+ // Undocumented: shouldn't be used I think.
location_ct::location_ct(location_ct const &prototype) : M_filepath(NULL)
{
if (prototype.M_filepath)
@@ -1345,6 +1352,12 @@
}
}
+ /**
+ * \brief Move \p prototype to this location object;
+ *
+ * \p prototype must be \ref is_known "known" and the current object \ref is_known "unknown";
+ * \p prototype is clear()-ed afterwards.
+ */
void location_ct::move(location_ct& prototype)
{
// MT: This method is used assuming that *only* attributes of the
@@ -1359,6 +1372,7 @@
prototype.M_func = "<moved location_ct>";
}
+ // Undocumented: shouldn't be used I think.
location_ct& location_ct::operator=(location_ct const &prototype)
{
if (this != &prototype)
@@ -1381,11 +1395,10 @@
/**
* \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 group_locations
+ *
+ * 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.
*/
std::ostream& operator<<(std::ostream& os, location_ct const& location)
{
Index: src/libcwd/debug.cc
diff -u src/libcwd/debug.cc:1.46.2.40 src/libcwd/debug.cc:1.46.2.41
--- src/libcwd/debug.cc:1.46.2.40 Wed Dec 5 22:01:15 2001
+++ src/libcwd/debug.cc Fri Dec 7 18:06:22 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/debug.cc,v 1.46.2.40 2001/12/06 06:01:15 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/debug.cc,v 1.46.2.41 2001/12/08 02:06:22 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -164,7 +164,7 @@
/**
* \addtogroup group_default_dc Predefined Debug Channels
- * \ingroup chapter_debug_channels
+ * \ingroup group_debug_channels
*
* These are the default %debug %channels pre-defined in libcwd.
*/
@@ -508,6 +508,9 @@
strncpy(M_str, str, len);
}
+ /**
+ * \brief Reserve memory for the string in advance.
+ */
void debug_string_ct::reserve(size_t size)
{
if (size < M_size)
@@ -529,6 +532,12 @@
M_default_capacity = ds.M_default_capacity;
}
+ /** \addtogroup group_formatting */
+ /* \{ */
+
+ /**
+ * \brief Push the current margin on a stack.
+ */
void debug_ct::push_margin(void)
{
debug_string_stack_element_ct* current_margin_stack = M_margin_stack;
@@ -540,6 +549,9 @@
M_margin_stack->next = current_margin_stack;
}
+ /**
+ * \brief Pop margin from the stack.
+ */
void debug_ct::pop_margin(void)
{
if (!M_margin_stack)
@@ -553,6 +565,9 @@
M_margin_stack = next;
}
+ /**
+ * \brief Push the current marker on a stack.
+ */
void debug_ct::push_marker(void)
{
debug_string_stack_element_ct* current_marker_stack = M_marker_stack;
@@ -563,6 +578,9 @@
M_marker_stack->next = current_marker_stack;
}
+ /**
+ * \brief Pop marker from the stack.
+ */
void debug_ct::pop_marker(void)
{
if (!M_marker_stack)
@@ -576,6 +594,8 @@
M_marker_stack = next;
}
+ /** \} */
+
void debug_ct::start(LIBCWD_TSD_PARAM)
{
// It's possible we get here before this debug object is initialized: The order of calling global is undefined :(.
@@ -946,6 +966,9 @@
}
}
+ /**
+ * \brief Destructor
+ */
debug_ct::~debug_ct()
{
// Sanity checks:
@@ -1047,22 +1070,22 @@
}
}
- void channel_ct::NS_initialize(char const* lbl) // Single Threaded function (or just Non-Shared if you take dlopen into account).
+ void channel_ct::NS_initialize(char const* label) // Single Threaded function (or just Non-Shared if you take dlopen into account).
{
// This is pretty much identical to fatal_channel_ct::fatal_channel_ct().
if (WNS_initialized)
return; // Already initialized.
- DEBUGDEBUG_CERR( "Entering `channel_ct::channel_ct(\"" << lbl << "\")'" );
+ DEBUGDEBUG_CERR( "Entering `channel_ct::NS_initialize(\"" << label << "\")'" );
// Of course, dc::debug is off - so this won't do anything unless DEBUGDEBUG is #defined.
- Dout( dc::debug, "Initializing channel_ct(\"" << lbl << "\")" );
+ Dout( dc::debug, "Initializing channel_ct(\"" << label << "\")" );
- size_t lbl_len = strlen(lbl);
+ size_t label_len = strlen(label);
- if (lbl_len > max_label_len_c) // Only happens for customized channels
- DoutFatal( dc::core, "strlen(\"" << lbl << "\") > " << max_label_len_c );
+ if (label_len > max_label_len_c) // Only happens for customized channels
+ DoutFatal( dc::core, "strlen(\"" << label << "\") > " << max_label_len_c );
#ifdef LIBCWD_THREAD_SAFE
_private_::mutex_tct<_private_::write_max_len_instance>::initialize();
@@ -1074,8 +1097,8 @@
// because this assignment is an atomic operation. The lock above is only needed to
// prefend two such simultaneously loaded libraries from causing WST_max_len to end up
// not maximal.
- if (lbl_len > WST_max_len)
- WST_max_len = lbl_len;
+ if (label_len > WST_max_len)
+ WST_max_len = label_len;
LIBCWD_TSD_DECLARATION
#ifdef LIBCWD_THREAD_SAFE
@@ -1091,8 +1114,8 @@
off_cnt = 0;
#endif
- strncpy(WNS_label, lbl, lbl_len);
- memset(WNS_label + lbl_len, ' ', max_label_len_c - lbl_len);
+ strncpy(WNS_label, label, label_len);
+ memset(WNS_label + label_len, ' ', max_label_len_c - label_len);
// We store debug channels in some organized order, so that the
// order in which they appear in the ForAllDebugChannels is not
@@ -1113,52 +1136,52 @@
set_alloc_checking_on(LIBCWD_TSD);
// Turn debug channel "WARNING" on by default.
- if (strncmp(WNS_label, "WARNING", lbl_len) == 0)
+ if (strncmp(WNS_label, "WARNING", label_len) == 0)
#ifdef LIBCWD_THREAD_SAFE
__libcwd_tsd.off_cnt_array[WNS_index] = -1;
#else
off_cnt = -1;
#endif
- DEBUGDEBUG_CERR( "Leaving `channel_ct::channel_ct(\"" << lbl << "\")" );
+ DEBUGDEBUG_CERR( "Leaving `channel_ct::NS_initialize(\"" << label << "\")" );
WNS_initialized = true;
}
- void fatal_channel_ct::NS_initialize(char const* lbl, control_flag_t maskbit)
+ void fatal_channel_ct::NS_initialize(char const* label, control_flag_t maskbit)
{
- // This is pretty much identical to channel_ct::channel_ct().
+ // This is pretty much identical to channel_ct::NS_initialize().
if (WNS_maskbit)
return; // Already initialized.
WNS_maskbit = maskbit;
- DEBUGDEBUG_CERR( "Entering `fatal_channel_ct::fatal_channel_ct(\"" << lbl << "\")'" );
+ DEBUGDEBUG_CERR( "Entering `fatal_channel_ct::NS_initialize(\"" << label << "\")'" );
// Of course, dc::debug is off - so this won't do anything unless DEBUGDEBUG is #defined.
- Dout( dc::debug, "Initializing fatal_channel_ct(\"" << lbl << "\")" );
+ Dout( dc::debug, "Initializing fatal_channel_ct(\"" << label << "\")" );
- size_t lbl_len = strlen(lbl);
+ size_t label_len = strlen(label);
- if (lbl_len > max_label_len_c) // Only happens for customized channels
- DoutFatal( dc::core, "strlen(\"" << lbl << "\") > " << max_label_len_c );
+ if (label_len > max_label_len_c) // Only happens for customized channels
+ DoutFatal( dc::core, "strlen(\"" << label << "\") > " << max_label_len_c );
#ifdef LIBCWD_THREAD_SAFE
_private_::mutex_tct<_private_::write_max_len_instance>::initialize();
_private_::mutex_tct<_private_::write_max_len_instance>::lock();
#endif
- // MT: See comment in channel_ct::channel_ct above.
- if (lbl_len > WST_max_len)
- WST_max_len = lbl_len;
+ // MT: See comment in channel_ct::NS_initialize above.
+ if (label_len > WST_max_len)
+ WST_max_len = label_len;
#ifdef LIBCWD_THREAD_SAFE
_private_::mutex_tct<_private_::write_max_len_instance>::unlock();
#endif
- strncpy(WNS_label, lbl, lbl_len);
- memset(WNS_label + lbl_len, ' ', max_label_len_c - lbl_len);
+ strncpy(WNS_label, label, label_len);
+ memset(WNS_label + label_len, ' ', max_label_len_c - label_len);
- DEBUGDEBUG_CERR( "Leaving `fatal_channel_ct::fatal_channel_ct(\"" << lbl << "\")" );
+ DEBUGDEBUG_CERR( "Leaving `fatal_channel_ct::NS_initialize(\"" << label << "\")" );
}
void continued_channel_ct::NS_initialize(control_flag_t maskbit)
@@ -1167,6 +1190,11 @@
WNS_maskbit = maskbit;
}
+ /**
+ * \brief Turn this channel off.
+ *
+ * \sa on()
+ */
void channel_ct::off(void)
{
#ifdef LIBCWD_THREAD_SAFE
@@ -1177,6 +1205,11 @@
#endif
}
+ /**
+ * \brief Cancel one call to `off()'.
+ *
+ * The channel is turned on when on() is called as often as off() was called before.
+ */
void channel_ct::on(void)
{
#ifdef LIBCWD_THREAD_SAFE
Index: src/libcwd/debugmalloc.cc
diff -u src/libcwd/debugmalloc.cc:1.61.2.46 src/libcwd/debugmalloc.cc:1.61.2.47
--- src/libcwd/debugmalloc.cc:1.61.2.46 Wed Dec 5 22:01:15 2001
+++ src/libcwd/debugmalloc.cc Fri Dec 7 18:06:22 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/debugmalloc.cc,v 1.61.2.46 2001/12/06 06:01:15 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/debugmalloc.cc,v 1.61.2.47 2001/12/08 02:06:22 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -469,6 +469,11 @@
from_free // memblk_type_external
};
+/**
+ * \brief Allow writing a \c memblk_types_nt directly to an ostream.
+ *
+ * Writes the name of the \c memblk_types_nt \a memblk_type to \c ostream \a os.
+ */
std::ostream& operator<<(std::ostream& os, memblk_types_nt memblk_type)
{
switch(memblk_type)
@@ -577,7 +582,7 @@
class dm_alloc_ct : public alloc_ct {
#ifdef DEBUGMARKER
friend class marker_ct;
- friend void libcw_debug_move_outside(marker_ct* marker, void const* ptr);
+ friend void move_outside(marker_ct* marker, void const* ptr);
#endif
private:
static dm_alloc_ct** current_alloc_list;
@@ -694,7 +699,7 @@
class memblk_info_ct {
#ifdef DEBUGMARKER
friend class marker_ct;
- friend void libcw_debug_move_outside(marker_ct* marker, void const* ptr);
+ friend void move_outside(marker_ct* marker, void const* ptr);
#endif
private:
memblk_types_nt M_memblk_type;
@@ -1555,9 +1560,9 @@
/**
* \brief Allow writing of enum malloc_report_nt to an ostream.
- * \ingroup chapter_overview
+ * \ingroup group_overview
*
- * \sa \ref malloc_report
+ * \sa \ref malloc_report_nt
*/
std::ostream& operator<<(std::ostream& o, malloc_report_nt)
{
@@ -1571,12 +1576,12 @@
/**
* \brief List all current allocations to a given %debug object.
- * \ingroup chapter_overview
+ * \ingroup group_overview
*
* 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".
+ * to write the \ref group_overview "overview of allocated memory" to
+ * a \ref group_debug_object "Debug Object".
* The syntax to do this is:
*
* \code
@@ -1584,7 +1589,7 @@
* \endcode
*
* 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.
+ * \ref group_debug_channels "debug channel" \link libcw::debug::dc::malloc dc::malloc \endlink.
*/
void list_allocations_on(debug_ct& debug_object)
{
@@ -1630,10 +1635,10 @@
* \ingroup group_invisible
*
* The allocation pointed to by \a ptr is made invisible; it won't show up
- * anymore in the \ref chapter_overview "overview of allocated memory".
+ * anymore in the \ref group_overview "overview of allocated memory".
*
* \sa \ref group_invisible
- * \sa \ref chapter_overview
+ * \sa \ref group_overview
*
* <b>Example:</b>
*
@@ -1668,12 +1673,12 @@
* \ingroup group_invisible
*
* All allocations, except the given pointer, are made invisible; they won't show up
- * anymore in the \ref chapter_overview "overview of allocated memory".
+ * anymore in the \ref group_overview "overview of allocated memory".
*
* If you want to make \em all allocations invisible, just pass \c NULL as parameter.
*
* \sa \ref group_invisible
- * \sa \ref chapter_overview
+ * \sa \ref group_overview
*
* <b>Example:</b>
*
@@ -1757,6 +1762,9 @@
#endif
}
+/**
+ * \brief Destructor.
+ */
marker_ct::~marker_ct(void)
{
#ifdef DEBUGDEBUGMALLOC
@@ -1794,7 +1802,11 @@
RELEASE_WRITE_LOCK
}
-void libcw_debug_move_outside(marker_ct* marker, void const* ptr)
+/**
+ * \brief Move memory allocation pointed to by \a ptr outside \a marker.
+ * \ingroup group_markers
+ */
+void move_outside(marker_ct* marker, void const* ptr)
{
#ifdef DEBUGDEBUGMALLOC
LIBCWD_TSD_DECLARATION
Index: src/libcwd/demangle3.cc
diff -u src/libcwd/demangle3.cc:1.8.2.19 src/libcwd/demangle3.cc:1.8.2.20
--- src/libcwd/demangle3.cc:1.8.2.19 Wed Dec 5 22:01:15 2001
+++ src/libcwd/demangle3.cc Fri Dec 7 18:06:23 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/demangle3.cc,v 1.8.2.19 2001/12/06 06:01:15 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/demangle3.cc,v 1.8.2.20 2001/12/08 02:06:23 libcw Exp $
//
// Copyright (C) 2001, by
//
@@ -1993,7 +1993,12 @@
extern void demangle_symbol(char const* input, _private_::internal_string& output);
extern void demangle_type(char const* input, _private_::internal_string& output);
-/** \ingroup group_demangle */
+/** \addtogroup group_demangle */
+/** \{ */
+
+/**
+ * \brief Demangle mangled symbol name \p input and write the result to string \p output.
+ */
void demangle_symbol(char const* input, std::string& output)
{
LIBCWD_TSD_DECLARATION
@@ -2008,7 +2013,9 @@
_private_::set_alloc_checking_on(LIBCWD_TSD);
}
-/** \ingroup group_demangle */
+/**
+ * \brief Demangle mangled type name \p input and write the result to string \p output.
+ */
void demangle_type(char const* input, std::string& output)
{
LIBCWD_TSD_DECLARATION
@@ -2022,6 +2029,8 @@
}
_private_::set_alloc_checking_on(LIBCWD_TSD);
}
+
+/** \} */
} // namespace debug
} // namespace libcw
Index: src/libcwd/documentation/Makefile
diff -u src/libcwd/documentation/Makefile:1.1.2.1 src/libcwd/documentation/Makefile:1.1.2.2
--- src/libcwd/documentation/Makefile:1.1.2.1 Tue Nov 13 19:01:07 2001
+++ src/libcwd/documentation/Makefile Fri Dec 7 18:06:23 2001
@@ -5,7 +5,15 @@
.PHONY: html external
html: external
+ rm -rf html
doxygen doxygen.config
+ mv html/preparation.html html/preparation.tmp
+ cat html/preparation.tmp | \
+ sed -e 's/href="debug_8h\.html">debug\.h/href="#preparation_step2">debug.h/' \
+ -e 's/"sys\.h"/"<a class="code" href="#preparation_step2">sys.h<\/a>"/' \
+ > html/preparation.html
+ rm html/preparation.tmp
+
external: external/INSTALL external/sys.h external/debug.h external/debug.cc
Index: src/libcwd/documentation/alloc_intro.dox
diff -u src/libcwd/documentation/alloc_intro.dox:1.1.2.2 src/libcwd/documentation/alloc_intro.dox:1.1.2.3
--- src/libcwd/documentation/alloc_intro.dox:1.1.2.2 Wed Dec 5 22:01:16 2001
+++ src/libcwd/documentation/alloc_intro.dox Fri Dec 7 18:06:23 2001
@@ -14,7 +14,7 @@
-# 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".
+-# Listing \ref group_overview "an overview of allocated memory" to a \ref group_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:
Index: src/libcwd/documentation/allocated_memory_overview.dox
diff -u src/libcwd/documentation/allocated_memory_overview.dox:1.1.2.2 src/libcwd/documentation/allocated_memory_overview.dox:1.1.2.3
--- src/libcwd/documentation/allocated_memory_overview.dox:1.1.2.2 Wed Dec 5 22:01:16 2001
+++ src/libcwd/documentation/allocated_memory_overview.dox Fri Dec 7 18:06:23 2001
@@ -1,10 +1,12 @@
/*!
-\defgroup chapter_overview Overview Of Allocated Memory
+\defgroup group_overview Overview Of Allocated Memory
\ingroup book_allocations
*/
/*!
\page page_overview
-\ingroup chapter_overview
+\ingroup group_overview
+
+<hr><h2>Detailed Description</h2>
An example output, using libcw-0.2.5, is given below.
Please follow the links to get a short explanation.
Index: src/libcwd/documentation/custom_do.dox
diff -u src/libcwd/documentation/custom_do.dox:1.1.2.3 src/libcwd/documentation/custom_do.dox:1.1.2.4
--- src/libcwd/documentation/custom_do.dox:1.1.2.3 Wed Dec 5 22:01:16 2001
+++ src/libcwd/documentation/custom_do.dox Fri Dec 7 18:06:23 2001
@@ -25,7 +25,7 @@
#endif // !CWDEBUG
\endcode
-\sa \ref chapter_debug_object
+\sa \ref group_debug_object
\sa \ref libcw::debug::libcw_do
*/
Index: src/libcwd/documentation/debug_channels.dox
diff -u src/libcwd/documentation/debug_channels.dox:1.1.2.2 src/libcwd/documentation/debug_channels.dox:1.1.2.3
--- src/libcwd/documentation/debug_channels.dox:1.1.2.2 Wed Dec 5 22:01:16 2001
+++ src/libcwd/documentation/debug_channels.dox Fri Dec 7 18:06:23 2001
@@ -1,12 +1,12 @@
/*!
-\defgroup chapter_debug_channels Controlling The Output Level (Debug Channels)
+\defgroup group_debug_channels Controlling The Output Level (Debug Channels)
\ingroup book_writing
*/
/*!
\page page_debug_channels
-\ingroup chapter_debug_channels
+\ingroup group_debug_channels
-<hr>
+<hr><h2>Detailed Description</h2>
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
Index: src/libcwd/documentation/debug_object.dox
diff -u src/libcwd/documentation/debug_object.dox:1.1.2.1 src/libcwd/documentation/debug_object.dox:1.1.2.2
--- src/libcwd/documentation/debug_object.dox:1.1.2.1 Wed Dec 5 22:01:16 2001
+++ src/libcwd/documentation/debug_object.dox Fri Dec 7 18:06:23 2001
@@ -1,12 +1,12 @@
/*!
-\defgroup chapter_debug_object The Output Device (Debug Object)
+\defgroup group_debug_object The Output Device (Debug Object)
\ingroup book_writing
*/
/*!
\page page_debug_object
-\ingroup chapter_debug_object
+\ingroup group_debug_object
-<hr>
+<hr><h2>Detailed Description</h2>
Libcwd declares a %debug class (\ref libcw::debug::debug_ct "debug_ct") which can be assigned an <code>ostream</code>
to which %debug output will be written.
Index: src/libcwd/documentation/downloading.dox
diff -u src/libcwd/documentation/downloading.dox:1.1.2.2 src/libcwd/documentation/downloading.dox:1.1.2.3
--- src/libcwd/documentation/downloading.dox:1.1.2.2 Mon Nov 19 20:32:39 2001
+++ src/libcwd/documentation/downloading.dox Fri Dec 7 18:06:23 2001
@@ -2,6 +2,6 @@
\page downloading Downloading
-For now, download libcwd from sourceforge at http://sourceforge.net/project/showfiles.php?group_id=354
+Download libcwd from sourceforge at http://sourceforge.net/project/showfiles.php?group_id=354
*/
Index: src/libcwd/documentation/doxygen.config
diff -u src/libcwd/documentation/doxygen.config:1.1.2.9 src/libcwd/documentation/doxygen.config:1.1.2.10
--- src/libcwd/documentation/doxygen.config:1.1.2.9 Wed Dec 5 22:01:16 2001
+++ src/libcwd/documentation/doxygen.config Fri Dec 7 18:06:23 2001
@@ -7,7 +7,7 @@
PROJECT_NUMBER = "libcwd 0.99.16"
OUTPUT_DIRECTORY =
OUTPUT_LANGUAGE = English
-EXTRACT_ALL = YES
+EXTRACT_ALL = NO
EXTRACT_PRIVATE = NO
EXTRACT_STATIC = NO
HIDE_UNDOC_MEMBERS = YES
@@ -41,7 +41,7 @@
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 0
OPTIMIZE_OUTPUT_FOR_C = NO
-SHOW_USED_FILES = YES
+SHOW_USED_FILES = NO
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
@@ -60,7 +60,8 @@
../include/libcw \
../demangle3.cc
FILE_PATTERNS = *.dox \
- *.h
+ *.h \
+ *.inl
RECURSIVE = NO
EXCLUDE =
EXCLUDE_PATTERNS =
@@ -125,10 +126,10 @@
#---------------------------------------------------------------------------
# configuration options related to the man page output
#---------------------------------------------------------------------------
-GENERATE_MAN = NO
+GENERATE_MAN = YES
MAN_OUTPUT =
-MAN_EXTENSION =
-MAN_LINKS = NO
+MAN_EXTENSION = .1
+MAN_LINKS = YES
#---------------------------------------------------------------------------
# configuration options related to the XML output
#---------------------------------------------------------------------------
Index: src/libcwd/documentation/fatal_output.dox
diff -u src/libcwd/documentation/fatal_output.dox:1.1.2.1 src/libcwd/documentation/fatal_output.dox:1.1.2.2
--- src/libcwd/documentation/fatal_output.dox:1.1.2.1 Wed Dec 5 22:01:16 2001
+++ src/libcwd/documentation/fatal_output.dox Fri Dec 7 18:06:23 2001
@@ -1,12 +1,12 @@
/*!
-\defgroup chapter_fatal_output Fatal Debug Output
+\defgroup group_fatal_output Fatal Debug Output
\ingroup book_writing
*/
/*!
\page page_fatal_output
-\ingroup chapter_fatal_output
+\ingroup group_fatal_output
-<hr>
+<hr><h2>Detailed Description</h2>
Often an application needs to be terminated when a fatal error occurs (whether or not CWDEBUG
is defined). Libcwd defines for these cases the macro DoutFatal.
Index: src/libcwd/documentation/invisible.dox
diff -u src/libcwd/documentation/invisible.dox:1.1.2.1 src/libcwd/documentation/invisible.dox:1.1.2.2
--- src/libcwd/documentation/invisible.dox:1.1.2.1 Wed Dec 5 22:01:16 2001
+++ src/libcwd/documentation/invisible.dox Fri Dec 7 18:06:23 2001
@@ -1,6 +1,6 @@
/*!
\addtogroup group_invisible Invisible Allocations
-\ingroup chapter_overview
+\ingroup group_overview
*/
/*!
\page page_invisible
@@ -9,7 +9,7 @@
<hr><h2>Detailed Description</h2>
Allocated memory blocks can be made invisible: They won't show up in
-the \ref chapter_overview "overview of allocated memory" anymore.
+the \ref group_overview "overview of allocated memory" anymore.
Even more, the corresponding \ref libcw::debug::alloc_ct "alloc_ct" is destroyed:
\ref libcw::debug::find_alloc "find_alloc" will not find them anymore.
There is no other effect, \ref libcw::debug::test_delete "test_delete" will still work
Index: src/libcwd/documentation/location.dox
diff -u src/libcwd/documentation/location.dox:1.1.2.3 src/libcwd/documentation/location.dox:1.1.2.4
--- src/libcwd/documentation/location.dox:1.1.2.3 Wed Dec 5 22:01:16 2001
+++ src/libcwd/documentation/location.dox Fri Dec 7 18:06:23 2001
@@ -23,7 +23,7 @@
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 chapter_debug_channels debug channels \endlink \link libcw::debug::channels::dc::bfd dc::bfd \endlink.
+\link group_debug_channels debug channels \endlink \link libcw::debug::channels::dc::bfd dc::bfd \endlink.
For example,
@@ -37,7 +37,7 @@
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
-\ref chapter_overview "overview of allocated memory" and when a memory block is freed.
+\ref group_overview "overview of allocated memory" and when a memory block is freed.
\section section_Without_location_support Without location support
Index: src/libcwd/documentation/memory_leak_checking.dox
diff -u src/libcwd/documentation/memory_leak_checking.dox:1.1.2.3 src/libcwd/documentation/memory_leak_checking.dox:1.1.2.4
--- src/libcwd/documentation/memory_leak_checking.dox:1.1.2.3 Wed Dec 5 22:01:16 2001
+++ src/libcwd/documentation/memory_leak_checking.dox Fri Dec 7 18:06:23 2001
@@ -1,11 +1,13 @@
/*!
-\defgroup chapter_markers Memory Allocation Markers: Memory Leak Checking
+\defgroup group_markers Memory Allocation Markers: Memory Leak Checking
\ingroup book_allocations
*/
/*!
\page page_markers
-\ingroup chapter_markers
+\ingroup group_markers
+<hr><h2>Detailed Description</h2>
+
Libcwd does a weak attempt to support debugging of memory leaks.
I hope to greatly improve this in the future.
@@ -40,7 +42,7 @@
}
\endcode
-which would move the memory allocation pointed to by ptr outside the test region of \c marker.
+which would move the memory allocation pointed to by \a ptr outside the test region of \a marker.
A complete example program with output is given here:
Index: src/libcwd/documentation/preparation.dox
diff -u src/libcwd/documentation/preparation.dox:1.1.2.4 src/libcwd/documentation/preparation.dox:1.1.2.5
--- src/libcwd/documentation/preparation.dox:1.1.2.4 Wed Dec 5 22:01:16 2001
+++ src/libcwd/documentation/preparation.dox Fri Dec 7 18:06:23 2001
@@ -7,7 +7,7 @@
\subsection installation Step 1: Installing libcwd
-Binairy distributions should be installed the usual way.
+Binary distributions should be installed the usual way.
If you are installing libcwd from source then please read the
\htmlonly<A HREF="../external/INSTALL">\endhtmlonly
@@ -31,8 +31,8 @@
\include debug.h
\htmlonly «<A HREF="../external/debug.h">download</A>»\endhtmlonly
-This %debug.h file is for applications, for more detailed information and for information
-for library developers who want to use libbcwd, please also read \ref chapter_custom_debug_h.
+This %debug.h file is for applications; for more detailed information and for information
+for library developers who want to use libcwd, please also read \ref chapter_custom_debug_h.
\subsection custom_debug_cc Step 3: Creating the custom source file
Index: src/libcwd/documentation/reference.dox
diff -u src/libcwd/documentation/reference.dox:1.1.2.3 src/libcwd/documentation/reference.dox:1.1.2.4
--- src/libcwd/documentation/reference.dox:1.1.2.3 Wed Dec 5 22:01:16 2001
+++ src/libcwd/documentation/reference.dox Fri Dec 7 18:06:23 2001
@@ -6,17 +6,17 @@
<ul>
<li>\ref book_writing_intro
<li>\ref group_destination
- <li>\ref chapter_debug_object
+ <li>\ref group_debug_object
<ul>
<li>\ref chapter_custom_do
</ul>
- <li>\ref chapter_debug_channels
+ <li>\ref group_debug_channels
<ul>
<li>\ref group_default_dc
</ul>
<li>\ref group_control_flags
<li>\ref group_formatting
- <li>\ref chapter_fatal_output
+ <li>\ref group_fatal_output
<li>\ref chapter_nesting
<li>\ref group_special
</ul>
@@ -27,12 +27,12 @@
<li>\ref chapter_validation
<li>\ref chapter_magic_numbers
<li>\ref group_annotation
- <li>\ref chapter_overview
+ <li>\ref group_overview
<ul>
<li>\ref group_invisible
</ul>
<li>\ref group_finding
- <li>\ref chapter_markers
+ <li>\ref group_markers
</ul>
<h2>Program Symbols Access And Interpretation</h2>
@@ -50,16 +50,6 @@
<li>\ref chapter_custom_debug_h
<li>\ref chapter_alloc_locations
<li>\ref group_configuration
- <ul>
- <li>\ref enable_libcwd_alloc
- <li>\ref enable_libcwd_magic
- <li>\ref enable_libcwd_location
- <li>\ref enable_libcwd_libbfd
- <li>\ref enable_libcwd_debug
- <li>\ref enable_libcwd_debugoutput
- <li>\ref enable_libcwd_debugm
- <li>\ref enable_libcwd_marker
- </ul>
</ul>
*/
Index: src/libcwd/documentation/why_macro.dox
diff -u src/libcwd/documentation/why_macro.dox:1.1.2.1 src/libcwd/documentation/why_macro.dox:1.1.2.2
--- src/libcwd/documentation/why_macro.dox:1.1.2.1 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/why_macro.dox Fri Dec 7 18:06:23 2001
@@ -2,14 +2,14 @@
\page page_why_macro Design Consideration Concerning Macros
-This page describes why we use a macro in stead of an inline
+This page describes why we use a macro instead of an inline
function for <CODE>Dout()</CODE>.
-Good C++ code should not use macros, but <CODE>inline</CODE> functions which
+Good C++ code whenever possible, 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:
+Using a macro has its advantages however:
<OL>
<LI>It inlines the debug code even when we don't use optimization.
@@ -19,43 +19,43 @@
<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
+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 deciding to
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:
+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.
+In most cases the debug code will be compiled and used <em>without</em> compiler optimization; including
+the fact that no inlining is done.
Moreover, we expect to use a lot of inserter operators and without
-optimization, each of these which will be called.
+optimization, each of these 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>).
+something else than an <CODE>ostream</CODE> (let's 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) ].
+without inlining (point 5 above) ].
-2. Lets develop an example, step by step which is writing debug output.
+2. Let's develop step by step an example where we write debug output.
-Lets start with writing some example debug output to <CODE>cerr</CODE>.
+Let's 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
+This line calls seven functions. If we want to save CPU time 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.
+After all, such an operator call can use a lot of CPU time 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
+It is necessary to write to a new class (let's 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>:
Index: src/libcwd/documentation/writing_intro.dox
diff -u src/libcwd/documentation/writing_intro.dox:1.1.2.1 src/libcwd/documentation/writing_intro.dox:1.1.2.2
--- src/libcwd/documentation/writing_intro.dox:1.1.2.1 Wed Dec 5 22:01:16 2001
+++ src/libcwd/documentation/writing_intro.dox Fri Dec 7 18:06:23 2001
@@ -11,7 +11,7 @@
Libcwd is an <code>ostream</code> oriented debug output facility.
The class libcw::debug::debug_ct represents a single <code>ostream</code>.
-Libcwd defines and uses only one such object, called a \ref chapter_debug_object "debug object",
+Libcwd defines and internally uses only one object of that class, called a \ref group_debug_object "debug object",
being libcw::debug::libcw_do.
Debug output is written using \ref page_why_macro "macros" (\ref Dout and \ref DoutFatal),
@@ -19,8 +19,8 @@
More general macros exist (\ref LibcwDout and \ref LibcwDoutFatal) that allow you
to use a different (\ref chapter_custom_do "custom") debug object.
-Both macros take two arguments, the first argument is used to specify
-\ref chapter_debug_channels "debug channels" and \ref group_control_flags "control flags"
+\ref Dout and \ref DoutFatal take two arguments: the first argument is used to specify
+\ref group_debug_channels "debug channels" and \ref group_control_flags "control flags"
while the second argument should be a series of objects seperated by <code><<</code>
that you want to write to the <code>ostream</code>.
@@ -30,8 +30,8 @@
Dout(dc::notice|blank_label_cf|flush_cf, "Total count: " << count << "; Average: " << average);
\endcode
-In this example <code>dc::notice</code> is one of the \ref group_default_dc "pre-defined" debug channels.
-Debug channels are intended to control to amount of output of your application by switching
-the channels on or off.
+In this example <code>dc::notice</code> is one of the \ref group_default_dc "predefined" debug channels.
+Debug channels are intended to control the amount of output of your application:
+you can switch the channels on and off.
*/
Index: src/libcwd/include/libcw/buf2str.h
diff -u src/libcwd/include/libcw/buf2str.h:1.5.2.10 src/libcwd/include/libcw/buf2str.h:1.5.2.11
--- src/libcwd/include/libcw/buf2str.h:1.5.2.10 Wed Dec 5 22:01:16 2001
+++ src/libcwd/include/libcw/buf2str.h Fri Dec 7 18:06:23 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/buf2str.h,v 1.5.2.10 2001/12/06 06:01:16 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/buf2str.h,v 1.5.2.11 2001/12/08 02:06:23 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -62,22 +62,23 @@
class buf2str {
private:
- char const* M_buf;
- size_t M_size;
+ char const* M_buf; //!< Pointer to the start of the buffer.
+ size_t M_size; //!< The size of the buffer.
public:
+ //! Construct \c buf2str object with attributes \a buf and \a size.
buf2str(char const* buf, size_t size) : M_buf(buf), M_size(size) { }
- //
- // Note: This function is only intended for debugging purposes,
- // it is not a good idea to use it in the final compilation.
- //
+ /**
+ * \brief Write the contents of the buffer represented by \a __buf2str
+ * to the \c ostream \a os, escaping non-printable characters.
+ */
friend
__inline__
std::ostream&
operator<<(std::ostream& os, buf2str const& __buf2str)
{
- register size_t size = __buf2str.M_size;
+ size_t size = __buf2str.M_size;
for (char const* p1 = __buf2str.M_buf; size > 0; --size, p1++)
os << char2str(*p1);
return os;
Index: src/libcwd/include/libcw/char2str.h
diff -u src/libcwd/include/libcw/char2str.h:1.5.2.10 src/libcwd/include/libcw/char2str.h:1.5.2.11
--- src/libcwd/include/libcw/char2str.h:1.5.2.10 Wed Dec 5 22:01:16 2001
+++ src/libcwd/include/libcw/char2str.h Fri Dec 7 18:06:23 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/char2str.h,v 1.5.2.10 2001/12/06 06:01:16 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/char2str.h,v 1.5.2.11 2001/12/08 02:06:23 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -53,11 +53,20 @@
class char2str {
private:
- char c;
+ char c; //!< The character to be printed.
+
+private:
void print_char_to(std::ostream&) const;
void print_escaped_char_to(std::ostream&) const;
+
public:
+ //! Construct a \c char2str object with attribute \a ci.
char2str(char ci) : c(ci) { }
+
+ /**
+ * \brief Write the character represented by \a c2s to the \c ostream \a os,
+ * escaping it when it is a non-printable character.
+ */
friend __inline__ std::ostream& operator<<(std::ostream& os, char2str const c2s)
{
if ((c2s.c > 31 && c2s.c != 92 && c2s.c != 127) || (unsigned char)c2s.c > 159)
Index: src/libcwd/include/libcw/class_alloc.h
diff -u src/libcwd/include/libcw/class_alloc.h:1.1.2.4 src/libcwd/include/libcw/class_alloc.h:1.1.2.5
--- src/libcwd/include/libcw/class_alloc.h:1.1.2.4 Wed Dec 5 22:01:16 2001
+++ src/libcwd/include/libcw/class_alloc.h Fri Dec 7 18:06:23 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_alloc.h,v 1.1.2.4 2001/12/06 06:01:16 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_alloc.h,v 1.1.2.5 2001/12/08 02:06:23 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -53,19 +53,16 @@
*/
class alloc_ct {
protected:
- void const* a_start; // Duplicate of (original) memblk_key_ct
- size_t a_size; // Duplicate of (original) memblk_key_ct
- memblk_types_nt a_memblk_type; // A flag which indicates the type of allocation
- type_info_ct const* type_info_ptr; // Type info of related object
- lockable_auto_ptr<char, true> a_description; // A label describing this memblk
+ void const* a_start; //!< Duplicate of (original) memblk_key_ct.
+ size_t a_size; //!< Duplicate of (original) memblk_key_ct.
+ memblk_types_nt a_memblk_type; //!< A flag which indicates the type of allocation.
+ type_info_ct const* type_info_ptr; //!< Type info of related object.
+ lockable_auto_ptr<char, true> a_description; //!< A label describing this memblk.
#ifdef DEBUGUSEBFD
- location_ct M_location; // Source file, function and line number from where
- // the allocator was called from
+ location_ct M_location; //!< Source file, function and line number from where the allocator was called from.
#endif
-public:
- alloc_ct(void const* s, size_t sz, memblk_types_nt type, type_info_ct const& ti) :
- a_start(s), a_size(sz), a_memblk_type(type), type_info_ptr(&ti) { }
+public:
/**
* \brief The allocated size in bytes.
*/
@@ -84,7 +81,8 @@
/**
* \brief A reference to the type info of the pointer to the allocated memory block.
*
- * \returns a reference to the static \ref type_info_ct object that is returned by a call to \ref type_info_of(p1).
+ * \returns a reference to the static \ref type_info_ct object that is returned
+ * by a call to \ref libcw::debug::type_info_of "type_info_of"(p1).
* Where \p p1 is the first parameter that was passed to \ref AllocTag().
*/
type_info_ct const& type_info(void) const { return *type_info_ptr; }
@@ -101,7 +99,7 @@
* \brief The source file location that the allocator was called from.
*
* \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.
+ * Class \ref location_ct describes a source file and line number location and in which function that location resides.
* \sa \ref chapter_alloc_locations
*/
location_ct& location_reference(void) { return M_location; }
@@ -115,7 +113,22 @@
*/
location_ct const& location(void) const { return M_location; }
#endif
+
protected:
+ /**
+ * \brief Construct an \c alloc_ct object with attributes \a s, \a sz, \a type and \a ti.
+ * \internal
+ */
+ alloc_ct(void const* s, size_t sz, memblk_types_nt type, type_info_ct const& ti) :
+ a_start(s), a_size(sz), a_memblk_type(type), type_info_ptr(&ti) { }
+
+ /**
+ * \brief Destructor.
+ * \internal
+ *
+ * The destructor is virtual because libcwd really creates dm_alloc_ct
+ * objects, objects \em derived from alloc_ct, using <code>operator new</code>.
+ */
virtual ~alloc_ct() { }
};
Index: src/libcwd/include/libcw/class_channel.h
diff -u src/libcwd/include/libcw/class_channel.h:1.1.2.7 src/libcwd/include/libcw/class_channel.h:1.1.2.8
--- src/libcwd/include/libcw/class_channel.h:1.1.2.7 Wed Dec 5 22:01:16 2001
+++ src/libcwd/include/libcw/class_channel.h Fri Dec 7 18:06:23 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_channel.h,v 1.1.2.7 2001/12/06 06:01:16 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_channel.h,v 1.1.2.8 2001/12/08 02:06:23 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -34,16 +34,12 @@
namespace libcw {
namespace debug {
-//===================================================================================================
-// class channel_ct
-//
-// This object represents a debug channel, it has a fixed label.
-// A debug channel can be viewed upon as a single bit: on or off.
-//
-
-/** \class channel_ct debug.h libcw/debug.h
+/**
+ * \class channel_ct class_channel.h libcw/debug.h
+ * \ingroup group_debug_channels
*
- * \brief The %Debug Channel class.
+ * \brief This object represents a debug channel, it has a fixed label.
+ * A debug channel can be viewed upon as a single bit: on or off.
*
* Whenever %debug output is written, one or more %debug %channels must be specified (as first
* parameter of the \ref Dout macro).
@@ -112,16 +108,10 @@
// MT: All channel objects must be global so that `WNS_initialized' is false
// at the start of the program and initialization occurs before other threads
// share the object.
- /**
- * \brief Constructor
- *
- * Constructor for an arbitrary new %debug channel with name \a label.
- * A newly created channel is off by default (except <CODE>dc::warning</CODE>).
- */
explicit channel_ct(char const* label);
// MT: May only be called from the constructors of global objects (or single threaded functions).
- void NS_initialize(char const* lbl);
+ void NS_initialize(char const* label);
// Force initialization in case the constructor of this global object
// wasn't called yet. Does nothing when the object was already initialized.
@@ -130,18 +120,7 @@
// Manipulators
//
- /**
- * \brief Turn this channel off.
- *
- * \sa on()
- */
void off(void);
-
- /**
- * \brief Cancel one call to `off()'.
- *
- * The channel is turned on when on() is called as often as off() was called before.
- */
void on(void);
public:
@@ -149,22 +128,12 @@
// Accessors
//
- /**
- * \brief Pointer to the label of the %debug channel.
- */
char const* get_label(void) const;
-
- /**
- * \brief Returns `true' if the channel is active.
- */
bool is_on(void) const;
#ifdef _REENTRANT
bool is_on(LIBCWD_TSD_PARAM) const;
#endif
};
-
-// End of declaration of class channel_ct.
-//===================================================================================================
} // namespace debug
} // namespace libcw
Index: src/libcwd/include/libcw/class_channel.inl
diff -u src/libcwd/include/libcw/class_channel.inl:1.1.2.2 src/libcwd/include/libcw/class_channel.inl:1.1.2.3
--- src/libcwd/include/libcw/class_channel.inl:1.1.2.2 Sat Oct 20 19:19:32 2001
+++ src/libcwd/include/libcw/class_channel.inl Fri Dec 7 18:06:23 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_channel.inl,v 1.1.2.2 2001/10/21 02:19:32 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_channel.inl,v 1.1.2.3 2001/12/08 02:06:23 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -24,10 +24,18 @@
namespace libcw {
namespace debug {
+/**
+ * \brief Construct a new %debug channel with name \a label.
+ *
+ * A newly created channel is off by default (except \ref libcw::debug::channels::dc::warning "dc::warning").
+ * All channel objects must be global objects.
+ *
+ * \sa \ref chapter_custom_debug_h
+ */
__inline__
-channel_ct::channel_ct(char const* lbl)
+channel_ct::channel_ct(char const* label)
{
- NS_initialize(lbl);
+ NS_initialize(label);
}
#ifdef _REENTRANT
@@ -39,6 +47,10 @@
}
#endif
+
+/**
+ * \brief Returns `true' if the channel is active.
+ */
__inline__
bool
channel_ct::is_on(void) const
@@ -51,6 +63,9 @@
#endif
}
+/**
+ * \brief Pointer to the label of the %debug channel.
+ */
__inline__
char const*
channel_ct::get_label(void) const
Index: src/libcwd/include/libcw/class_debug.h
diff -u src/libcwd/include/libcw/class_debug.h:1.1.2.9 src/libcwd/include/libcw/class_debug.h:1.1.2.10
--- src/libcwd/include/libcw/class_debug.h:1.1.2.9 Wed Dec 5 22:01:16 2001
+++ src/libcwd/include/libcw/class_debug.h Fri Dec 7 18:06:23 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_debug.h,v 1.1.2.9 2001/12/06 06:01:16 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/Attic/class_debug.h,v 1.1.2.10 2001/12/08 02:06:23 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -59,14 +59,18 @@
/**
* \class debug_ct debug.h libcw/debug.h
- * \ingroup chapter_debug_object
+ * \ingroup group_debug_object
*
- * \brief The %Debug Object class.
+ * \brief The %Debug Object class, this object represents one output device (<code>ostream</code>).
*
- * See \ref chapter_debug_object.
+ * See \ref group_debug_object.
*/
class debug_ct {
+#ifdef DOXYGEN
+protected:
+#else
public: // Direct access needed in macro LibcwDout(). Do not write to these.
+#endif
int _off;
// Debug output is turned on when this variable is -1, otherwise it is off.
@@ -161,29 +165,16 @@
// Manipulators and accessors for the above "format" attributes:
//
- /** \addtogroup group_formatting */
- /* \{ */
-
- /** \brief Set number of spaces to indent. */
void set_indent(unsigned short indentation);
- /** \brief Increment number of spaces to indent. */
void inc_indent(unsigned short indentation);
- /** \brief Decrement number of spaces to indent. */
void dec_indent(unsigned short indentation);
- /** \brief Get the current indentation. */
unsigned short get_indent(void) const;
- /** \brief Push the current margin on a stack */
void push_margin(void);
- /** \brief Pop margin from the stack */
void pop_margin(void);
- /** \brief Push the current marker on a stack */
void push_marker(void);
- /** \brief Pop marker from the stack */
void pop_marker(void);
- /** \} */
-
// Deprecated (last documented in 0.99.15)
void set_margin(std::string const& ...
[truncated message content] |
