diff options
| -rw-r--r-- | pod/perlhack.pod | 50 | ||||
| -rw-r--r-- | pod/perlobj.pod | 1 | ||||
| -rw-r--r-- | pod/perlrun.pod | 2 |
3 files changed, 45 insertions, 8 deletions
diff --git a/pod/perlhack.pod b/pod/perlhack.pod index 1f398a4fce..490049b394 100644 --- a/pod/perlhack.pod +++ b/pod/perlhack.pod @@ -1683,14 +1683,50 @@ DEC OSF/1). When building Perl, you must first run Configure with -Doptimize=-g and -Uusemymalloc flags, after that you can use the make targets +"perl.third" and "test.third". -"perl.third" and "test.third". The short story is that with "atom" -you can instrument the Perl executable to create a new executable -called "perl.third." When the instrumented executable is run, it -creates a log of dubious memory traffic in file called "perl.3log". -See man atom and man third for more information. The most extensive -Third Degree documentation is available in the Compaq "Tru64 UNIX -Programmer's Guide", chapter "Debugging Programs with Third Degree". +The short story is that with "atom" you can instrument the Perl +executable to create a new executable called "perl.third". +When the instrumented executable is run, it creates a log of dubious +memory traffic in file called "perl.3log". See man atom and man third +for more information. The most extensive Third Degree documentation +is available in the Compaq "Tru64 UNIX Programmer's Guide", chapter +"Debugging Programs with Third Degree". + +The "test.third" leaves a lot of files named perl.3log.* in the t/ +subdirectory. There is a problem with these files: Third Degree is so +effective that it finds problems also in the system libraries. +Therefore there are certain types of errors that you should ignore +in your debugging. Errors with stack traces matching + + __actual_atof|__catgets|_doprnt|__exc_|__exec|_findio|__localtime|setlocale|__sia_|__strxfrm + +(all in libc.so) are known to be non-serious. You can also +ignore the combinations + + Perl_gv_fetchfile() calling strcpy() + S_doopen_pmc() calling strcmp() + +causing "rih" (reading invalid heap) errors. + +There are also leaks that for given certain definition of a leak, +aren't. See L</PERL_DESTRUCT_LEVEL> for more information. + +=head2 PERL_DESTRUCT_LEVEL + +If you want to run any of the tests yourself manually using the +pureperl or perl.third executables, please note that by default +perl B<does not> explicitly cleanup all the memory it has allocated +(such as global memory arenas) but instead lets the exit() of +the whole program "take care" of such allocations, also known +as "global destruction of objects". + +There is a way to tell perl to do complete cleanup: set the +environment variable PERL_DESTRUCT_LEVEL to a non-zero value. +The t/TEST wrapper does set this to 2, and this is what you +need to do too, if you don't want to see the "global leaks": + + PERL_DESTRUCT_LEVEL=2 ./perl.third t/foo/bar.t =head2 CONCLUSION diff --git a/pod/perlobj.pod b/pod/perlobj.pod index 285ed9975e..53009c5eb2 100644 --- a/pod/perlobj.pod +++ b/pod/perlobj.pod @@ -548,6 +548,7 @@ destructed. Plain refs are only garbage-collected if the destruct level is greater than 0. You can test the higher levels of global destruction by setting the PERL_DESTRUCT_LEVEL environment variable, presuming C<-DDEBUGGING> was enabled during perl build time. +See L<perlhack/PERL_DESTRUCT_LEVEL> for more information. A more complete garbage collection strategy will be implemented at a future date. diff --git a/pod/perlrun.pod b/pod/perlrun.pod index 3170df4ccc..0bfcaff3b8 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -830,7 +830,7 @@ after compilation. Relevant only if your perl executable was built with B<-DDEBUGGING>, this controls the behavior of global destruction of objects and other -references. +references. See L<perlhack/PERL_DESTRUCT_LEVEL> for more information. =item PERL_ROOT (specific to the VMS port) |