From: Elizabeth Mattijsen Date: Sat, 29 Nov 2003 23:15:56 +0000 (+0100) Subject: Better docs for the special code blocks, based on : X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=ac90fb77766c098cd9f3441aa6691af8456d9c52;p=p5sagit%2Fp5-mst-13.2.git Better docs for the special code blocks, based on : Subject: [DOCPATCH] BEGIN, CHECK, INIT, END explained more Message-Id: p4raw-id: //depot/perl@21832 --- diff --git a/pod/perlmod.pod b/pod/perlmod.pod index c80836c..752d1f3 100644 --- a/pod/perlmod.pod +++ b/pod/perlmod.pod @@ -253,23 +253,34 @@ rather than: This also has implications for the use of the SUPER:: qualifier (see L). -=head2 Package Constructors and Destructors - -Four special subroutines act as package constructors and destructors. -These are the C, C, C, and C routines. The -C is optional for these routines. See the B program, at -the end of this section, to see them in action. - -A C subroutine is executed as soon as possible, that is, the moment -it is completely defined, even before the rest of the containing file -is parsed. You may have multiple C blocks within a file--they -will execute in order of definition. Because a C block executes -immediately, it can pull in definitions of subroutines and such from other -files in time to be visible to the rest of the file. Once a C -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. - -An C subroutine is executed as late as possible, that is, after +=head2 BEGIN, CHECK, INIT and END + +Four specially named code blocks are executed at the beginning and at the end +of a running Perl program. These are the C, C, C, and +C blocks. + +These code blocks can be prefixed with C to give the appearance of a +subroutine (although this is not considered good style). One should note +that these code blocks don't really exist as named subroutines (despite +their appearance). The thing that gives this away is the fact that you can +have B of these code blocks in a program, and they will get +B executed at the appropriate moment. So you can't execute any of +these code blocks by name. + +A C code block is executed as soon as possible, that is, the moment +it is completely defined, even before the rest of the containing file (or +string) is parsed. You may have multiple C blocks within a file (or +eval'ed string) -- they will execute in order of definition. Because a C +code block executes immediately, it can pull in definitions of subroutines +and such from other files in time to be visible to the rest of the compile +and run time. Once a C has run, it is immediately undefined and any +code it used is returned to Perl's memory pool. + +It should be noted that C code blocks B executed inside string +C's. The C and C code blocks are B executed inside +a string eval, which e.g. can be a problem in a mod_perl environment. + +An C code block 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, or @@ -279,17 +290,22 @@ will execute in reverse order of definition; that is: last in, first out (LIFO). C blocks are not executed when you run perl with the C<-c> switch, or if compilation fails. -Inside an C subroutine, C<$?> contains the value that the program is +Note that C code blocks are B executed at the end of a string +C: if any C code blocks are created in a string C, +they will be executed just as any other C code block of that package +in LIFO order just before the interpreter is being exited. + +Inside an C code block, C<$?> contains the value that the program is going to pass to C. 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). -C and C blocks are useful to catch the transition between +C and C code blocks are useful to catch the transition between the compilation phase and the execution phase of the main program. -C blocks are run just after the Perl compile phase ends and before -the run time begins, in LIFO order. C blocks are used in -the Perl compiler suite to save the compiled state of the program. +C code blocks are run just after the B Perl compile phase ends +and before the run time begins, in LIFO order. C code blocks are used +in the Perl compiler suite to save the compiled state of the program. C blocks are run just before the Perl runtime begins execution, in "first in, first out" (FIFO) order. For example, the code generators diff --git a/pod/perlsub.pod b/pod/perlsub.pod index 376ba12..969d0ba 100644 --- a/pod/perlsub.pod +++ b/pod/perlsub.pod @@ -202,13 +202,17 @@ disables any prototype checking on arguments you do provide. This is partly for historical reasons, and partly for having a convenient way to cheat if you know what you're doing. See L below. -Functions whose names are in all upper case are reserved to the Perl -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, C, C, C, C, -C and C--plus all functions mentioned in L. +Subroutines whose names are in all upper case are reserved to the Perl +core, as are modules whose names are in all lower case. A subroutine 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. +Subroutines that do special, pre-defined things include C, C, +C plus all functions mentioned in L and L. + +The C, C, C and C subroutines are not so much +subroutines as named special code blocks, of which you can have more +than one in a package, and which you can B call explicitely. See +L =head2 Private Variables via my() @@ -440,18 +444,18 @@ via C or C, then this is probably just fine. If it's all in the main program, you'll need to arrange for the C to be executed early, either by putting the whole block above your main program, or more likely, placing merely a C -sub around it to make sure it gets executed before your program +code block around it to make sure it gets executed before your program starts to run: - sub BEGIN { + BEGIN { my $secret_val = 0; sub gimme_another { return ++$secret_val; } } -See L about the -special triggered functions, C, C, C and C. +See L about the +special triggered code blocks, C, C, C and C. If declared at the outermost scope (the file scope), then lexicals work somewhat like C's file statics. They are available to all