First pass at documentation for the debugging options in APR's

memory allocation. Mainly just the comments from apr_pools.c. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@85608 13f79535-47bb-0310-9956-ffa450edef68
author: David Reid <dreid@apache.org> 2000-06-18 12:41:32 +0200
committer: David Reid <dreid@apache.org> 2000-06-18 12:41:32 +0200
commit: b4dfc95a12cdeffb31803e706a09b120e3de68a8 (patch)
tree: 29fff8759f10cbcb74c20cdaf682b117e7a8f382 /docs
parent: Use the new command-handler initializer macros in a few more modules, (diff)
download: apache2-b4dfc95a12cdeffb31803e706a09b120e3de68a8.tar.xz
apache2-b4dfc95a12cdeffb31803e706a09b120e3de68a8.zip
2 files changed, 176 insertions, 0 deletions
diff --git a/docs/manual/developer/debugging.html b/docs/manual/developer/debugging.html
new file mode 100644
index 0000000000..2cb210f732
--- /dev/null
+++ b/docs/manual/developer/debugging.html
@@ -0,0 +1,175 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+<TITLE>Debugging Memory Allocation in APR</TITLE>
+</HEAD>
+
+<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+<BODY
+ BGCOLOR="#FFFFFF"
+ TEXT="#000000"
+ LINK="#0000FF"
+ VLINK="#000080"
+ ALINK="#FF0000"
+>
+
+<H1 ALIGN="CENTER">Debugging Memory Allocation in APR<br></H1>
+
+<p>The allocation mechanism's within APR have a number of debugging
+modes that can be used to assist in finding memory problems.  This document describes
+the modes available and gives instructions on activating them.</p>
+
+<ul>
+<li><a href="#options">Available debugging options</a></li>
+<li><a href="#combo">Allowable combinations</a></li>
+<li><a href="#howto">How to activate debugging</a></li>
+</ul>
+
+<hr>
+<a name="options">
+<h2>Allocation Debugging</h2>
+
+<h3>ALLOC_DEBUG</h3>
+<p><em>Debugging support: Define this to enable code which helps detect re-use of freed memory and other such nonsense.</em></p>
+
+<p>The theory is simple.  The FILL_BYTE (0xa5) is written over all malloc'd memory as we receive it, and is written over everything that we free up during a clear_pool.  We check that blocks on the free list always have the FILL_BYTE in them, and we check during palloc() that the bytes still have FILL_BYTE in them.  If you ever see garbage URLs or whatnot containing lots of 0xa5s then you know something used data that's been freed or uninitialized.</p>
+
+<h2>Malloc Support</h2>
+<h3>ALLOC_USE_MALLOC</h3>
+<p><em>If defined all allocations will be done with malloc and free()d appropriately at the end.
+</em></p>
+
+<p>This is intended to be used with something like Electric Fence or Purify to help detect memory problems.  Note that if you're using efence then you should also add in ALLOC_DEBUG.  But don't add in ALLOC_DEBUG if you're using Purify because ALLOC_DEBUG would hide all the uninitialized read errors that Purify can diagnose.</p>
+
+<h2>Pool Debugging</h2>
+<h3>POOL_DEBUG</h3>
+<p><em>This is intended to detect cases where the wrong pool is used when assigning data to an object in another pool.</em></p>
+
+<p>In particular, it causes the table_{set,add,merge}n routines to check that their arguments are safe for the ap_table_t they're being placed in.  It currently only works with the unix multiprocess model, but could be extended to others.</p>
+
+<h2>Table Debugging</h2>
+<h3>MAKE_TABLE_PROFILE</h3>
+<p><em>Provide diagnostic information about make_table() calls which are possibly too small.</em></p>
+
+<p>This requires a recent gcc which supports __builtin_return_address().  The error_log output will be a message such as: </p>
+<pre>table_push: ap_table_t created by 0x804d874 hit limit of 10</pre>
+<p>Use "<em><strong>l *0x804d874</strong></em>" to find the source that corresponds to.  It
+ indicates that a ap_table_t allocated by a call at that address has possibly too small an initial ap_table_t size guess.</p>
+
+<h2>Allocation Statistics</h2>
+<h3>ALLOC_STATS</h3>
+<p><em>Provide some statistics on the cost of allocations.</em></p>
+
+<p>This requires a bit of an understanding of how alloc.c works.</p>
+
+<hr>
+
+<a name="combo">
+<h2>Allowable Combinations</h2>
+
+<p>Not all the options outlined above can be activated at the same time.  the following table gives more information.</p>
+
+<p align="center">
+<table width="80%">
+<tr>
+<th width="25%">Option 1</th>
+<th width="15%">ALLOC<br>DEBUG</th>
+<th width="15%">ALLOC<br>USE<br>MALLOC</th>
+<th width="15%">POOL<br>DEBUG</th>
+<th width="15%">MAKE<br>TABLE<br>PROFILE</th>
+<th width="15%">ALLOC<br>STATS</th>
+</tr>
+<tr>
+<td>ALLOC_DEBUG</td>
+<td bgcolor="#ff0000">&nbsp;</td>
+<td align="center">No</td>
+<td align="center">Yes</td>
+<td align="center">Yes</td>
+<td align="center">Yes</td>
+</tr>
+<tr>
+<td>ALLOC_USE<br>MALLOC</td>
+<td align="center">No</td>
+<td bgcolor="#ff0000">&nbsp;</td>
+<td align="center">No</td>
+<td align="center">No</td>
+<td align="center">No</td>
+</tr>
+<tr>
+<td>POOL_DEBUG</td>
+<td align="center">Yes</td>
+<td align="center">No</td>
+<td bgcolor="#ff0000">&nbsp;</td>
+<td align="center">Yes</td>
+<td align="center">Yes</td>
+</tr>
+<tr>
+<td>MAKE_TABLE<br>PROFILE</td>
+<td align="center">Yes</td>
+<td align="center">No</td>
+<td align="center">Yes</td>
+<td bgcolor="#ff0000">&nbsp;</td>
+<td align="center">Yes</td>
+</tr>
+<tr>
+<td>ALLOC_STATS</td>
+<td align="center">Yes</td>
+<td align="center">No</td>
+<td align="center">Yes</td>
+<td align="center">Yes</td>
+<td bgcolor="#ff0000">&nbsp;</td>
+</tr>
+
+</table>
+
+<p>Additionally the debugging options are not suitable for multi-threaded versions of the server.  When trying to debug with these options the server should be started in single process mode.</p>
+
+<hr>
+
+<a name="howto">
+<h2>Activating Debugging Options</h2>
+<p>The various options for debugging memory are now enabled in the apr_general.h header file in APR.  The various options are enabled by uncommenting the define for the option you wish to use.  The section of the code currently looks like this <em>(contained in src/lib/apr/inclide/apr_general.h)</em></p>
+
+<pre>
+/*
+#define ALLOC_DEBUG
+#define POOL_DEBUG
+#define ALLOC_USE_MALLOC
+#define MAKE_TABLE_PROFILE
+#define ALLOC_STATS
+*/
+
+typedef struct ap_pool_t {
+    union block_hdr *first;
+    union block_hdr *last;
+    struct cleanup *cleanups;
+    struct process_chain *subprocesses;
+    struct ap_pool_t *sub_pools;
+    struct ap_pool_t *sub_next;
+    struct ap_pool_t *sub_prev;
+    struct ap_pool_t *parent;
+    char *free_first_avail;
+#ifdef ALLOC_USE_MALLOC
+    void *allocation_list;
+#endif
+#ifdef POOL_DEBUG
+    struct ap_pool_t *joined;
+#endif
+    int (*apr_abort)(int retcode);
+    struct datastruct *prog_data;
+}ap_pool_t;
+</pre>
+
+<p>To enable allocation debugging simply move the #define ALLOC_DEBUG above the start of the comments block and rebuild the server.</p>
+
+<h3>NB. In order to use the various options the server MUST be rebuilt after editing the header file.
+</h3>
+
+
+</body>
+</html>
+
+
+
+
+
diff --git a/docs/manual/developer/index.html b/docs/manual/developer/index.html
index 2f1810d908..e795744e6d 100644
--- a/docs/manual/developer/index.html
+++ b/docs/manual/developer/index.html
@@ -15,5 +15,6 @@
 <p><a href="hooks.html">Apache Hook Functions</a></p>
 <p><a href="modules.html">Converting Apache 1.3 Modules to Apache 2.0</a></p>
 <p><a href="../mpm.html">MPM listing</a></p>
+<p><a href="debugging.html">Debugging Memory Allocation in APR</a></p>
 </body>
 </html>
author	David Reid <dreid@apache.org>	2000-06-18 12:41:32 +0200
committer	David Reid <dreid@apache.org>	2000-06-18 12:41:32 +0200
commit	b4dfc95a12cdeffb31803e706a09b120e3de68a8 (patch)
tree	29fff8759f10cbcb74c20cdaf682b117e7a8f382 /docs
parent	Use the new command-handler initializer macros in a few more modules, (diff)
download	apache2-b4dfc95a12cdeffb31803e706a09b120e3de68a8.tar.xz apache2-b4dfc95a12cdeffb31803e706a09b120e3de68a8.zip