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