From 35060cb8bac165cc46d789d177c036d72e5026e6 Mon Sep 17 00:00:00 2001 From: Rich Bowen Date: Fri, 11 Nov 2011 18:21:07 +0000 Subject: [PATCH] Axe outdated resources, broken links, in developer docs. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1201011 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/developer/debugging.xml | 165 +--------------------------- docs/manual/developer/index.xml | 29 ++--- 2 files changed, 10 insertions(+), 184 deletions(-) diff --git a/docs/manual/developer/debugging.xml b/docs/manual/developer/debugging.xml index 9a579f7301..ed913462da 100644 --- a/docs/manual/developer/debugging.xml +++ b/docs/manual/developer/debugging.xml @@ -26,169 +26,10 @@ Debugging Memory Allocation in APR -

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. +

-
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.

-
-
- -
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.

-
- -
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.

- -
diff --git a/docs/manual/developer/index.xml b/docs/manual/developer/index.xml index 296792dcef..7121f2952d 100644 --- a/docs/manual/developer/index.xml +++ b/docs/manual/developer/index.xml @@ -23,28 +23,27 @@ -Developer Documentation for Apache 2.0 +Developer Documentation for Apache 2.x -

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.

+
Topics @@ -52,24 +51,10 @@
External Resources