=head1 DESCRIPTION
=head2 Packages
+X<package> X<namespace> X<variable, global> X<global variable> X<global>
Perl provides a mechanism for alternative namespaces to protect
packages from stomping on each other's variables. In fact, there's
C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is,
the $s variable in package C<owner>, which is probably not what you meant.
Use braces to disambiguate, as in C<"This is ${owner}'s house">.
+X<::> X<'>
Packages may themselves contain package separators, as in
C<$OUTER::INNER::var>. This implies nothing about the order of
have a package called C<m>, C<s>, or C<y>, then you can't use the
qualified form of an identifier because it would be instead interpreted
as a pattern match, a substitution, or a transliteration.
+X<variable, punctuation>
Variables beginning with underscore used to be forced into package
main, but we decided it was more useful for package writers to be able
and L<perlref> regarding closures.
=head2 Symbol Tables
+X<symbol table> X<stash> X<%::> X<%main::> X<typeglob> X<glob> X<alias>
The symbol table for a package happens to be stored in the hash of that
name with two colons appended. The main symbol table's name is thus
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
explicitly.
Another use of symbol tables is for making "constant" scalars.
+X<constant> X<scalar, constant>
*PI = \3.14159265358979;
This also has implications for the use of the SUPER:: qualifier
(see L<perlobj>).
-=head2 Package Constructors and Destructors
-
-Four special subroutines act as package constructors and destructors.
-These are the C<BEGIN>, C<CHECK>, 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
-is parsed. You may have multiple C<BEGIN> blocks within a file--they
-will execute in order of definition. Because a C<BEGIN> 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<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>.
-
-An C<END> subroutine is executed as late as possible, that is, after
+=head2 BEGIN, UNITCHECK, CHECK, INIT and END
+X<BEGIN> X<UNITCHECK> X<CHECK> X<INIT> X<END>
+
+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
+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<more than one> of these code blocks in a program, and they will get
+B<all> executed at the appropriate moment. So you can't execute any of
+these code blocks by name.
+
+A C<BEGIN> 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<BEGIN> blocks within a file (or
+eval'ed string) -- they will execute in order of definition. Because a C<BEGIN>
+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<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> 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
out (LIFO). C<END> blocks are not executed when you run perl with the
C<-c> switch, or if compilation fails.
-Inside an C<END> subroutine, C<$?> contains the value that the program is
+Note that C<END> code blocks are B<not> executed at the end of a string
+C<eval()>: if any C<END> code blocks are created in a string C<eval()>,
+they will be executed just as any other C<END> code block of that package
+in LIFO order just before the interpreter is being exited.
+
+Inside an C<END> code block, 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>).
+X<$?>
-C<CHECK> and C<INIT> 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<CHECK> blocks are run just after the Perl compile phase ends and before
-the run time begins, in LIFO order. C<CHECK> blocks are used in
-the Perl compiler suite to save the compiled state of the 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.
switch for a compile-only syntax check, although your main code
is not.
+The B<begincheck> program makes it all clear, eventually:
+
+ #!/usr/bin/perl
+
+ # begincheck
+
+ print "10. Ordinary code runs at runtime.\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 "11. It runs in order, of course.\n";
+
+ BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\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 "12. This is anti-obfuscated code.\n";
+
+ END { print "14. END blocks run LIFO at quitting time.\n" }
+ BEGIN { print " 2. So this line comes out second.\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 "13. It merely _looks_ like it should be confusing.\n";
+
+ __END__
+
=head2 Perl Classes
+X<class> X<@ISA>
There is no special class syntax in Perl, but a package may act
as a class if it provides subroutines to act as methods. Such a
For more on this, see L<perltoot> and L<perlobj>.
=head2 Perl Modules
+X<module>
A module is just a set of related functions in a library file, i.e.,
a Perl package with the same name as the file. It is specifically
autoloading, the user can say just C<use POSIX> to get it all.
=head2 Making your module threadsafe
+X<threadsafe> X<thread safe>
+X<module, threadsafe> X<module, thread safe>
+X<CLONE> X<CLONE_SKIP> X<thread> X<threads> X<ithread>
Since 5.6.0, Perl has had support for a new type of threads called
interpreter threads (ithreads). These threads can be used explicitly
module or by doing fork() on win32 (fake fork() support). When a
thread is cloned all Perl data is cloned, however non-Perl data cannot
be cloned automatically. Perl after 5.7.2 has support for the C<CLONE>
-special subroutine . In C<CLONE> you can do whatever you need to do,
+special subroutine. In C<CLONE> you can do whatever
+you need to do,
like for example handle the cloning of non-Perl data, if necessary.
-C<CLONE> will be executed once for every package that has it defined
-(or inherits it). It will be called in the context of the new thread,
-so all modifications are made in the new area.
+C<CLONE> will be called once as a class method for every package that has it
+defined (or inherits it). It will be called in the context of the new thread,
+so all modifications are made in the new area. Currently CLONE is called with
+no parameters other than the invocant package name, but code should not assume
+that this will remain unchanged, as it is likely that in future extra parameters
+will be passed in to give more information about the state of cloning.
If you want to CLONE all objects you will need to keep track of them per
package. This is simply done using a hash and Scalar::Util::weaken().
+Perl after 5.8.7 has support for the C<CLONE_SKIP> special subroutine.
+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
+to make use of the objects, then a more sophisticated approach is
+needed.
+
+Like C<CLONE>, C<CLONE_SKIP> is currently called with no parameters other
+than the invocant package name, although that may change. Similarly, to
+allow for future expansion, the return value should be a single C<0> or
+C<1> value.
+
=head1 SEE ALSO
See L<perlmodlib> for general style issues related to building Perl
https://perl5.git.perl.org / perl5.git / blobdiff