Hack out -DL documentation from perldebuguts.pod

Now that the perl core uses Newx*() rather than New*() this chunk
of old documentation is more obsolete than ever before.

p4raw-id: //depot/perl@25118

1 files changed, 2 insertions, 152 deletions

diff --git a/pod/perldebguts.pod b/pod/perldebguts.pod
index 7cce15631a..6bc2c3781c 100644
--- a/pod/perldebguts.pod
+++ b/pod/perldebguts.pod
@@ -753,7 +753,8 @@ The B<-DL> command-line switch is obsolete since circa Perl 5.6.0
 (it was available only if Perl was built with C<-DDEBUGGING>).
 The switch was used to track Perl's memory allocations and possible
 memory leaks.  These days the use of malloc debugging tools like
-F<Purify> or F<valgrind> is suggested instead.
+F<Purify> or F<valgrind> is suggested instead.  See also
+L<perlhack/PERL_MEM_LOG>.
 
 One way to find out how much memory is being used by Perl data
 structures is to install the Devel::Size module from CPAN: it gives
@@ -867,157 +868,6 @@ never touched.
 
 =back
 
-=head2 Example of using B<-DL> switch
-
-(Note that -DL is obsolete since circa 5.6.0, and even before that
-Perl needed to be compiled with -DDEBUGGING.)
-
-Below we show how to analyse memory usage by 
-
-  do 'lib/auto/POSIX/autosplit.ix';
-
-The file in question contains a header and 146 lines similar to
-
-  sub getcwd;
-
-B<WARNING>: The discussion below supposes 32-bit architecture.  In 
-newer releases of Perl, memory usage of the constructs discussed
-here is greatly improved, but the story discussed below is a real-life
-story.  This story is mercilessly terse, and assumes rather more than cursory
-knowledge of Perl internals.  Type space to continue, `q' to quit. 
-(Actually, you just want to skip to the next section.)
-
-Here is the itemized list of Perl allocations performed during parsing
-of this file:
-
- !!! "after" at test.pl line 3.
-    Id  subtot   4   8  12  16  20  24  28  32  36  40  48  56  64  72  80 80+
-  0 02   13752   .   .   .   . 294   .   .   .   .   .   .   .   .   .   .   4
-  0 54    5545   .   .   8 124  16   .   .   .   1   1   .   .   .   .   .   3
-  5 05      32   .   .   .   .   .   .   .   1   .   .   .   .   .   .   .   .
-  6 02    7152   .   .   .   .   .   .   .   .   .   . 149   .   .   .   .   .
-  7 02    3600   .   .   .   .   . 150   .   .   .   .   .   .   .   .   .   .
-  7 03      64   .  -1   .   1   .   .   2   .   .   .   .   .   .   .   .   .
-  7 04    7056   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   7
-  7 17   38404   .   .   .   .   .   .   .   1   .   . 442 149   .   . 147   .
-  9 03    2078  17 249  32   .   .   .   .   2   .   .   .   .   .   .   .   .
-
-
-To see this list, insert two C<warn('!...')> statements around the call:
-
-  warn('!');
-  do 'lib/auto/POSIX/autosplit.ix';
-  warn('!!! "after"');
-
-and run it with Perl's B<-DL> option.  The first warn() will print
-memory allocation info before parsing the file and will memorize
-the statistics at this point (we ignore what it prints).  The second
-warn() prints increments with respect to these memorized data.  This
-is the printout shown above.
-
-Different I<Id>s on the left correspond to different subsystems of
-the perl interpreter.  They are just the first argument given to
-the perl memory allocation API named New().  To find what C<9 03>
-means, just B<grep> the perl source for C<903>.  You'll find it in
-F<util.c>, function savepvn().  (I know, you wonder why we told you
-to B<grep> and then gave away the answer.  That's because grepping
-the source is good for the soul.)  This function is used to store
-a copy of an existing chunk of memory.  Using a C debugger, one can
-see that the function was called either directly from gv_init() or
-via sv_magic(), and that gv_init() is called from gv_fetchpv()--which
-was itself called from newSUB().  Please stop to catch your breath now.
-
-B<NOTE>: To reach this point in the debugger and skip the calls to
-savepvn() during the compilation of the main program, you should
-set a C breakpoint
-in Perl_warn(), continue until this point is reached, and I<then> set
-a C breakpoint in Perl_savepvn().  Note that you may need to skip a
-handful of Perl_savepvn() calls that do not correspond to mass production
-of CVs (there are more C<903> allocations than 146 similar lines of
-F<lib/auto/POSIX/autosplit.ix>).  Note also that C<Perl_> prefixes are
-added by macroization code in perl header files to avoid conflicts
-with external libraries.
-
-Anyway, we see that C<903> ids correspond to creation of globs, twice
-per glob - for glob name, and glob stringification magic.
-
-Here are explanations for other I<Id>s above: 
-
-=over 4
-
-=item C<717> 
-
-Creates bigger C<XPV*> structures.  In the case above, it
-creates 3 C<AV>s per subroutine, one for a list of lexical variable
-names, one for a scratchpad (which contains lexical variables and
-C<targets>), and one for the array of scratchpads needed for
-recursion.  
-
-It also creates a C<GV> and a C<CV> per subroutine, all called from
-start_subparse().
-
-=item C<002>
-
-Creates a C array corresponding to the C<AV> of scratchpads and the
-scratchpad itself.  The first fake entry of this scratchpad is
-created though the subroutine itself is not defined yet.
-
-It also creates C arrays to keep data for the stash.  This is one HV,
-but it grows; thus, there are 4 big allocations: the big chunks are not
-freed, but are kept as additional arenas for C<SV> allocations.
-
-=item C<054>
-
-Creates a C<HEK> for the name of the glob for the subroutine.  This
-name is a key in a I<stash>.
-
-Big allocations with this I<Id> correspond to allocations of new
-arenas to keep C<HE>.
-
-=item C<602>
-
-Creates a C<GP> for the glob for the subroutine.
-
-=item C<702>
-
-Creates the C<MAGIC> for the glob for the subroutine.
-
-=item C<704>
-
-Creates I<arenas> which keep SVs.
-
-=back
-
-=head2 B<-DL> details
-
-If Perl is run with B<-DL> option, then warn()s that start with `!'
-behave specially.  They print a list of I<categories> of memory
-allocations, and statistics of allocations of different sizes for
-these categories.
-
-If warn() string starts with
-
-=over 4
-
-=item C<!!!> 
-
-print changed categories only, print the differences in counts of allocations.
-
-=item C<!!> 
-
-print grown categories only; print the absolute values of counts, and totals.
-
-=item C<!>
-
-print nonempty categories, print the absolute values of counts and totals.
-
-=back
-
-=head2 Limitations of B<-DL> statistics
-
-If an extension or external library does not use the Perl API to
-allocate memory, such allocations are not counted.
-
 =head1 SEE ALSO
 
 L<perldebug>,