This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Capitalize "SysV" correctly
[perl5.git] / pod / perlmod.pod
index fc49e34..3d5f3ad 100644 (file)
@@ -94,18 +94,9 @@ C<%main::>, or C<%::> for short.  Likewise the symbol table for the nested
 package mentioned earlier is named C<%OUTER::INNER::>.
 
 The value in each entry of the hash is what you are referring to when you
-use the C<*name> typeglob notation.  In fact, the following have the same
-effect, though the first is more efficient because it does the symbol
-table lookups at compile time:
+use the C<*name> typeglob notation.
 
     local *main::foo    = *main::bar;
-    local $main::{foo}  = $main::{bar};
-
-(Be sure to note the B<vast> difference between the second line above
-and C<local $main::foo = $main::bar>. The former is accessing the hash
-C<%main::>, which is the symbol table of package C<main>. The latter is
-simply assigning scalar C<$bar> in package C<main> to scalar C<$foo> of
-the same package.)
 
 You can use this to print out all the variables in a package, for
 instance.  The standard but antiquated F<dumpvar.pl> library and
@@ -258,12 +249,12 @@ rather than:
 This also has implications for the use of the SUPER:: qualifier
 (see L<perlobj>).
 
-=head2 BEGIN, CHECK, INIT and END
-X<BEGIN> X<CHECK> X<INIT> X<END>
+=head2 BEGIN, UNITCHECK, CHECK, INIT and END
+X<BEGIN> X<UNITCHECK> X<CHECK> X<INIT> X<END>
 
-Four specially named code blocks are executed at the beginning and at the end
-of a running Perl program.  These are the C<BEGIN>, C<CHECK>, C<INIT>, and
-C<END> blocks.
+Five specially named code blocks are executed at the beginning and at
+the end of a running Perl program.  These are the C<BEGIN>,
+C<UNITCHECK>, C<CHECK>, C<INIT>, and C<END> blocks.
 
 These code blocks can be prefixed with C<sub> to give the appearance of a
 subroutine (although this is not considered good style).  One should note
@@ -282,14 +273,15 @@ and such from other files in time to be visible to the rest of the compile
 and run time.  Once a C<BEGIN> has run, it is immediately undefined and any
 code it used is returned to Perl's memory pool.
 
-It should be noted that C<BEGIN> code blocks B<are> executed inside string
-C<eval()>'s.  The C<CHECK> and C<INIT> code blocks are B<not> executed inside
-a string eval, which e.g. can be a problem in a mod_perl environment.
+It should be noted that C<BEGIN> and C<UNITCHECK> code blocks B<are>
+executed inside string C<eval()>'s.  The C<CHECK> and C<INIT> code
+blocks are B<not> executed inside a string eval, which e.g. can be a
+problem in a mod_perl environment.
 
 An C<END> 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<exec>, or
+(But not if it's morphing 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
@@ -307,17 +299,22 @@ value of the program.  Beware of changing C<$?> by accident (e.g. by
 running something via C<system>).
 X<$?>
 
-C<CHECK> and C<INIT> code blocks are useful to catch the transition between
-the compilation phase and the execution phase of the main program.
+C<UNITCHECK>, C<CHECK> and C<INIT> code blocks are useful to catch the
+transition between the compilation phase and the execution phase of
+the main program.
+
+C<UNITCHECK> blocks are run just after the unit which defined them has
+been compiled.  The main program file and each module it loads are
+compilation units, as are string C<eval>s, code compiled using the
+C<(?{ })> construct in a regex, calls to C<do FILE>, C<require FILE>,
+and code after the C<-e> switch on the command line.
 
 C<CHECK> code blocks are run just after the B<initial> Perl compile phase ends
 and before the run time begins, in LIFO order.  C<CHECK> code blocks are used
 in the Perl compiler suite to save the compiled state of the program.
 
 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.
+"first in, first out" (FIFO) order.
 
 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.
@@ -331,26 +328,32 @@ The B<begincheck> program makes it all clear, eventually:
 
   # begincheck
 
-  print         " 8. Ordinary code runs at runtime.\n";
+  print         "10. Ordinary code runs at runtime.\n";
 
-  END { print   "14.   So this is the end of the tale.\n" }
-  INIT { print  " 5. INIT blocks run FIFO just before runtime.\n" }
-  CHECK { print " 4.   So this is the fourth line.\n" }
+  END { print   "16.   So this is the end of the tale.\n" }
+  INIT { print  " 7. INIT blocks run FIFO just before runtime.\n" }
+  UNITCHECK {
+    print       " 4.   And therefore before any CHECK blocks.\n"
+  }
+  CHECK { print " 6.   So this is the sixth line.\n" }
 
-  print         " 9.   It runs in order, of course.\n";
+  print         "11.   It runs in order, of course.\n";
 
   BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\n" }
-  END { print   "13.   Read perlmod for the rest of the story.\n" }
-  CHECK { print " 3. CHECK blocks run LIFO at compilation's end.\n" }
-  INIT { print  " 6.   Run this again, using Perl's -c switch.\n" }
+  END { print   "15.   Read perlmod for the rest of the story.\n" }
+  CHECK { print " 5. CHECK blocks run LIFO after all compilation.\n" }
+  INIT { print  " 8.   Run this again, using Perl's -c switch.\n" }
 
-  print         "10.   This is anti-obfuscated code.\n";
+  print         "12.   This is anti-obfuscated code.\n";
 
-  END { print   "12. END blocks run LIFO at quitting time.\n" }
+  END { print   "14. END blocks run LIFO at quitting time.\n" }
   BEGIN { print " 2.   So this line comes out second.\n" }
-  INIT { print  " 7.   You'll see the difference right away.\n" }
+  UNITCHECK {
+   print " 3. UNITCHECK blocks run LIFO after each file is compiled.\n"
+  }
+  INIT { print  " 9.   You'll see the difference right away.\n" }
 
-  print         "11.   It merely _looks_ like it should be confusing.\n";
+  print         "13.   It merely _looks_ like it should be confusing.\n";
 
   __END__
 
@@ -569,6 +572,9 @@ Like C<CLONE>, C<CLONE_SKIP> is called once per package; however, it is
 called just before cloning starts, and in the context of the parent
 thread. If it returns a true value, then no objects of that class will
 be cloned; or rather, they will be copied as unblessed, undef values.
+For example: if in the parent there are two references to a single blessed
+hash, then in the child there will be two references to a single undefined
+scalar value instead.
 This provides a simple mechanism for making a module threadsafe; just add
 C<sub CLONE_SKIP { 1 }> at the top of the class, and C<DESTROY()> will be
 now only be called once per object. Of course, if the child thread needs