Integrate with Sarathy.

p4raw-id: //depot/cfgperl@4520

7 files changed, 51 insertions, 29 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index da1425e6c1..e46df77f83 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -24,6 +24,12 @@ responsibility to ensure that warnings are enabled judiciously.
 
 =over 4
 
+=item STOP is a new keyword
+
+In addition to C<BEGIN>, C<INIT> and C<END>, subroutines named
+C<STOP> are now special.  They are queued up for execution at the
+end of compilation, and cannot be called directly.
+
 =item Treatment of list slices of undef has changed
 
 When taking a slice of a literal list (as opposed to a slice of
@@ -603,6 +609,13 @@ BEGIN blocks are executed under such conditions, this variable
 enables perl code to determine whether actions that make sense
 only during normal running are warranted.  See L<perlvar>.
 
+=head2 STOP blocks
+
+Arbitrary code can be queued for execution when Perl has finished
+parsing the program (i.e. when the compile phase ends) using STOP
+blocks.  These behave similar to END blocks, except for being
+called at the end of compilation rather than at the end of execution.
+
 =head2 Optional Y2K warnings
 
 If Perl is built with the cpp macro C<PERL_Y2KWARN> defined,
@@ -789,9 +802,7 @@ run in compile-only mode.  Since this is typically not the expected
 behavior, END blocks are not executed anymore when the C<-c> switch
 is used.
 
-Note that something resembling the previous behavior can still be
-obtained by putting C<BEGIN { $^C = 0; exit; }> at the very end of
-the top level source file.
+See L<STOP blocks> for how to run things when the compile phase ends.
 
 =head2 Potential to leak DATA filehandles
 
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 0b1f68e848..277e6342bc 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -1316,10 +1316,11 @@ ugly.  Your code will be interpreted as an attempt to call a method
 named "elseif" for the class returned by the following block.  This is
 unlikely to be what you want.
 
-=item END failed--cleanup aborted
+=item %s failed--call queue aborted
 
-(F) An untrapped exception was raised while executing an END subroutine.
-The interpreter is immediately exited.
+(F) An untrapped exception was raised while executing a STOP, INIT, or
+END subroutine.  Processing of the remainder of the queue of such
+routines has been prematurely ended.
 
 =item entering effective %s failed
 
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 033d4caf24..088f1dd509 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3767,7 +3767,9 @@ array by 1 and moving everything down.  If there are no elements in the
 array, returns the undefined value.  If ARRAY is omitted, shifts the
 C<@_> array within the lexical scope of subroutines and formats, and the
 C<@ARGV> array at file scopes or within the lexical scopes established by
-the C<eval ''>, C<BEGIN {}>, C<END {}>, and C<INIT {}> constructs.
+the C<eval ''>, C<BEGIN {}>, C<INIT {}>, C<STOP {}>, and C<END {}>
+constructs.
+
 See also C<unshift>, C<push>, and C<pop>.  C<Shift()> and C<unshift> do the
 same thing to the left end of an array that C<pop> and C<push> do to the
 right end.
diff --git a/pod/perlmod.pod b/pod/perlmod.pod
index fc81fdfaae..45a82ad7a2 100644
--- a/pod/perlmod.pod
+++ b/pod/perlmod.pod
@@ -213,8 +213,8 @@ This also has implications for the use of the SUPER:: qualifier
 =head2 Package Constructors and Destructors
 
 Three special subroutines act as package
-constructors and destructors.  These are the C<BEGIN>, C<INIT>, and
-C<END> routines.  The C<sub> is optional for these routines.
+constructors and destructors.  These are the C<BEGIN>, C<STOP>, C<INIT>,
+and C<END> routines.  The C<sub> is optional for these routines.
 
 A C<BEGIN> subroutine is executed as soon as possible, that is, the moment
 it is completely defined, even before the rest of the containing file
@@ -225,24 +225,31 @@ files in time to be visible to the rest of the file.  Once a C<BEGIN>
 has run, it is immediately undefined and any code it used is returned to
 Perl's memory pool.  This means you can't ever explicitly call a C<BEGIN>.
 
-Similar to C<BEGIN> blocks, C<INIT> blocks are run just before the
-Perl runtime begins execution.  For example, the code generators
-documented in L<perlcc> make use of C<INIT> blocks to initialize
-and resolve pointers to XSUBs.
-
-An C<END> subroutine is executed as late as possible, that is, when
-the interpreter is being exited, even if it is exiting as a result of
-a die() function.  (But not if it's polymorphing into another program
-via C<exec>, or being blown out of the water by a signal--you have to
-trap that yourself (if you can).)  You may have multiple C<END> blocks
-within a file--they will execute in reverse order of definition; that is:
-last in, first out (LIFO).
+An C<END> subroutine is executed as late as possible, that is, after
+perl has finished running the program and just before the interpreter
+is being exited, even if it is exiting as a result of a die() function.
+(But not if it's polymorphing into another program via C<exec>, or
+being blown out of the water by a signal--you have to trap that yourself
+(if you can).)  You may have multiple C<END> blocks within a file--they
+will execute in reverse order of definition; that is: last in, first
+out (LIFO).  C<END> blocks are not executed when you run perl with the
+C<-c> switch.
 
 Inside an C<END> subroutine, C<$?> contains the value that the program is
 going to pass to C<exit()>.  You can modify C<$?> to change the exit
 value of the program.  Beware of changing C<$?> by accident (e.g. by
 running something via C<system>).
 
+Similar to C<BEGIN> blocks, C<INIT> blocks are run just before the
+Perl runtime begins execution, in "first in, first out" (FIFO) order.
+For example, the code generators documented in L<perlcc> make use of
+C<INIT> blocks to initialize and resolve pointers to XSUBs.
+
+Similar to C<END> blocks, C<STOP> blocks are run just after the
+Perl compile phase ends and before the run time begins, in
+LIFO order.  C<STOP> blocks are again useful in the Perl compiler
+suite to save the compiled state of the program.
+
 When you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and
 C<END> work just as they do in B<awk>, as a degenerate case.  As currently
 implemented (and subject to change, since its inconvenient at best),
diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 0c3fcad921..8fec7c397a 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -268,9 +268,10 @@ An alternate delimiter may be specified using B<-F>.
 =item B<-c>
 
 causes Perl to check the syntax of the program and then exit without
-executing it.  Actually, it I<will> execute C<BEGIN>, C<END>, and C<use> blocks,
-because these are considered as occurring outside the execution of
-your program.  C<INIT> blocks, however, will be skipped.
+executing it.  Actually, it I<will> execute C<BEGIN>, C<STOP>, and
+C<use> blocks, because these are considered as occurring outside the
+execution of your program.  C<INIT> and C<END> blocks, however, will
+be skipped.
 
 =item B<-d>
 
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 4abdc39529..416763f6d8 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -207,9 +207,8 @@ core, as are modules whose names are in all lower case.  A
 function in all capitals is a loosely-held convention meaning it
 will be called indirectly by the run-time system itself, usually
 due to a triggered event.  Functions that do special, pre-defined
-things include C<BEGIN>, C<END>, C<AUTOLOAD>, and C<DESTROY>--plus
-all functions mentioned in L<perltie>.  The 5.005 release adds
-C<INIT> to this list.
+things include C<BEGIN>, C<STOP>, C<INIT>, C<END>, C<AUTOLOAD>, and
+C<DESTROY>--plus all functions mentioned in L<perltie>.
 
 =head2 Private Variables via my()
 
@@ -455,7 +454,7 @@ starts to run:
     }
 
 See L<perlmod/"Package Constructors and Destructors"> about the
-special triggered functions, C<BEGIN> and C<INIT>.
+special triggered functions, C<BEGIN>, C<STOP>, C<INIT> and C<END>.
 
 If declared at the outermost scope (the file scope), then lexicals
 work somewhat like C's file statics.  They are available to all
diff --git a/pod/perltodo.pod b/pod/perltodo.pod
index 4b2ed48a09..7836acf677 100644
--- a/pod/perltodo.pod
+++ b/pod/perltodo.pod
@@ -824,7 +824,8 @@ Workarounds to help Win32 dynamic loading.
 
 =head2 END blocks
 
-END blocks need saving in compiled output.
+END blocks need saving in compiled output, now that STOP blocks
+are available.
 
 =head2 _AUTOLOAD