X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/a0d0e21ea6ea90a22318550944fe6cb09ae10cda..c079d275c4f9c514ec0de3de1aef066d6f4595aa:/pod/perlmod.pod diff --git a/pod/perlmod.pod b/pod/perlmod.pod index d804b1e..29ad67c 100644 --- a/pod/perlmod.pod +++ b/pod/perlmod.pod @@ -1,472 +1,472 @@ =head1 NAME -perlmod - Perl modules (packages) +perlmod - Perl modules (packages and symbol tables) =head1 DESCRIPTION =head2 Packages -Perl provides a mechanism for alternate namespaces to protect packages -from stomping on each others variables. By default, a Perl script starts -compiling into the package known as C
. You can switch namespaces -using the C declaration. The scope of the package declaration is -from the declaration itself to the end of the enclosing block (the same -scope as the local() operator). Typically it would be the first -declaration in a file to be included by the C operator. You can -switch into a package in more than one place; it merely influences which -symbol table is used by the compiler for the rest of that block. You can -refer to variables and filehandles in other packages by prefixing the -identifier with the package name and a double colon: -C<$Package::Variable>. If the package name is null, the C
package -as assumed. That is, C<$::sail> is equivalent to C<$main::sail>. - -(The old package delimiter was a single quote, but double colon -is now the preferred delimiter, in part because it's more readable -to humans, and in part because it's more readable to B macros. -It also makes C++ programmers feel like they know what's going on.) - -Packages may be nested inside other packages: C<$OUTER::INNER::var>. This -implies nothing about the order of name lookups, however. All symbols +Perl provides a mechanism for alternative namespaces to protect +packages from stomping on each other's variables. In fact, there's +really no such thing as a global variable in Perl. The package +statement declares the compilation unit as being in the given +namespace. The scope of the package declaration is from the +declaration itself through the end of the enclosing block, C, +or file, whichever comes first (the same scope as the my() and +local() operators). Unqualified dynamic identifiers will be in +this namespace, except for those few identifiers that if unqualified, +default to the main package instead of the current one as described +below. A package statement affects only dynamic variables--including +those you've used local() on--but I lexical variables created +with my(). Typically it would be the first declaration in a file +included by the C, C, or C operators. You can +switch into a package in more than one place; it merely influences +which symbol table is used by the compiler for the rest of that +block. You can refer to variables and filehandles in other packages +by prefixing the identifier with the package name and a double +colon: C<$Package::Variable>. If the package name is null, the +C
package is assumed. That is, C<$::sail> is equivalent to +C<$main::sail>. + +The old package delimiter was a single quote, but double colon is now the +preferred delimiter, in part because it's more readable to humans, and +in part because it's more readable to B macros. It also makes C++ +programmers feel like they know what's going on--as opposed to using the +single quote as separator, which was there to make Ada programmers feel +like they knew what's going on. Because the old-fashioned syntax is still +supported for backwards compatibility, if you try to use a string like +C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is, +the $s variable in package C, which is probably not what you meant. +Use braces to disambiguate, as in C<"This is ${owner}'s house">. + +Packages may themselves contain package separators, as in +C<$OUTER::INNER::var>. This implies nothing about the order of +name lookups, however. There are no relative packages: all symbols are either local to the current package, or must be fully qualified from the outer package name down. For instance, there is nowhere -within package C that C<$INNER::var> refers to C<$OUTER::INNER::var>. -It would treat package C as a totally separate global package. - -Only identifiers starting with letters (or underscore) are stored in a -package's symbol table. All other symbols are kept in package C
. -In addition, the identifiers STDIN, STDOUT, STDERR, C, -ARGVOUT, ENV, INC and SIG are forced to be in package C
, -even when used for other purposes than their built-in one. Note also -that, if you have a package called C, C or C, then you can't use -the qualified form of an identifier since it will be interpreted instead -as a pattern match, a substitution, or a translation. - -(Variables beginning with underscore used to be forced into package +within package C that C<$INNER::var> refers to +C<$OUTER::INNER::var>. It would treat package C as a totally +separate global package. + +Only identifiers starting with letters (or underscore) are stored +in a package's symbol table. All other symbols are kept in package +C
, including all punctuation variables, like $_. In addition, +when unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV, +ARGVOUT, ENV, INC, and SIG are forced to be in package C
, +even when used for other purposes than their built-in one. If you +have a package called C, C, or C, 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. + +Variables beginning with underscore used to be forced into package main, but we decided it was more useful for package writers to be able -to use leading underscore to indicate private variables and method names.) +to use leading underscore to indicate private variables and method names. +$_ is still global though. See also +L. -Eval()ed strings are compiled in the package in which the eval() was +Ced strings are compiled in the package in which the eval() was compiled. (Assignments to C<$SIG{}>, however, assume the signal -handler specified is in the C package. Qualify the signal handler name if you wish to have a signal handler in a package.) For an example, examine F in the Perl library. It initially switches to the C package so that the debugger doesn't interfere with variables -in the script you are trying to debug. At various points, however, it +in the program you are trying to debug. At various points, however, it temporarily switches back to the C
package to evaluate various expressions in the context of the C
package (or wherever you came from). See L. +The special symbol C<__PACKAGE__> contains the current package, but cannot +(easily) be used to construct variables. + +See L for other scoping issues related to my() and local(), +and L regarding closures. + =head2 Symbol Tables -The symbol table for a package happens to be stored in the associative -array of that name appended with two colons. The main symbol table's -name is thus C<%main::>, or C<%::> for short. Likewise the nested package -mentioned earlier is named C<%OUTER::INNER::>. +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 +C<%main::>, or C<%::> for short. Likewise the symbol table for the nested +package mentioned earlier is named C<%OUTER::INNER::>. + +The value in each entry of the hash is what you are referring to when you +use the C<*name> typeglob notation. In fact, the following have the same +effect, though the first is more efficient because it does the symbol +table lookups at compile time: -The value in each entry of the associative array is what you are -referring to when you use the C<*name> 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: + local *main::foo = *main::bar; + local $main::{foo} = $main::{bar}; - local(*main::foo) = *main::bar; local($main::{'foo'}) = - $main::{'bar'}; +(Be sure to note the B difference between the second line above +and C. The former is accessing the hash +C<%main::>, which is the symbol table of package C
. The latter is +simply assigning scalar C<$bar> in package C
to scalar C<$foo> of +the same package.) You can use this to print out all the variables in a package, for -instance. Here is F from the Perl library: - - package dumpvar; - sub main::dumpvar { - ($package) = @_; - local(*stab) = eval("*${package}::"); - while (($key,$val) = each(%stab)) { - local(*entry) = $val; - if (defined $entry) { - print "\$$key = '$entry'\n"; - } - - if (defined @entry) { - print "\@$key = (\n"; - foreach $num ($[ .. $#entry) { - print " $num\t'",$entry[$num],"'\n"; - } - print ")\n"; - } - - if ($key ne "${package}::" && defined %entry) { - print "\%$key = (\n"; - foreach $key (sort keys(%entry)) { - print " $key\t'",$entry{$key},"'\n"; - } - print ")\n"; - } - } - } - -Note that even though the subroutine is compiled in package C, -the name of the subroutine is qualified so that its name is inserted -into package C
. - -Assignment to a symbol table entry performs an aliasing operation, -i.e., +instance. The standard but antiquated F library and +the CPAN module Devel::Symdump make use of this. + +Assignment to a typeglob performs an aliasing operation, i.e., *dick = *richard; -causes variables, subroutines and filehandles accessible via the -identifier C to also be accessible via the symbol C. If -you only want to alias a particular variable or subroutine, you can -assign a reference instead: +causes variables, subroutines, formats, and file and directory handles +accessible via the identifier C also to be accessible via the +identifier C. If you want to alias only a particular variable or +subroutine, assign a reference instead: *dick = \$richard; -makes $richard and $dick the same variable, but leaves +Which makes $richard and $dick the same variable, but leaves @richard and @dick as separate arrays. Tricky, eh? -=head2 Package Constructors and Destructors - -There are two special subroutine definitions that function as package -constructors and destructors. These are the C and C -routines. The C is optional for these routines. - -A C 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 blocks within a -file--they will execute in order of definition. Because a C -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. - -An C subroutine is executed as late as possible, that is, when the -interpreter is being exited, even if it is exiting as a result of a -die() function. (But not if it's is being blown out of the water by a -signal--you have to trap that yourself (if you can).) You may have -multiple C blocks within a file--they wil execute in reverse -order of definition; that is: last in, first out (LIFO). - -Note that when you use the B<-n> and B<-p> switches to Perl, C -and C work just as they do in B, as a degenerate case. - -=head2 Perl Classes - -There is no special class syntax in Perl 5, but a package may function -as a class if it provides subroutines that function as methods. Such a -package may also derive some of its methods from another class package -by listing the other package name in its @ISA array. For more on -this, see L. +This mechanism may be used to pass and return cheap references +into or from subroutines if you don't want to copy the whole +thing. It only works when assigning to dynamic variables, not +lexicals. -=head2 Perl Modules - -In Perl 5, the notion of packages has been extended into the notion of -modules. A module is a package that is defined in a library file of -the same name, and is designed to be reusable. It may do this by -providing a mechanism for exporting some of its symbols into the symbol -table of any package using it. Or it may function as a class -definition and make its semantics available implicitly through method -calls on the class and its objects, without explicit exportation of any -symbols. Or it can do a little of both. - -Perl modules are included by saying - - use Module; - -or - - use Module LIST; - -This is exactly equivalent to - - BEGIN { require "Module.pm"; import Module; } - -or - - BEGIN { require "Module.pm"; import Module LIST; } - -All Perl module files have the extension F<.pm>. C assumes this so -that you don't have to spell out "F" in quotes. This also -helps to differentiate new modules from old F<.pl> and F<.ph> files. -Module names are also capitalized unless they're functioning as pragmas, -"Pragmas" are in effect compiler directives, and are sometimes called -"pragmatic modules" (or even "pragmata" if you're a classicist). - -Because the C statement implies a C block, the importation -of semantics happens at the moment the C statement is compiled, -before the rest of the file is compiled. This is how it is able -to function as a pragma mechanism, and also how modules are able to -declare subroutines that are then visible as list operators for -the rest of the current file. This will not work if you use C -instead of C. Therefore, if you're planning on the module altering -your namespace, use C; otherwise, use C. Otherwise you -can get into this problem: - - require Cwd; # make Cwd:: accessible - $here = Cwd::getcwd(); - - use Cwd; # import names from Cwd:: - $here = getcwd(); - - require Cwd; # make Cwd:: accessible - $here = getcwd(); # oops! no main::getcwd() - -Perl packages may be nested inside other package names, so we can have -package names containing C<::>. But if we used that package name -directly as a filename it would makes for unwieldy or impossible -filenames on some systems. Therefore, if a module's name is, say, -C, then its definition is actually found in the library -file F. + %some_hash = (); # can't be my() + *some_hash = fn( \%another_hash ); + sub fn { + local *hashsym = shift; + # now use %hashsym normally, and you + # will affect the caller's %another_hash + my %nhash = (); # do what you want + return \%nhash; + } -Perl modules always have a F<.pm> file, but there may also be dynamically -linked executables or autoloaded subroutine definitions associated with -the module. If so, these will be entirely transparent to the user of -the module. It is the responsibility of the F<.pm> file to load (or -arrange to autoload) any additional functionality. The POSIX module -happens to do both dynamic loading and autoloading, but the user can -just say C to get it all. +On return, the reference will overwrite the hash slot in the +symbol table specified by the *some_hash typeglob. This +is a somewhat tricky way of passing around references cheaply +when you don't want to have to remember to dereference variables +explicitly. -For more information on writing extension modules, see L -and L. +Another use of symbol tables is for making "constant" scalars. -=head1 NOTE + *PI = \3.14159265358979; -Perl does not enforce private and public parts of its modules as you may -have been used to in other languages like C++, Ada, or Modula-17. Perl -doesn't have an infatuation with enforced privacy. It would prefer -that you stayed out of its living room because you weren't invited, not -because it has a shotgun. +Now you cannot alter C<$PI>, which is probably a good thing all in all. +This isn't the same as a constant subroutine, which is subject to +optimization at compile-time. A constant subroutine is one prototyped +to take no arguments and to return a constant expression. See +L for details on these. The C pragma is a +convenient shorthand for these. -The module and its user have a contract, part of which is common law, -and part of which is "written". Part of the common law contract is -that a module doesn't pollute any namespace it wasn't asked to. The -written contract for the module (AKA documentation) may make other -provisions. But then you know when you C that -you're redefining the world and willing to take the consequences. +You can say C<*foo{PACKAGE}> and C<*foo{NAME}> to find out what name and +package the *foo symbol table entry comes from. This may be useful +in a subroutine that gets passed typeglobs as arguments: -=head1 THE PERL MODULE LIBRARY + sub identify_typeglob { + my $glob = shift; + print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\n"; + } + identify_typeglob *foo; + identify_typeglob *bar::baz; -A number of modules are included the the Perl distribution. These are -described below, and all end in F<.pm>. You may also discover files in -the library directory that end in either F<.pl> or F<.ph>. These are old -libaries supplied so that old programs that use them still run. The -F<.pl> files will all eventually be converted into standard modules, and -the F<.ph> files made by B will probably end up as extension modules -made by B. (Some F<.ph> values may already be available through the -POSIX module.) The B file in the distribution may help in your -conversion, but it's just a mechanical process, so is far from bullet proof. +This prints -=head2 Pragmatic Modules + You gave me main::foo + You gave me bar::baz -They work somewhat like pragmas in that they tend to affect the compilation of -your program, and thus will usually only work well when used within a -C, or C. These are locally scoped, so if an inner BLOCK -may countermand any of these by saying +The C<*foo{THING}> notation can also be used to obtain references to the +individual elements of *foo. See L. - no integer; - no strict 'refs'; +Subroutine definitions (and declarations, for that matter) need +not necessarily be situated in the package whose symbol table they +occupy. You can define a subroutine outside its package by +explicitly qualifying the name of the subroutine: -which lasts until the end of that BLOCK. + package main; + sub Some_package::foo { ... } # &foo defined in Some_package -The following programs are defined (and have their own documentation). +This is just a shorthand for a typeglob assignment at compile time: -=over 12 + BEGIN { *Some_package::foo = sub { ... } } -=item C +and is I the same as writing: -Perl pragma to compute arithmetic in integer instead of double + { + package Some_package; + sub foo { ... } + } -=item C +In the first two versions, the body of the subroutine is +lexically in the main package, I in Some_package. So +something like this: -Perl pragma to request less of something from the compiler + package main; -=item C + $Some_package::name = "fred"; + $main::name = "barney"; -Perl pragma to enable stack backtrace on unexpected signals + sub Some_package::foo { + print "in ", __PACKAGE__, ": \$name is '$name'\n"; + } -=item C + Some_package::foo(); -Perl pragma to restrict unsafe constructs +prints: -=item C + in main: $name is 'barney' -Perl pragma to predeclare sub names +rather than: -=back + in Some_package: $name is 'fred' -=head2 Standard Modules +This also has implications for the use of the SUPER:: qualifier +(see L). -The following modules are all expacted to behave in a well-defined -manner with respect to namespace pollution because they use the -Exporter module. -See their own documentation for details. - -=over 12 - -=item C - -create an abbreviation table from a list - -=item C - -provide framework for multiple DBMs - -=item C - -load functions only on demand - -=item C - -split a package for autoloading - -=item C - -parse file anme and path from a specification - -=item C - -benchmark running times of code - -=item C - -warn or die of errors (from perspective of caller) - -=item C - -run many filetest checks on a tree - -=item C - -compare 8-bit scalar data according to the current locale - -=item C - -access Perl configuration option - -=item C - -get pathname of current working directory - -=item C +=head2 Package Constructors and Destructors -Dynamically load C libraries into Perl code +Four special subroutines act as package constructors and destructors. +These are the C, C, C, and C routines. The +C is optional for these routines. + +A C 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 blocks within a file--they +will execute in order of definition. Because a C 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 +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. + +An C subroutine 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, or +being blown out of the water by a signal--you have to trap that yourself +(if you can).) You may have multiple C blocks within a file--they +will execute in reverse order of definition; that is: last in, first +out (LIFO). C blocks are not executed when you run perl with the +C<-c> switch, or if compilation fails. + +Inside an C subroutine, C<$?> contains the value that the program is +going to pass to C. 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). + +Similar to C blocks, C 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 make use of +C blocks to initialize and resolve pointers to XSUBs. + +Similar to C blocks, C blocks are run just after the +Perl compile phase ends and before the run time begins, in +LIFO order. C blocks are again useful in the Perl compiler +suite to save the compiled state of the program. + +When you use the B<-n> and B<-p> switches to Perl, C and +C work just as they do in B, as a degenerate case. +Both C and C blocks are run when you use the B<-c> +switch for a compile-only syntax check, although your main code +is not. -=item C +=head2 Perl Classes -use nice English (or B) names for ugly punctuation variables +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 +package may also derive some of its methods from another class (package) +by listing the other package name(s) in its global @ISA array (which +must be a package global, not a lexical). -=item C +For more on this, see L and L. -Perl module that imports environment variables +=head2 Perl Modules -=item C +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 +designed to be reusable by other modules or programs. It may do this +by providing a mechanism for exporting some of its symbols into the +symbol table of any package using it. Or it may function as a class +definition and make its semantics available implicitly through +method calls on the class and its objects, without explicitly +exporting anything. Or it can do a little of both. -module to control namespace manipulations +For example, to start a traditional, non-OO module called Some::Module, +create a file called F and start with this template: -=item C + package Some::Module; # assumes Some/Module.pm -load the C Fcntl.h defines + use strict; + use warnings; -=item C + BEGIN { + use Exporter (); + our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS); -supply object methods for filehandles + # set the version for version checking + $VERSION = 1.00; + # if using RCS/CVS, this may be preferred + $VERSION = do { my @r = (q$Revision: 2.21 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r }; # must be all one line, for MakeMaker -=item C + @ISA = qw(Exporter); + @EXPORT = qw(&func1 &func2 &func4); + %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ], -traverse a file tree + # your exported package globals go here, + # as well as any optionally exported functions + @EXPORT_OK = qw($Var1 %Hashit &func3); + } + our @EXPORT_OK; -=item C + # exported package globals go here + our $Var1; + our %Hashit; -traverse a directory structure depth-first + # non-exported package globals go here + our @more; + our $stuff; -=item C + # initialize package globals, first exported ones + $Var1 = ''; + %Hashit = (); -basic and extended getopt(3) processing + # then the others (which are still accessible as $Some::Module::stuff) + $stuff = ''; + @more = (); -=item C + # all file-scoped lexicals must be created before + # the functions below that use them. -generate a Makefile for Perl extension + # file-private lexicals go here + my $priv_var = ''; + my %secret_hash = (); -=item C + # here's a file-private function as a closure, + # callable as &$priv_func; it cannot be prototyped. + my $priv_func = sub { + # stuff goes here. + }; -open a process for both reading and writing + # make all your functions, whether exported or not; + # remember to put something interesting in the {} stubs + sub func1 {} # no prototype + sub func2() {} # proto'd void + sub func3($$) {} # proto'd to 2 scalars -=item C + # this one isn't exported, but could be called! + sub func4(\%) {} # proto'd to 1 hash ref -open a process for reading, writing, and error handling + END { } # module clean-up code here (global destructor) -=item C + ## YOUR CODE GOES HERE -Perl interface to IEEE 1003.1 namespace + 1; # don't forget to return a true value from the file -=item C +Then go on to declare and use your variables in functions without +any qualifications. See L and the L for +details on mechanics and style issues in module creation. -check a host for upness +Perl modules are included into your program by saying -=item C + use Module; -load the C socket.h defines +or -=back + use Module LIST; -=head2 Extension Modules +This is exactly equivalent to -Extension modules are written in C (or a mix of Perl and C) and get -dynamically loaded into Perl if and when you need them. Supported -extension modules include the Socket, Fcntl, and POSIX modules. + BEGIN { require Module; import Module; } -The following are popular C extension modules, which while available at -Perl 5.0 release time, do not come not bundled (at least, not completely) -due to their size, volatility, or simply lack of time for adequate testing -and configuration across the multitude of platforms on which Perl was -beta-tested. You are encouraged to look for them in archie(1L), the Perl -FAQ or Meta-FAQ, the WWW page, and even their authors before randomly -posting asking for their present condition and disposition. There's no -guarantee that the names or addresses below have not changed since printing, -and in fact, they probably have! +or -=over 12 + BEGIN { require Module; import Module LIST; } -=item C +As a special case -Written by William Setzer >, while not -included with the standard distribution, this extension module ports to -most systems. FTP from your nearest Perl archive site, or try + use Module (); - ftp://ftp.ncsu.edu/pub/math/wsetzer/cursperl5??.tar.gz +is exactly equivalent to -It is currently in alpha test, so the name and ftp location may -change. + BEGIN { require Module; } +All Perl module files have the extension F<.pm>. The C operator +assumes this so you don't have to spell out "F" in quotes. +This also helps to differentiate new modules from old F<.pl> and +F<.ph> files. Module names are also capitalized unless they're +functioning as pragmas; pragmas are in effect compiler directives, +and are sometimes called "pragmatic modules" (or even "pragmata" +if you're a classicist). -=item C +The two statements: -This is the portable database interface written by ->. This supersedes the many perl4 ports for -database extensions. The official archive for DBperl extensions is -F. This archive contains copies of perl4 -ports for Ingres, Oracle, Sybase, Informix, Unify, Postgres, and -Interbase, as well as rdb and shql and other non-SQL systems. + require SomeModule; + require "SomeModule.pm"; -=item C +differ from each other in two ways. In the first case, any double +colons in the module name, such as C, are translated +into your system's directory separator, usually "/". The second +case does not, and would have to be specified literally. The other +difference is that seeing the first C clues in the compiler +that uses of indirect object notation involving "SomeModule", as +in C<$ob = purge SomeModule>, are method calls, not function calls. +(Yes, this really can make a difference.) -Fastest and most restriction-free of the DBM bindings, this extension module -uses the popular Berkeley DB to tie() into your hashes. This has a -standardly-distributed man page and dynamic loading extension module, but -you'll have to fetch the Berkeley code yourself. See L for -where. +Because the C statement implies a C block, the importing +of semantics happens as soon as the C statement is compiled, +before the rest of the file is compiled. This is how it is able +to function as a pragma mechanism, and also how modules are able to +declare subroutines that are then visible as list or unary operators for +the rest of the current file. This will not work if you use C +instead of C. With C you can get into this problem: -=item C + require Cwd; # make Cwd:: accessible + $here = Cwd::getcwd(); -This extension module is a front to the Athena and Xlib libraries for Perl -GUI progamming, originally written by by Dominic Giampaolo ->, then and rewritten for Sx by FrEdEric -Chauveau >. It's available for FTP from + use Cwd; # import names from Cwd:: + $here = getcwd(); - ftp.pasteur.fr:/pub/Perl/Sx.tar.gz + require Cwd; # make Cwd:: accessible + $here = getcwd(); # oops! no main::getcwd() -=item C +In general, C is recommended over C, +because it determines module availability at compile time, not in the +middle of your program's execution. An exception would be if two modules +each tried to C each other, and each also called a function from +that other module. In that case, it's easy to use Cs instead. -This extension module is an object-oriented Perl5 binding to the popular -tcl/tk X11 package. However, you need know no TCL to use it! -It was written by Malcolm Beattie >. -If you are unable to locate it using archie(1L) or a similar -tool, you may try retrieving it from F -from Malcolm's machine listed above. +Perl packages may be nested inside other package names, so we can have +package names containing C<::>. But if we used that package name +directly as a filename it would make for unwieldy or impossible +filenames on some systems. Therefore, if a module's name is, say, +C, then its definition is actually found in the library +file F. -=back +Perl modules always have a F<.pm> file, but there may also be +dynamically linked executables (often ending in F<.so>) or autoloaded +subroutine definitions (often ending in F<.al>) associated with the +module. If so, these will be entirely transparent to the user of +the module. It is the responsibility of the F<.pm> file to load +(or arrange to autoload) any additional functionality. For example, +although the POSIX module happens to do both dynamic loading and +autoloading, the user can say just C to get it all. + +=head2 Making your module threadsafe + +Perl has since 5.6.0 support for a new type of threads called +interpreter threads. These threads can be used explicitly and implicitly. + +Ithreads work by cloning the data tree so that no data is shared +between different threads. These threads can be used using the threads +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. +Perl after 5.7.2 has support for the C keyword. C 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. + +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(). + +=head1 SEE ALSO + +See L for general style issues related to building Perl +modules and classes, as well as descriptions of the standard library +and CPAN, L for how Perl's standard import/export mechanism +works, L and L for an in-depth tutorial on +creating classes, L for a hard-core reference document on +objects, L for an explanation of functions and scoping, +and L and L for more information on writing +extension modules.