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