This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Accidental interpolation of $@ in Pod::Html [PATCH]
[perl5.git] / pod / perlmod.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
f102b883 3perlmod - Perl modules (packages and symbol tables)
a0d0e21e
LW
4
5=head1 DESCRIPTION
6
7=head2 Packages
8
19799a22
GS
9Perl provides a mechanism for alternative namespaces to protect
10packages from stomping on each other's variables. In fact, there's
bc8df162 11really no such thing as a global variable in Perl. The package
19799a22
GS
12statement declares the compilation unit as being in the given
13namespace. The scope of the package declaration is from the
14declaration itself through the end of the enclosing block, C<eval>,
15or file, whichever comes first (the same scope as the my() and
16local() operators). Unqualified dynamic identifiers will be in
17this namespace, except for those few identifiers that if unqualified,
18default to the main package instead of the current one as described
19below. A package statement affects only dynamic variables--including
20those you've used local() on--but I<not> lexical variables created
21with my(). Typically it would be the first declaration in a file
22included by the C<do>, C<require>, or C<use> operators. You can
23switch into a package in more than one place; it merely influences
24which symbol table is used by the compiler for the rest of that
25block. You can refer to variables and filehandles in other packages
26by prefixing the identifier with the package name and a double
27colon: C<$Package::Variable>. If the package name is null, the
28C<main> package is assumed. That is, C<$::sail> is equivalent to
29C<$main::sail>.
a0d0e21e 30
d3ebb66b
GS
31The old package delimiter was a single quote, but double colon is now the
32preferred delimiter, in part because it's more readable to humans, and
33in part because it's more readable to B<emacs> macros. It also makes C++
34programmers feel like they know what's going on--as opposed to using the
35single quote as separator, which was there to make Ada programmers feel
14c715f4 36like they knew what was going on. Because the old-fashioned syntax is still
d3ebb66b
GS
37supported for backwards compatibility, if you try to use a string like
38C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is,
39the $s variable in package C<owner>, which is probably not what you meant.
40Use braces to disambiguate, as in C<"This is ${owner}'s house">.
a0d0e21e 41
19799a22
GS
42Packages may themselves contain package separators, as in
43C<$OUTER::INNER::var>. This implies nothing about the order of
44name lookups, however. There are no relative packages: all symbols
a0d0e21e
LW
45are either local to the current package, or must be fully qualified
46from the outer package name down. For instance, there is nowhere
19799a22 47within package C<OUTER> that C<$INNER::var> refers to
14c715f4 48C<$OUTER::INNER::var>. C<INNER> refers to a totally
19799a22
GS
49separate global package.
50
51Only identifiers starting with letters (or underscore) are stored
52in a package's symbol table. All other symbols are kept in package
53C<main>, including all punctuation variables, like $_. In addition,
54when unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV,
55ARGVOUT, ENV, INC, and SIG are forced to be in package C<main>,
14c715f4 56even when used for other purposes than their built-in ones. If you
19799a22
GS
57have a package called C<m>, C<s>, or C<y>, then you can't use the
58qualified form of an identifier because it would be instead interpreted
59as a pattern match, a substitution, or a transliteration.
60
61Variables beginning with underscore used to be forced into package
a0d0e21e 62main, but we decided it was more useful for package writers to be able
cb1a09d0 63to use leading underscore to indicate private variables and method names.
b58b0d99
AT
64However, variables and functions named with a single C<_>, such as
65$_ and C<sub _>, are still forced into the package C<main>. See also
cea6626f 66L<perlvar/"Technical Note on the Syntax of Variable Names">.
a0d0e21e 67
19799a22 68C<eval>ed strings are compiled in the package in which the eval() was
a0d0e21e 69compiled. (Assignments to C<$SIG{}>, however, assume the signal
748a9306 70handler specified is in the C<main> package. Qualify the signal handler
a0d0e21e
LW
71name if you wish to have a signal handler in a package.) For an
72example, examine F<perldb.pl> in the Perl library. It initially switches
73to the C<DB> package so that the debugger doesn't interfere with variables
19799a22 74in the program you are trying to debug. At various points, however, it
a0d0e21e
LW
75temporarily switches back to the C<main> package to evaluate various
76expressions in the context of the C<main> package (or wherever you came
77from). See L<perldebug>.
78
f102b883 79The special symbol C<__PACKAGE__> contains the current package, but cannot
14c715f4 80(easily) be used to construct variable names.
f102b883 81
5f05dabc 82See L<perlsub> for other scoping issues related to my() and local(),
f102b883 83and L<perlref> regarding closures.
cb1a09d0 84
a0d0e21e
LW
85=head2 Symbol Tables
86
aa689395
PP
87The symbol table for a package happens to be stored in the hash of that
88name with two colons appended. The main symbol table's name is thus
5803be0d 89C<%main::>, or C<%::> for short. Likewise the symbol table for the nested
aa689395
PP
90package mentioned earlier is named C<%OUTER::INNER::>.
91
92The value in each entry of the hash is what you are referring to when you
93use the C<*name> typeglob notation. In fact, the following have the same
94effect, though the first is more efficient because it does the symbol
95table lookups at compile time:
a0d0e21e 96
f102b883
TC
97 local *main::foo = *main::bar;
98 local $main::{foo} = $main::{bar};
a0d0e21e 99
bc8df162
DC
100(Be sure to note the B<vast> difference between the second line above
101and C<local $main::foo = $main::bar>. The former is accessing the hash
102C<%main::>, which is the symbol table of package C<main>. The latter is
103simply assigning scalar C<$bar> in package C<main> to scalar C<$foo> of
104the same package.)
105
a0d0e21e 106You can use this to print out all the variables in a package, for
4375e838 107instance. The standard but antiquated F<dumpvar.pl> library and
19799a22 108the CPAN module Devel::Symdump make use of this.
a0d0e21e 109
cb1a09d0 110Assignment to a typeglob performs an aliasing operation, i.e.,
a0d0e21e
LW
111
112 *dick = *richard;
113
5a964f20
TC
114causes variables, subroutines, formats, and file and directory handles
115accessible via the identifier C<richard> also to be accessible via the
116identifier C<dick>. If you want to alias only a particular variable or
19799a22 117subroutine, assign a reference instead:
a0d0e21e
LW
118
119 *dick = \$richard;
120
5a964f20 121Which makes $richard and $dick the same variable, but leaves
a0d0e21e
LW
122@richard and @dick as separate arrays. Tricky, eh?
123
5e76a0e2
MC
124There is one subtle difference between the following statements:
125
126 *foo = *bar;
127 *foo = \$bar;
128
129C<*foo = *bar> makes the typeglobs themselves synonymous while
130C<*foo = \$bar> makes the SCALAR portions of two distinct typeglobs
131refer to the same scalar value. This means that the following code:
132
133 $bar = 1;
134 *foo = \$bar; # Make $foo an alias for $bar
135
136 {
137 local $bar = 2; # Restrict changes to block
138 print $foo; # Prints '1'!
139 }
140
141Would print '1', because C<$foo> holds a reference to the I<original>
142C<$bar> -- the one that was stuffed away by C<local()> and which will be
143restored when the block ends. Because variables are accessed through the
144typeglob, you can use C<*foo = *bar> to create an alias which can be
145localized. (But be aware that this means you can't have a separate
146C<@foo> and C<@bar>, etc.)
147
148What makes all of this important is that the Exporter module uses glob
149aliasing as the import/export mechanism. Whether or not you can properly
150localize a variable that has been exported from a module depends on how
151it was exported:
152
153 @EXPORT = qw($FOO); # Usual form, can't be localized
154 @EXPORT = qw(*FOO); # Can be localized
155
14c715f4 156You can work around the first case by using the fully qualified name
5e76a0e2
MC
157(C<$Package::FOO>) where you need a local value, or by overriding it
158by saying C<*FOO = *Package::FOO> in your script.
159
160The C<*x = \$y> mechanism may be used to pass and return cheap references
5803be0d 161into or from subroutines if you don't want to copy the whole
5a964f20
TC
162thing. It only works when assigning to dynamic variables, not
163lexicals.
cb1a09d0 164
5a964f20 165 %some_hash = (); # can't be my()
cb1a09d0
AD
166 *some_hash = fn( \%another_hash );
167 sub fn {
168 local *hashsym = shift;
169 # now use %hashsym normally, and you
170 # will affect the caller's %another_hash
171 my %nhash = (); # do what you want
5f05dabc 172 return \%nhash;
cb1a09d0
AD
173 }
174
5f05dabc 175On return, the reference will overwrite the hash slot in the
cb1a09d0 176symbol table specified by the *some_hash typeglob. This
c36e9b62 177is a somewhat tricky way of passing around references cheaply
5803be0d 178when you don't want to have to remember to dereference variables
cb1a09d0
AD
179explicitly.
180
19799a22 181Another use of symbol tables is for making "constant" scalars.
cb1a09d0
AD
182
183 *PI = \3.14159265358979;
184
bc8df162 185Now you cannot alter C<$PI>, which is probably a good thing all in all.
5a964f20 186This isn't the same as a constant subroutine, which is subject to
5803be0d 187optimization at compile-time. A constant subroutine is one prototyped
14c715f4 188to take no arguments and to return a constant expression. See
5803be0d 189L<perlsub> for details on these. The C<use constant> pragma is a
5a964f20 190convenient shorthand for these.
cb1a09d0 191
55497cff
PP
192You can say C<*foo{PACKAGE}> and C<*foo{NAME}> to find out what name and
193package the *foo symbol table entry comes from. This may be useful
5a964f20 194in a subroutine that gets passed typeglobs as arguments:
55497cff
PP
195
196 sub identify_typeglob {
197 my $glob = shift;
198 print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\n";
199 }
200 identify_typeglob *foo;
201 identify_typeglob *bar::baz;
202
203This prints
204
205 You gave me main::foo
206 You gave me bar::baz
207
19799a22 208The C<*foo{THING}> notation can also be used to obtain references to the
5803be0d 209individual elements of *foo. See L<perlref>.
55497cff 210
9263d47b
GS
211Subroutine definitions (and declarations, for that matter) need
212not necessarily be situated in the package whose symbol table they
213occupy. You can define a subroutine outside its package by
214explicitly qualifying the name of the subroutine:
215
216 package main;
217 sub Some_package::foo { ... } # &foo defined in Some_package
218
219This is just a shorthand for a typeglob assignment at compile time:
220
221 BEGIN { *Some_package::foo = sub { ... } }
222
223and is I<not> the same as writing:
224
225 {
226 package Some_package;
227 sub foo { ... }
228 }
229
230In the first two versions, the body of the subroutine is
231lexically in the main package, I<not> in Some_package. So
232something like this:
233
234 package main;
235
236 $Some_package::name = "fred";
237 $main::name = "barney";
238
239 sub Some_package::foo {
240 print "in ", __PACKAGE__, ": \$name is '$name'\n";
241 }
242
243 Some_package::foo();
244
245prints:
246
247 in main: $name is 'barney'
248
249rather than:
250
251 in Some_package: $name is 'fred'
252
253This also has implications for the use of the SUPER:: qualifier
254(see L<perlobj>).
255
ac90fb77
EM
256=head2 BEGIN, CHECK, INIT and END
257
258Four specially named code blocks are executed at the beginning and at the end
259of a running Perl program. These are the C<BEGIN>, C<CHECK>, C<INIT>, and
260C<END> blocks.
261
262These code blocks can be prefixed with C<sub> to give the appearance of a
263subroutine (although this is not considered good style). One should note
264that these code blocks don't really exist as named subroutines (despite
265their appearance). The thing that gives this away is the fact that you can
266have B<more than one> of these code blocks in a program, and they will get
267B<all> executed at the appropriate moment. So you can't execute any of
268these code blocks by name.
269
270A C<BEGIN> code block is executed as soon as possible, that is, the moment
271it is completely defined, even before the rest of the containing file (or
272string) is parsed. You may have multiple C<BEGIN> blocks within a file (or
273eval'ed string) -- they will execute in order of definition. Because a C<BEGIN>
274code block executes immediately, it can pull in definitions of subroutines
275and such from other files in time to be visible to the rest of the compile
276and run time. Once a C<BEGIN> has run, it is immediately undefined and any
277code it used is returned to Perl's memory pool.
278
279It should be noted that C<BEGIN> code blocks B<are> executed inside string
280C<eval()>'s. The C<CHECK> and C<INIT> code blocks are B<not> executed inside
281a string eval, which e.g. can be a problem in a mod_perl environment.
282
283An C<END> code block is executed as late as possible, that is, after
4f25aa18
GS
284perl has finished running the program and just before the interpreter
285is being exited, even if it is exiting as a result of a die() function.
286(But not if it's polymorphing into another program via C<exec>, or
287being blown out of the water by a signal--you have to trap that yourself
288(if you can).) You may have multiple C<END> blocks within a file--they
289will execute in reverse order of definition; that is: last in, first
290out (LIFO). C<END> blocks are not executed when you run perl with the
db517d64 291C<-c> switch, or if compilation fails.
a0d0e21e 292
ac90fb77
EM
293Note that C<END> code blocks are B<not> executed at the end of a string
294C<eval()>: if any C<END> code blocks are created in a string C<eval()>,
295they will be executed just as any other C<END> code block of that package
296in LIFO order just before the interpreter is being exited.
297
298Inside an C<END> code block, C<$?> contains the value that the program is
c36e9b62 299going to pass to C<exit()>. You can modify C<$?> to change the exit
19799a22 300value of the program. Beware of changing C<$?> by accident (e.g. by
c36e9b62
PP
301running something via C<system>).
302
ac90fb77 303C<CHECK> and C<INIT> code blocks are useful to catch the transition between
ca62f0fc
RGS
304the compilation phase and the execution phase of the main program.
305
ac90fb77
EM
306C<CHECK> code blocks are run just after the B<initial> Perl compile phase ends
307and before the run time begins, in LIFO order. C<CHECK> code blocks are used
308in the Perl compiler suite to save the compiled state of the program.
ca62f0fc
RGS
309
310C<INIT> blocks are run just before the Perl runtime begins execution, in
311"first in, first out" (FIFO) order. For example, the code generators
312documented in L<perlcc> make use of C<INIT> blocks to initialize and
313resolve pointers to XSUBs.
4f25aa18 314
19799a22 315When you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and
4375e838
GS
316C<END> work just as they do in B<awk>, as a degenerate case.
317Both C<BEGIN> and C<CHECK> blocks are run when you use the B<-c>
318switch for a compile-only syntax check, although your main code
319is not.
a0d0e21e 320
055634da
TP
321The B<begincheck> program makes it all clear, eventually:
322
323 #!/usr/bin/perl
324
325 # begincheck
326
327 print " 8. Ordinary code runs at runtime.\n";
328
329 END { print "14. So this is the end of the tale.\n" }
330 INIT { print " 5. INIT blocks run FIFO just before runtime.\n" }
331 CHECK { print " 4. So this is the fourth line.\n" }
332
333 print " 9. It runs in order, of course.\n";
334
335 BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\n" }
336 END { print "13. Read perlmod for the rest of the story.\n" }
337 CHECK { print " 3. CHECK blocks run LIFO at compilation's end.\n" }
338 INIT { print " 6. Run this again, using Perl's -c switch.\n" }
339
340 print "10. This is anti-obfuscated code.\n";
341
342 END { print "12. END blocks run LIFO at quitting time.\n" }
343 BEGIN { print " 2. So this line comes out second.\n" }
344 INIT { print " 7. You'll see the difference right away.\n" }
345
346 print "11. It merely _looks_ like it should be confusing.\n";
347
348 __END__
349
a0d0e21e
LW
350=head2 Perl Classes
351
19799a22 352There is no special class syntax in Perl, but a package may act
5a964f20
TC
353as a class if it provides subroutines to act as methods. Such a
354package may also derive some of its methods from another class (package)
14c715f4 355by listing the other package name(s) in its global @ISA array (which
5a964f20 356must be a package global, not a lexical).
4633a7c4 357
f102b883 358For more on this, see L<perltoot> and L<perlobj>.
a0d0e21e
LW
359
360=head2 Perl Modules
361
5803be0d 362A module is just a set of related functions in a library file, i.e.,
14c715f4 363a Perl package with the same name as the file. It is specifically
5803be0d
GS
364designed to be reusable by other modules or programs. It may do this
365by providing a mechanism for exporting some of its symbols into the
14c715f4 366symbol table of any package using it, or it may function as a class
19799a22
GS
367definition and make its semantics available implicitly through
368method calls on the class and its objects, without explicitly
4375e838 369exporting anything. Or it can do a little of both.
a0d0e21e 370
19799a22
GS
371For example, to start a traditional, non-OO module called Some::Module,
372create a file called F<Some/Module.pm> and start with this template:
9607fc9c
PP
373
374 package Some::Module; # assumes Some/Module.pm
375
376 use strict;
9f1b1f2d 377 use warnings;
9607fc9c
PP
378
379 BEGIN {
380 use Exporter ();
77ca0c92 381 our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
9607fc9c
PP
382
383 # set the version for version checking
384 $VERSION = 1.00;
385 # if using RCS/CVS, this may be preferred
328fc025 386 $VERSION = sprintf "%d.%03d", q$Revision: 1.1 $ =~ /(\d+)/g;
9607fc9c
PP
387
388 @ISA = qw(Exporter);
389 @EXPORT = qw(&func1 &func2 &func4);
390 %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ],
391
392 # your exported package globals go here,
393 # as well as any optionally exported functions
394 @EXPORT_OK = qw($Var1 %Hashit &func3);
395 }
77ca0c92 396 our @EXPORT_OK;
9607fc9c 397
3da4c8f2
DB
398 # exported package globals go here
399 our $Var1;
400 our %Hashit;
401
9607fc9c 402 # non-exported package globals go here
77ca0c92
LW
403 our @more;
404 our $stuff;
9607fc9c 405
c2611fb3 406 # initialize package globals, first exported ones
9607fc9c
PP
407 $Var1 = '';
408 %Hashit = ();
409
410 # then the others (which are still accessible as $Some::Module::stuff)
411 $stuff = '';
412 @more = ();
413
414 # all file-scoped lexicals must be created before
415 # the functions below that use them.
416
417 # file-private lexicals go here
418 my $priv_var = '';
419 my %secret_hash = ();
420
421 # here's a file-private function as a closure,
422 # callable as &$priv_func; it cannot be prototyped.
423 my $priv_func = sub {
424 # stuff goes here.
425 };
426
427 # make all your functions, whether exported or not;
428 # remember to put something interesting in the {} stubs
429 sub func1 {} # no prototype
430 sub func2() {} # proto'd void
431 sub func3($$) {} # proto'd to 2 scalars
432
433 # this one isn't exported, but could be called!
434 sub func4(\%) {} # proto'd to 1 hash ref
435
436 END { } # module clean-up code here (global destructor)
4633a7c4 437
19799a22
GS
438 ## YOUR CODE GOES HERE
439
440 1; # don't forget to return a true value from the file
441
442Then go on to declare and use your variables in functions without
443any qualifications. See L<Exporter> and the L<perlmodlib> for
444details on mechanics and style issues in module creation.
4633a7c4
LW
445
446Perl modules are included into your program by saying
a0d0e21e
LW
447
448 use Module;
449
450or
451
452 use Module LIST;
453
454This is exactly equivalent to
455
5a964f20 456 BEGIN { require Module; import Module; }
a0d0e21e
LW
457
458or
459
5a964f20 460 BEGIN { require Module; import Module LIST; }
a0d0e21e 461
cb1a09d0
AD
462As a special case
463
464 use Module ();
465
466is exactly equivalent to
467
5a964f20 468 BEGIN { require Module; }
cb1a09d0 469
19799a22
GS
470All Perl module files have the extension F<.pm>. The C<use> operator
471assumes this so you don't have to spell out "F<Module.pm>" in quotes.
472This also helps to differentiate new modules from old F<.pl> and
473F<.ph> files. Module names are also capitalized unless they're
474functioning as pragmas; pragmas are in effect compiler directives,
475and are sometimes called "pragmatic modules" (or even "pragmata"
476if you're a classicist).
a0d0e21e 477
5a964f20
TC
478The two statements:
479
480 require SomeModule;
14c715f4 481 require "SomeModule.pm";
5a964f20
TC
482
483differ from each other in two ways. In the first case, any double
484colons in the module name, such as C<Some::Module>, are translated
485into your system's directory separator, usually "/". The second
19799a22
GS
486case does not, and would have to be specified literally. The other
487difference is that seeing the first C<require> clues in the compiler
488that uses of indirect object notation involving "SomeModule", as
489in C<$ob = purge SomeModule>, are method calls, not function calls.
490(Yes, this really can make a difference.)
491
492Because the C<use> statement implies a C<BEGIN> block, the importing
493of semantics happens as soon as the C<use> statement is compiled,
a0d0e21e
LW
494before the rest of the file is compiled. This is how it is able
495to function as a pragma mechanism, and also how modules are able to
19799a22 496declare subroutines that are then visible as list or unary operators for
a0d0e21e 497the rest of the current file. This will not work if you use C<require>
19799a22 498instead of C<use>. With C<require> you can get into this problem:
a0d0e21e
LW
499
500 require Cwd; # make Cwd:: accessible
54310121 501 $here = Cwd::getcwd();
a0d0e21e 502
5f05dabc 503 use Cwd; # import names from Cwd::
a0d0e21e
LW
504 $here = getcwd();
505
506 require Cwd; # make Cwd:: accessible
507 $here = getcwd(); # oops! no main::getcwd()
508
5a964f20
TC
509In general, C<use Module ()> is recommended over C<require Module>,
510because it determines module availability at compile time, not in the
511middle of your program's execution. An exception would be if two modules
512each tried to C<use> each other, and each also called a function from
14c715f4 513that other module. In that case, it's easy to use C<require> instead.
cb1a09d0 514
a0d0e21e
LW
515Perl packages may be nested inside other package names, so we can have
516package names containing C<::>. But if we used that package name
5803be0d 517directly as a filename it would make for unwieldy or impossible
a0d0e21e
LW
518filenames on some systems. Therefore, if a module's name is, say,
519C<Text::Soundex>, then its definition is actually found in the library
520file F<Text/Soundex.pm>.
521
19799a22
GS
522Perl modules always have a F<.pm> file, but there may also be
523dynamically linked executables (often ending in F<.so>) or autoloaded
5803be0d 524subroutine definitions (often ending in F<.al>) associated with the
19799a22
GS
525module. If so, these will be entirely transparent to the user of
526the module. It is the responsibility of the F<.pm> file to load
527(or arrange to autoload) any additional functionality. For example,
528although the POSIX module happens to do both dynamic loading and
5803be0d 529autoloading, the user can say just C<use POSIX> to get it all.
a0d0e21e 530
f2fc0a40
AB
531=head2 Making your module threadsafe
532
14c715f4
CP
533Since 5.6.0, Perl has had support for a new type of threads called
534interpreter threads (ithreads). These threads can be used explicitly
535and implicitly.
f2fc0a40
AB
536
537Ithreads work by cloning the data tree so that no data is shared
14c715f4 538between different threads. These threads can be used by using the C<threads>
4ebc451b
JH
539module or by doing fork() on win32 (fake fork() support). When a
540thread is cloned all Perl data is cloned, however non-Perl data cannot
14c715f4 541be cloned automatically. Perl after 5.7.2 has support for the C<CLONE>
4d5ff0dd 542special subroutine. In C<CLONE> you can do whatever
9660f481 543you need to do,
4ebc451b 544like for example handle the cloning of non-Perl data, if necessary.
38e4e52d
NC
545C<CLONE> will be called once as a class method for every package that has it
546defined (or inherits it). It will be called in the context of the new thread,
547so all modifications are made in the new area. Currently CLONE is called with
548no parameters other than the invocant package name, but code should not assume
549that this will remain unchanged, as it is likely that in future extra parameters
550will be passed in to give more information about the state of cloning.
f2fc0a40
AB
551
552If you want to CLONE all objects you will need to keep track of them per
553package. This is simply done using a hash and Scalar::Util::weaken().
554
4d5ff0dd 555Perl after 5.8.7 has support for the C<CLONE_SKIP> special subroutine.
9660f481
DM
556Like C<CLONE>, C<CLONE_SKIP> is called once per package; however, it is
557called just before cloning starts, and in the context of the parent
558thread. If it returns a true value, then no objects of that class will
559be cloned; or rather, they will be copied as unblessed, undef values.
560This provides a simple mechanism for making a module threadsafe; just add
561C<sub CLONE_SKIP { 1 }> at the top of the class, and C<DESTROY()> will be
562now only be called once per object. Of course, if the child thread needs
563to make use of the objects, then a more sophisticated approach is
564needed.
565
566Like C<CLONE>, C<CLONE_SKIP> is currently called with no parameters other
567than the invocant package name, although that may change. Similarly, to
568allow for future expansion, the return value should be a single C<0> or
569C<1> value.
570
f102b883 571=head1 SEE ALSO
cb1a09d0 572
f102b883 573See L<perlmodlib> for general style issues related to building Perl
19799a22
GS
574modules and classes, as well as descriptions of the standard library
575and CPAN, L<Exporter> for how Perl's standard import/export mechanism
890a53b9 576works, L<perltoot> and L<perltooc> for an in-depth tutorial on
19799a22
GS
577creating classes, L<perlobj> for a hard-core reference document on
578objects, L<perlsub> for an explanation of functions and scoping,
579and L<perlxstut> and L<perlguts> for more information on writing
580extension modules.