From 70e302b586f0b003882552cf04148556836db61e Mon Sep 17 00:00:00 2001 From: Rich Bowen Date: Fri, 11 Nov 2011 18:27:37 +0000 Subject: [PATCH] Rebuild developer docs - remove outdated stuff and add warning about the state of the developer docs. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1201014 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/developer/debugging.html.en | 173 +----------------------- docs/manual/developer/index.html.en | 27 ++-- 2 files changed, 13 insertions(+), 187 deletions(-) diff --git a/docs/manual/developer/debugging.html.en b/docs/manual/developer/debugging.html.en index 2d63b74ca5..2519cd0e0c 100644 --- a/docs/manual/developer/debugging.html.en +++ b/docs/manual/developer/debugging.html.en @@ -10,7 +10,7 @@ -
+

Modules | Directives | FAQ | Glossary | Sitemap

Apache HTTP Server Version 2.3

@@ -21,174 +21,11 @@

Available Languages:  en 

-

The allocation mechanisms 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.

+

+ This document has been removed. +

+ -
-
top
-
-

Available debugging options

-

Allocation Debugging - ALLOC_DEBUG

- - -
Debugging support: Define this to enable code which - helps detect re-use of free()d memory and other such - nonsense.
- -

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.

- - -

Malloc Support - ALLOC_USE_MALLOC

- - -
If defined all allocations will be done with - malloc() and free()d appropriately at the - end.
- -

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.

- - -

Pool Debugging - POOL_DEBUG

-
This is intended to detect cases where the wrong pool is - used when assigning data to an object in another pool.
- -

In particular, it causes the table_{set,add,merge}n - routines to check that their arguments are safe for the - apr_table_t they're being placed in. It currently only works - with the unix multiprocess model, but could be extended to others.

- - -

Table Debugging - MAKE_TABLE_PROFILE

- - -
Provide diagnostic information about make_table() calls - which are possibly too small.
- -

This requires a recent gcc which supports - __builtin_return_address(). The error_log output will be a - message such as:

-

- table_push: apr_table_t created by 0x804d874 hit limit of 10 -

- -

Use l *0x804d874 to find the - source that corresponds to. It indicates that a apr_table_t - allocated by a call at that address has possibly too small an - initial apr_table_t size guess.

- - -

Allocation Statistics - ALLOC_STATS

- - -
Provide some statistics on the cost of allocations.
- -

This requires a bit of an understanding of how alloc.c - works.

- -
top
-
-

Allowable Combinations

- -

Not all the options outlined above can be activated at the - same time. the following table gives more information.

- - - - - - - - - - - - - - - - -
- ALLOC DEBUGALLOC USE MALLOCPOOL DEBUGMAKE TABLE PROFILEALLOC STATS
ALLOC DEBUG-NoYesYesYes
ALLOC USE MALLOCNo-NoNoNo
POOL DEBUGYesNo-YesYes
MAKE TABLE PROFILEYesNoYes-Yes
ALLOC STATSYesNoYesYes-
- -

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.

-
top
-
-

Activating Debugging Options

- -

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 - (contained in srclib/apr/include/apr_pools.h)

- -

- /*
- #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; -

- -

To enable allocation debugging simply move the #define - ALLOC_DEBUG above the start of the comments block and rebuild - the server.

- -

Note

-

In order to use the various options the server must - be rebuilt after editing the header file.

-
-

Available Languages:  en 

<-
-Apache > HTTP Server > Documentation > Version 2.3

Developer Documentation for Apache 2.0

+Apache > HTTP Server > Documentation > Version 2.3

Developer Documentation for Apache 2.x

Available Languages:  en  |  zh-cn 

-

Many of the documents on these Developer pages are lifted - from Apache 1.3's documentation. While they are all being - updated to Apache 2, they are in different stages of - progress. Please be patient, and point out any discrepancies or +

Warning

+

Many of the documents listed here are in need of update. + They are in different stages of progress. + Please be patient, and point out any discrepancies or errors on the developer/ pages directly to the dev@httpd.apache.org mailing list.

+