Profile of Module/Runtime.pm

← Index
NYTProf Performance Profile «line view»
For -e
Run on Thu Jun 30 16:34:56 2016
Reported on Thu Jun 30 16:35:09 2016

Filename | /home/s1/perl5/perlbrew/perls/perl-5.22.1/lib/site_perl/5.22.1/Module/Runtime.pm
Statements | Executed 51 statements in 1.68ms

Subroutines
Calls | P | F | Exclusive Time | Inclusive Time | Subroutine
--- | --- | --- | --- | --- | ---
1 | 1 | 1 | 461µs | 794µs | Module::Runtime::::require_moduleModule::Runtime::require_module
3 | 3 | 1 | 82µs | 82µs | Module::Runtime::::CORE:regcompModule::Runtime::CORE:regcomp (opcode)
3 | 3 | 3 | 41µs | 44µs | Module::Runtime::::importModule::Runtime::import
1 | 1 | 1 | 21µs | 21µs | Module::Runtime::::BEGIN@116Module::Runtime::BEGIN@116
1 | 1 | 1 | 10µs | 33µs | Module::Runtime::::is_module_nameModule::Runtime::is_module_name
1 | 1 | 1 | 9µs | 9µs | Module::Runtime::::BEGIN@289Module::Runtime::BEGIN@289
1 | 1 | 1 | 8µs | 46µs | Module::Runtime::::module_notional_filenameModule::Runtime::module_notional_filename
4 | 2 | 1 | 7µs | 7µs | Module::Runtime::::CORE:matchModule::Runtime::CORE:match (opcode)
6 | 6 | 1 | 5µs | 5µs | Module::Runtime::::CORE:qrModule::Runtime::CORE:qr (opcode)
1 | 1 | 1 | 4µs | 4µs | Module::Runtime::::BEGIN@120Module::Runtime::BEGIN@120
1 | 1 | 1 | 4µs | 4µs | Module::Runtime::::BEGIN@296Module::Runtime::BEGIN@296
1 | 1 | 1 | 3µs | 36µs | Module::Runtime::::check_module_nameModule::Runtime::check_module_name
1 | 1 | 1 | 2µs | 2µs | Module::Runtime::::_is_stringModule::Runtime::_is_string
1 | 1 | 1 | 2µs | 2µs | Module::Runtime::::CORE:substModule::Runtime::CORE:subst (opcode)
0 | 0 | 0 | 0s | 0s | Module::Runtime::::check_module_specModule::Runtime::check_module_spec
0 | 0 | 0 | 0s | 0s | Module::Runtime::::compose_module_nameModule::Runtime::compose_module_name
0 | 0 | 0 | 0s | 0s | Module::Runtime::::is_module_specModule::Runtime::is_module_spec
0 | 0 | 0 | 0s | 0s | Module::Runtime::::use_moduleModule::Runtime::use_module
0 | 0 | 0 | 0s | 0s | Module::Runtime::::use_package_optimisticallyModule::Runtime::use_package_optimistically

Call graph for these subroutines as a Graphviz dot language file.

Line | State ments | Time on line | Calls | Time in subs | Code
--- | --- | --- | --- | --- | ---
1 |  |  |  |  | =head1 NAME
2 |  |  |  |  |
3 |  |  |  |  | Module::Runtime - runtime module handling
4 |  |  |  |  |
5 |  |  |  |  | =head1 SYNOPSIS
6 |  |  |  |  |
7 |  |  |  |  | use Module::Runtime qw(
8 |  |  |  |  | $module_name_rx is_module_name check_module_name
9 |  |  |  |  | module_notional_filename require_module
10 |  |  |  |  | );
11 |  |  |  |  |
12 |  |  |  |  | if($module_name =~ /\A$module_name_rx\z/o) { ...
13 |  |  |  |  | if(is_module_name($module_name)) { ...
14 |  |  |  |  | check_module_name($module_name);
15 |  |  |  |  |
16 |  |  |  |  | $notional_filename = module_notional_filename($module_name);
17 |  |  |  |  | require_module($module_name);
18 |  |  |  |  |
19 |  |  |  |  | use Module::Runtime qw(use_module use_package_optimistically);
20 |  |  |  |  |
21 |  |  |  |  | $bi = use_module("Math::BigInt", 1.31)->new("1_234");
22 |  |  |  |  | $widget = use_package_optimistically("Local::Widget")->new;
23 |  |  |  |  |
24 |  |  |  |  | use Module::Runtime qw(
25 |  |  |  |  | $top_module_spec_rx $sub_module_spec_rx
26 |  |  |  |  | is_module_spec check_module_spec
27 |  |  |  |  | compose_module_name
28 |  |  |  |  | );
29 |  |  |  |  |
30 |  |  |  |  | if($spec =~ /\A$top_module_spec_rx\z/o) { ...
31 |  |  |  |  | if($spec =~ /\A$sub_module_spec_rx\z/o) { ...
32 |  |  |  |  | if(is_module_spec("Standard::Prefix", $spec)) { ...
33 |  |  |  |  | check_module_spec("Standard::Prefix", $spec);
34 |  |  |  |  |
35 |  |  |  |  | $module_name =
36 |  |  |  |  | compose_module_name("Standard::Prefix", $spec);
37 |  |  |  |  |
38 |  |  |  |  | =head1 DESCRIPTION
39 |  |  |  |  |
40 |  |  |  |  | The functions exported by this module deal with runtime handling of
41 |  |  |  |  | Perl modules, which are normally handled at compile time. This module
42 |  |  |  |  | avoids using any other modules, so that it can be used in low-level
43 |  |  |  |  | infrastructure.
44 |  |  |  |  |
45 |  |  |  |  | The parts of this module that work with module names apply the same syntax
46 |  |  |  |  | that is used for barewords in Perl source. In principle this syntax
47 |  |  |  |  | can vary between versions of Perl, and this module applies the syntax of
48 |  |  |  |  | the Perl on which it is running. In practice the usable syntax hasn't
49 |  |  |  |  | changed yet. There's some intent for Unicode module names to be supported
50 |  |  |  |  | in the future, but this hasn't yet amounted to any consistent facility.
51 |  |  |  |  |
52 |  |  |  |  | The functions of this module whose purpose is to load modules include
53 |  |  |  |  | workarounds for three old Perl core bugs regarding C<require>. These
54 |  |  |  |  | workarounds are applied on any Perl version where the bugs exist, except
55 |  |  |  |  | for a case where one of the bugs cannot be adequately worked around in
56 |  |  |  |  | pure Perl.
57 |  |  |  |  |
58 |  |  |  |  | =head2 Module name syntax
59 |  |  |  |  |
60 |  |  |  |  | The usable module name syntax has not changed from Perl 5.000 up to
61 |  |  |  |  | Perl 5.19.8. The syntax is composed entirely of ASCII characters.
62 |  |  |  |  | From Perl 5.6 onwards there has been some attempt to allow the use of
63 |  |  |  |  | non-ASCII Unicode characters in Perl source, but it was fundamentally
64 |  |  |  |  | broken (like the entirety of Perl 5.6's Unicode handling) and remained
65 |  |  |  |  | pretty much entirely unusable until it got some attention in the Perl
66 |  |  |  |  | 5.15 series. Although Unicode is now consistently accepted by the
67 |  |  |  |  | parser in some places, it remains broken for module names. Furthermore,
68 |  |  |  |  | there has not yet been any work on how to map Unicode module names into
69 |  |  |  |  | filenames, so in that respect also Unicode module names are unusable.
70 |  |  |  |  |
71 |  |  |  |  | The module name syntax is, precisely: the string must consist of one or
72 |  |  |  |  | more segments separated by C<::>; each segment must consist of one or more
73 |  |  |  |  | identifier characters (ASCII alphanumerics plus "_"); the first character
74 |  |  |  |  | of the string must not be a digit. Thus "C<IO::File>", "C<warnings>",
75 |  |  |  |  | and "C<foo::123::x_0>" are all valid module names, whereas "C<IO::>"
76 |  |  |  |  | and "C<1foo::bar>" are not. C<'> separators are not permitted by this
77 |  |  |  |  | module, though they remain usable in Perl source, being translated to
78 |  |  |  |  | C<::> in the parser.
79 |  |  |  |  |
80 |  |  |  |  | =head2 Core bugs worked around
81 |  |  |  |  |
82 |  |  |  |  | The first bug worked around is core bug [perl #68590], which causes
83 |  |  |  |  | lexical state in one file to leak into another that is C<require>d/C<use>d
84 |  |  |  |  | from it. This bug is present from Perl 5.6 up to Perl 5.10, and is
85 |  |  |  |  | fixed in Perl 5.11.0. From Perl 5.9.4 up to Perl 5.10.0 no satisfactory
86 |  |  |  |  | workaround is possible in pure Perl. The workaround means that modules
87 |  |  |  |  | loaded via this module don't suffer this pollution of their lexical
88 |  |  |  |  | state. Modules loaded in other ways, or via this module on the Perl
89 |  |  |  |  | versions where the pure Perl workaround is impossible, remain vulnerable.
90 |  |  |  |  | The module L<Lexical::SealRequireHints> provides a complete workaround
91 |  |  |  |  | for this bug.
92 |  |  |  |  |
93 |  |  |  |  | The second bug worked around causes some kinds of failure in module
94 |  |  |  |  | loading, principally compilation errors in the loaded module, to be
95 |  |  |  |  | recorded in C<%INC> as if they were successful, so later attempts to load
96 |  |  |  |  | the same module immediately indicate success. This bug is present up
97 |  |  |  |  | to Perl 5.8.9, and is fixed in Perl 5.9.0. The workaround means that a
98 |  |  |  |  | compilation error in a module loaded via this module won't be cached as
99 |  |  |  |  | a success. Modules loaded in other ways remain liable to produce bogus
100 |  |  |  |  | C<%INC> entries, and if a bogus entry exists then it will mislead this
101 |  |  |  |  | module if it is used to re-attempt loading.
102 |  |  |  |  |
103 |  |  |  |  | The third bug worked around causes the wrong context to be seen at
104 |  |  |  |  | file scope of a loaded module, if C<require> is invoked in a location
105 |  |  |  |  | that inherits context from a higher scope. This bug is present up to
106 |  |  |  |  | Perl 5.11.2, and is fixed in Perl 5.11.3. The workaround means that
107 |  |  |  |  | a module loaded via this module will always see the correct context.
108 |  |  |  |  | Modules loaded in other ways remain vulnerable.
109 |  |  |  |  |
110 |  |  |  |  | =cut
111 |  |  |  |  |
112 |  |  |  |  | package Module::Runtime;
113 |  |  |  |  |
114 |  |  |  |  | # Don't "use 5.006" here, because Perl 5.15.6 will load feature.pm if
115 |  |  |  |  | # the version check is done that way.
116 | 1 | 42µs | 1 | 21µs | # spent 21µs within Module::Runtime::BEGIN@116 which was called: # once (21µs+0s) by Module::Implementation::BEGIN@8 at line 116 BEGIN { require 5.006; } # spent 21µs making 1 call to Module::Runtime::BEGIN@116
117 |  |  |  |  | # Don't "use warnings" here, to avoid dependencies. Do standardise the
118 |  |  |  |  | # warning status by lexical override; unfortunately the only safe bitset
119 |  |  |  |  | # to build in is the empty set, equivalent to "no warnings".
120 | 1 | 688µs | 1 | 4µs | # spent 4µs within Module::Runtime::BEGIN@120 which was called: # once (4µs+0s) by Module::Implementation::BEGIN@8 at line 120 BEGIN { ${^WARNING_BITS} = ""; } # spent 4µs making 1 call to Module::Runtime::BEGIN@120
121 |  |  |  |  | # Don't "use strict" here, to avoid dependencies.
122 |  |  |  |  |
123 | 1 | 500ns |  |  | our $VERSION = "0.014";
124 |  |  |  |  |
125 |  |  |  |  | # Don't use Exporter here, to avoid dependencies.
126 | 1 | 2µs |  |  | our @EXPORT_OK = qw(
127 |  |  |  |  | $module_name_rx is_module_name is_valid_module_name check_module_name
128 |  |  |  |  | module_notional_filename require_module
129 |  |  |  |  | use_module use_package_optimistically
130 |  |  |  |  | $top_module_spec_rx $sub_module_spec_rx
131 |  |  |  |  | is_module_spec is_valid_module_spec check_module_spec
132 |  |  |  |  | compose_module_name
133 |  |  |  |  | );
134 | 1 | 9µs |  |  | my %export_ok = map { ($_ => undef) } @EXPORT_OK;
135 |  |  |  |  | # spent 44µs (41+3) within Module::Runtime::import which was called 3 times, avg 15µs/call: # once (16µs+1µs) by DateTime::TimeZone::Local::BEGIN@8 at line 8 of DateTime/TimeZone/Local.pm # once (14µs+1000ns) by Module::Implementation::BEGIN@8 at line 8 of Module/Implementation.pm # once (12µs+800ns) by DateTime::TimeZone::BEGIN@14 at line 14 of DateTime/TimeZone.pm sub import {
136 | 3 | 1µs |  |  | my $me = shift;
137 | 3 | 2µs |  |  | my $callpkg = caller(0);
138 | 3 | 900ns |  |  | my $errs = "";
139 | 3 | 4µs |  |  | foreach(@_) {
140 | 3 | 4µs |  |  | if(exists $export_ok{$_}) {
141 |  |  |  |  | # We would need to do "no strict 'refs'" here
142 |  |  |  |  | # if we had enabled strict at file scope.
143 | 3 | 14µs | 3 | 3µs | if(/\A\$(.*)\z/s) { # spent 3µs making 3 calls to Module::Runtime::CORE:match, avg 933ns/call
144 |  |  |  |  | *{$callpkg."::".$1} = \$$1;
145 |  |  |  |  | } else {
146 | 3 | 13µs |  |  | *{$callpkg."::".$_} = \&$_;
147 |  |  |  |  | }
148 |  |  |  |  | } else {
149 |  |  |  |  | $errs .= "\"$_\" is not exported by the $me module\n";
150 |  |  |  |  | }
151 |  |  |  |  | }
152 | 3 | 11µs |  |  | if($errs ne "") {
153 |  |  |  |  | die "${errs}Can't continue after import errors ".
154 |  |  |  |  | "at @{[(caller(0))[1]]} line @{[(caller(0))[2]]}.\n";
155 |  |  |  |  | }
156 |  |  |  |  | }
157 |  |  |  |  |
158 |  |  |  |  | # Logic duplicated from Params::Classify. Duplicating it here avoids
159 |  |  |  |  | # an extensive and potentially circular dependency graph.
160 |  |  |  |  | # spent 2µs within Module::Runtime::_is_string which was called: # once (2µs+0s) by Module::Runtime::is_module_name at line 222 sub _is_string($) {
161 | 1 | 400ns |  |  | my($arg) = @_;
162 | 1 | 4µs |  |  | return defined($arg) && ref(\$arg) eq "SCALAR";
163 |  |  |  |  | }
164 |  |  |  |  |
165 |  |  |  |  | =head1 REGULAR EXPRESSIONS
166 |  |  |  |  |
167 |  |  |  |  | These regular expressions do not include any anchors, so to check
168 |  |  |  |  | whether an entire string matches a syntax item you must supply the
169 |  |  |  |  | anchors yourself.
170 |  |  |  |  |
171 |  |  |  |  | =over
172 |  |  |  |  |
173 |  |  |  |  | =item $module_name_rx
174 |  |  |  |  |
175 |  |  |  |  | Matches a valid Perl module name in bareword syntax.
176 |  |  |  |  |
177 |  |  |  |  | =cut
178 |  |  |  |  |
179 | 1 | 8µs | 1 | 2µs | our $module_name_rx = qr/[A-Z_a-z][0-9A-Z_a-z]*(?:::[0-9A-Z_a-z]+)*/; # spent 2µs making 1 call to Module::Runtime::CORE:qr
180 |  |  |  |  |
181 |  |  |  |  | =item $top_module_spec_rx
182 |  |  |  |  |
183 |  |  |  |  | Matches a module specification for use with L</compose_module_name>,
184 |  |  |  |  | where no prefix is being used.
185 |  |  |  |  |
186 |  |  |  |  | =cut
187 |  |  |  |  |
188 | 1 | 3µs | 1 | 600ns | my $qual_module_spec_rx = # spent 600ns making 1 call to Module::Runtime::CORE:qr
189 |  |  |  |  | qr#(?:/|::)[A-Z_a-z][0-9A-Z_a-z]*(?:(?:/|::)[0-9A-Z_a-z]+)*#;
190 |  |  |  |  |
191 | 1 | 3µs | 1 | 500ns | my $unqual_top_module_spec_rx = # spent 500ns making 1 call to Module::Runtime::CORE:qr
192 |  |  |  |  | qr#[A-Z_a-z][0-9A-Z_a-z]*(?:(?:/|::)[0-9A-Z_a-z]+)*#;
193 |  |  |  |  |
194 | 1 | 44µs | 2 | 37µs | our $top_module_spec_rx = qr/$qual_module_spec_rx|$unqual_top_module_spec_rx/o; # spent 36µs making 1 call to Module::Runtime::CORE:regcomp # spent 700ns making 1 call to Module::Runtime::CORE:qr
195 |  |  |  |  |
196 |  |  |  |  | =item $sub_module_spec_rx
197 |  |  |  |  |
198 |  |  |  |  | Matches a module specification for use with L</compose_module_name>,
199 |  |  |  |  | where a prefix is being used.
200 |  |  |  |  |
201 |  |  |  |  | =cut
202 |  |  |  |  |
203 | 1 | 3µs | 1 | 600ns | my $unqual_sub_module_spec_rx = qr#[0-9A-Z_a-z]+(?:(?:/|::)[0-9A-Z_a-z]+)*#; # spent 600ns making 1 call to Module::Runtime::CORE:qr
204 |  |  |  |  |
205 | 1 | 36µs | 2 | 30µs | our $sub_module_spec_rx = qr/$qual_module_spec_rx|$unqual_sub_module_spec_rx/o; # spent 29µs making 1 call to Module::Runtime::CORE:regcomp # spent 800ns making 1 call to Module::Runtime::CORE:qr
206 |  |  |  |  |
207 |  |  |  |  | =back
208 |  |  |  |  |
209 |  |  |  |  | =head1 FUNCTIONS
210 |  |  |  |  |
211 |  |  |  |  | =head2 Basic module handling
212 |  |  |  |  |
213 |  |  |  |  | =over
214 |  |  |  |  |
215 |  |  |  |  | =item is_module_name(ARG)
216 |  |  |  |  |
217 |  |  |  |  | Returns a truth value indicating whether I<ARG> is a plain string
218 |  |  |  |  | satisfying Perl module name syntax as described for L</$module_name_rx>.
219 |  |  |  |  |
220 |  |  |  |  | =cut
221 |  |  |  |  |
222 | 1 | 31µs | 3 | 23µs | # spent 33µs (10+23) within Module::Runtime::is_module_name which was called: # once (10µs+23µs) by Module::Runtime::check_module_name at line 241 sub is_module_name($) { _is_string($_[0]) && $_[0] =~ /\A$module_name_rx\z/o } # spent 17µs making 1 call to Module::Runtime::CORE:regcomp # spent 4µs making 1 call to Module::Runtime::CORE:match # spent 2µs making 1 call to Module::Runtime::_is_string
223 |  |  |  |  |
224 |  |  |  |  | =item is_valid_module_name(ARG)
225 |  |  |  |  |
226 |  |  |  |  | Deprecated alias for L</is_module_name>.
227 |  |  |  |  |
228 |  |  |  |  | =cut
229 |  |  |  |  |
230 | 1 | 1µs |  |  | *is_valid_module_name = \&is_module_name;
231 |  |  |  |  |
232 |  |  |  |  | =item check_module_name(ARG)
233 |  |  |  |  |
234 |  |  |  |  | Check whether I<ARG> is a plain string
235 |  |  |  |  | satisfying Perl module name syntax as described for L</$module_name_rx>.
236 |  |  |  |  | Return normally if it is, or C<die> if it is not.
237 |  |  |  |  |
238 |  |  |  |  | =cut
239 |  |  |  |  |
240 |  |  |  |  | # spent 36µs (3+33) within Module::Runtime::check_module_name which was called: # once (3µs+33µs) by Module::Runtime::module_notional_filename at line 264 sub check_module_name($) {
241 | 1 | 3µs | 1 | 33µs | unless(&is_module_name) { # spent 33µs making 1 call to Module::Runtime::is_module_name
242 |  |  |  |  | die +(_is_string($_[0]) ? "`$_[0]'" : "argument").
243 |  |  |  |  | " is not a module name\n";
244 |  |  |  |  | }
245 |  |  |  |  | }
246 |  |  |  |  |
247 |  |  |  |  | =item module_notional_filename(NAME)
248 |  |  |  |  |
249 |  |  |  |  | Generates a notional relative filename for a module, which is used in
250 |  |  |  |  | some Perl core interfaces.
251 |  |  |  |  | The I<NAME> is a string, which should be a valid module name (one or
252 |  |  |  |  | more C<::>-separated segments). If it is not a valid name, the function
253 |  |  |  |  | C<die>s.
254 |  |  |  |  |
255 |  |  |  |  | The notional filename for the named module is generated and returned.
256 |  |  |  |  | This filename is always in Unix style, with C</> directory separators
257 |  |  |  |  | and a C<.pm> suffix. This kind of filename can be used as an argument to
258 |  |  |  |  | C<require>, and is the key that appears in C<%INC> to identify a module,
259 |  |  |  |  | regardless of actual local filename syntax.
260 |  |  |  |  |
261 |  |  |  |  | =cut
262 |  |  |  |  |
263 |  |  |  |  | # spent 46µs (8+38) within Module::Runtime::module_notional_filename which was called: # once (8µs+38µs) by Module::Runtime::require_module at line 317 sub module_notional_filename($) {
264 | 1 | 900ns | 1 | 36µs | &check_module_name; # spent 36µs making 1 call to Module::Runtime::check_module_name
265 | 1 | 400ns |  |  | my($name) = @_;
266 | 1 | 6µs | 1 | 2µs | $name =~ s!::!/!g; # spent 2µs making 1 call to Module::Runtime::CORE:subst
267 | 1 | 3µs |  |  | return $name.".pm";
268 |  |  |  |  | }
269 |  |  |  |  |
270 |  |  |  |  | =item require_module(NAME)
271 |  |  |  |  |
272 |  |  |  |  | This is essentially the bareword form of C<require>, in runtime form.
273 |  |  |  |  | The I<NAME> is a string, which should be a valid module name (one or
274 |  |  |  |  | more C<::>-separated segments). If it is not a valid name, the function
275 |  |  |  |  | C<die>s.
276 |  |  |  |  |
277 |  |  |  |  | The module specified by I<NAME> is loaded, if it hasn't been already,
278 |  |  |  |  | in the manner of the bareword form of C<require>. That means that a
279 |  |  |  |  | search through C<@INC> is performed, and a byte-compiled form of the
280 |  |  |  |  | module will be used if available.
281 |  |  |  |  |
282 |  |  |  |  | The return value is as for C<require>. That is, it is the value returned
283 |  |  |  |  | by the module itself if the module is loaded anew, or C<1> if the module
284 |  |  |  |  | was already loaded.
285 |  |  |  |  |
286 |  |  |  |  | =cut
287 |  |  |  |  |
288 |  |  |  |  | # Don't "use constant" here, to avoid dependencies.
289 |  |  |  |  | # spent 9µs within Module::Runtime::BEGIN@289 which was called: # once (9µs+0s) by Module::Implementation::BEGIN@8 at line 294 BEGIN {
290 |  |  |  |  | *_WORK_AROUND_HINT_LEAKAGE =
291 |  |  |  |  | "$]" < 5.011 && !("$]" >= 5.009004 && "$]" < 5.010001)
292 | 1 | 3µs |  |  | ? sub(){1} : sub(){0};
293 | 1 | 6µs |  |  | *_WORK_AROUND_BROKEN_MODULE_STATE = "$]" < 5.009 ? sub(){1} : sub(){0};
294 | 1 | 45µs | 1 | 9µs | } # spent 9µs making 1 call to Module::Runtime::BEGIN@289
295 |  |  |  |  |
296 | 1 | 4µs |  |  | # spent 4µs within Module::Runtime::BEGIN@296 which was called: # once (4µs+0s) by Module::Implementation::BEGIN@8 at line 301 BEGIN { if(_WORK_AROUND_BROKEN_MODULE_STATE) { eval q{
297 |  |  |  |  | sub Module::Runtime::__GUARD__::DESTROY {
298 |  |  |  |  | delete $INC{$_[0]->[0]} if @{$_[0]};
299 |  |  |  |  | }
300 |  |  |  |  | 1;
301 | 1 | 499µs | 1 | 4µs | }; die $@ if $@ ne ""; } } # spent 4µs making 1 call to Module::Runtime::BEGIN@296
302 |  |  |  |  |
303 |  |  |  |  | # spent 794µs (461+333) within Module::Runtime::require_module which was called: # once (461µs+333µs) by Module::Implementation::try {...} at line 93 of Module/Implementation.pm sub require_module($) {
304 |  |  |  |  | # Localise %^H to work around [perl #68590], where the bug exists
305 |  |  |  |  | # and this is a satisfactory workaround. The bug consists of
306 |  |  |  |  | # %^H state leaking into each required module, polluting the
307 |  |  |  |  | # module's lexical state.
308 |  |  |  |  | local %^H if _WORK_AROUND_HINT_LEAKAGE;
309 | 1 | 100ns |  |  | if(_WORK_AROUND_BROKEN_MODULE_STATE) {
310 |  |  |  |  | my $notional_filename = &module_notional_filename;
311 |  |  |  |  | my $guard = bless([ $notional_filename ],
312 |  |  |  |  | "Module::Runtime::__GUARD__");
313 |  |  |  |  | my $result = CORE::require($notional_filename);
314 |  |  |  |  | pop @$guard;
315 |  |  |  |  | return $result;
316 |  |  |  |  | } else {
317 | 1 | 170µs | 1 | 46µs | return scalar(CORE::require(&module_notional_filename)); # spent 46µs making 1 call to Module::Runtime::module_notional_filename
318 |  |  |  |  | }
319 |  |  |  |  | }
320 |  |  |  |  |
321 |  |  |  |  | =back
322 |  |  |  |  |
323 |  |  |  |  | =head2 Structured module use
324 |  |  |  |  |
325 |  |  |  |  | =over
326 |  |  |  |  |
327 |  |  |  |  | =item use_module(NAME[, VERSION])
328 |  |  |  |  |
329 |  |  |  |  | This is essentially C<use> in runtime form, but without the importing
330 |  |  |  |  | feature (which is fundamentally a compile-time thing). The I<NAME> is
331 |  |  |  |  | handled just like in C<require_module> above: it must be a module name,
332 |  |  |  |  | and the named module is loaded as if by the bareword form of C<require>.
333 |  |  |  |  |
334 |  |  |  |  | If a I<VERSION> is specified, the C<VERSION> method of the loaded module is
335 |  |  |  |  | called with the specified I<VERSION> as an argument. This normally serves to
336 |  |  |  |  | ensure that the version loaded is at least the version required. This is
337 |  |  |  |  | the same functionality provided by the I<VERSION> parameter of C<use>.
338 |  |  |  |  |
339 |  |  |  |  | On success, the name of the module is returned. This is unlike
340 |  |  |  |  | L</require_module>, and is done so that the entire call to L</use_module>
341 |  |  |  |  | can be used as a class name to call a constructor, as in the example in
342 |  |  |  |  | the synopsis.
343 |  |  |  |  |
344 |  |  |  |  | =cut
345 |  |  |  |  |
346 |  |  |  |  | sub use_module($;$) {
347 |  |  |  |  | my($name, $version) = @_;
348 |  |  |  |  | require_module($name);
349 |  |  |  |  | $name->VERSION($version) if @_ >= 2;
350 |  |  |  |  | return $name;
351 |  |  |  |  | }
352 |  |  |  |  |
353 |  |  |  |  | =item use_package_optimistically(NAME[, VERSION])
354 |  |  |  |  |
355 |  |  |  |  | This is an analogue of L</use_module> for the situation where there is
356 |  |  |  |  | uncertainty as to whether a package/class is defined in its own module
357 |  |  |  |  | or by some other means. It attempts to arrange for the named package to
358 |  |  |  |  | be available, either by loading a module or by doing nothing and hoping.
359 |  |  |  |  |
360 |  |  |  |  | An attempt is made to load the named module (as if by the bareword form
361 |  |  |  |  | of C<require>). If the module cannot be found then it is assumed that
362 |  |  |  |  | the package was actually already loaded by other means, and no error
363 |  |  |  |  | is signalled. That's the optimistic bit.
364 |  |  |  |  |
365 |  |  |  |  | This is mostly the same operation that is performed by the L<base> pragma
366 |  |  |  |  | to ensure that the specified base classes are available. The behaviour
367 |  |  |  |  | of L<base> was simplified in version 2.18, and later improved in version
368 |  |  |  |  | 2.20, and on both occasions this function changed to match.
369 |  |  |  |  |
370 |  |  |  |  | If a I<VERSION> is specified, the C<VERSION> method of the loaded package is
371 |  |  |  |  | called with the specified I<VERSION> as an argument. This normally serves
372 |  |  |  |  | to ensure that the version loaded is at least the version required.
373 |  |  |  |  | On success, the name of the package is returned. These aspects of the
374 |  |  |  |  | function work just like L</use_module>.
375 |  |  |  |  |
376 |  |  |  |  | =cut
377 |  |  |  |  |
378 |  |  |  |  | sub use_package_optimistically($;$) {
379 |  |  |  |  | my($name, $version) = @_;
380 |  |  |  |  | my $fn = module_notional_filename($name);
381 |  |  |  |  | eval { local $SIG{__DIE__}; require_module($name); };
382 |  |  |  |  | die $@ if $@ ne "" &&
383 |  |  |  |  | ($@ !~ /\ACan't locate \Q$fn\E .+ at \Q@{[__FILE__]}\E line/s ||
384 |  |  |  |  | $@ =~ /^Compilation\ failed\ in\ require
385 |  |  |  |  | \ at\ \Q@{[__FILE__]}\E\ line/xm);
386 |  |  |  |  | $name->VERSION($version) if @_ >= 2;
387 |  |  |  |  | return $name;
388 |  |  |  |  | }
389 |  |  |  |  |
390 |  |  |  |  | =back
391 |  |  |  |  |
392 |  |  |  |  | =head2 Module name composition
393 |  |  |  |  |
394 |  |  |  |  | =over
395 |  |  |  |  |
396 |  |  |  |  | =item is_module_spec(PREFIX, SPEC)
397 |  |  |  |  |
398 |  |  |  |  | Returns a truth value indicating
399 |  |  |  |  | whether I<SPEC> is valid input for L</compose_module_name>.
400 |  |  |  |  | See below for what that entails. Whether a I<PREFIX> is supplied affects
401 |  |  |  |  | the validity of I<SPEC>, but the exact value of the prefix is unimportant,
402 |  |  |  |  | so this function treats I<PREFIX> as a truth value.
403 |  |  |  |  |
404 |  |  |  |  | =cut
405 |  |  |  |  |
406 |  |  |  |  | sub is_module_spec($$) {
407 |  |  |  |  | my($prefix, $spec) = @_;
408 |  |  |  |  | return _is_string($spec) &&
409 |  |  |  |  | $spec =~ ($prefix ? qr/\A$sub_module_spec_rx\z/o :
410 |  |  |  |  | qr/\A$top_module_spec_rx\z/o);
411 |  |  |  |  | }
412 |  |  |  |  |
413 |  |  |  |  | =item is_valid_module_spec(PREFIX, SPEC)
414 |  |  |  |  |
415 |  |  |  |  | Deprecated alias for L</is_module_spec>.
416 |  |  |  |  |
417 |  |  |  |  | =cut
418 |  |  |  |  |
419 | 1 | 400ns |  |  | *is_valid_module_spec = \&is_module_spec;
420 |  |  |  |  |
421 |  |  |  |  | =item check_module_spec(PREFIX, SPEC)
422 |  |  |  |  |
423 |  |  |  |  | Check whether I<SPEC> is valid input for L</compose_module_name>.
424 |  |  |  |  | Return normally if it is, or C<die> if it is not.
425 |  |  |  |  |
426 |  |  |  |  | =cut
427 |  |  |  |  |
428 |  |  |  |  | sub check_module_spec($$) {
429 |  |  |  |  | unless(&is_module_spec) {
430 |  |  |  |  | die +(_is_string($_[1]) ? "`$_[1]'" : "argument").
431 |  |  |  |  | " is not a module specification\n";
432 |  |  |  |  | }
433 |  |  |  |  | }
434 |  |  |  |  |
435 |  |  |  |  | =item compose_module_name(PREFIX, SPEC)
436 |  |  |  |  |
437 |  |  |  |  | This function is intended to make it more convenient for a user to specify
438 |  |  |  |  | a Perl module name at runtime. Users have greater need for abbreviations
439 |  |  |  |  | and context-sensitivity than programmers, and Perl module names get a
440 |  |  |  |  | little unwieldy. I<SPEC> is what the user specifies, and this function
441 |  |  |  |  | translates it into a module name in standard form, which it returns.
442 |  |  |  |  |
443 |  |  |  |  | I<SPEC> has syntax approximately that of a standard module name: it
444 |  |  |  |  | should consist of one or more name segments, each of which consists
445 |  |  |  |  | of one or more identifier characters. However, C</> is permitted as a
446 |  |  |  |  | separator, in addition to the standard C<::>. The two separators are
447 |  |  |  |  | entirely interchangeable.
448 |  |  |  |  |
449 |  |  |  |  | Additionally, if I<PREFIX> is not C<undef> then it must be a module
450 |  |  |  |  | name in standard form, and it is prefixed to the user-specified name.
451 |  |  |  |  | The user can inhibit the prefix addition by starting I<SPEC> with a
452 |  |  |  |  | separator (either C</> or C<::>).
453 |  |  |  |  |
454 |  |  |  |  | =cut
455 |  |  |  |  |
456 |  |  |  |  | sub compose_module_name($$) {
457 |  |  |  |  | my($prefix, $spec) = @_;
458 |  |  |  |  | check_module_name($prefix) if defined $prefix;
459 |  |  |  |  | &check_module_spec;
460 |  |  |  |  | if($spec =~ s#\A(?:/|::)##) {
461 |  |  |  |  | # OK
462 |  |  |  |  | } else {
463 |  |  |  |  | $spec = $prefix."::".$spec if defined $prefix;
464 |  |  |  |  | }
465 |  |  |  |  | $spec =~ s#/#::#g;
466 |  |  |  |  | return $spec;
467 |  |  |  |  | }
468 |  |  |  |  |
469 |  |  |  |  | =back
470 |  |  |  |  |
471 |  |  |  |  | =head1 BUGS
472 |  |  |  |  |
473 |  |  |  |  | On Perl versions 5.7.2 to 5.8.8, if C<require> is overridden by the
474 |  |  |  |  | C<CORE::GLOBAL> mechanism, it is likely to break the heuristics used by
475 |  |  |  |  | L</use_package_optimistically>, making it signal an error for a missing
476 |  |  |  |  | module rather than assume that it was already loaded. From Perl 5.8.9
477 |  |  |  |  | onwards, and on 5.7.1 and earlier, this module can avoid being confused
478 |  |  |  |  | by such an override. On the affected versions, a C<require> override
479 |  |  |  |  | might be installed by L<Lexical::SealRequireHints>, if something requires
480 |  |  |  |  | its bugfix but for some reason its XS implementation isn't available.
481 |  |  |  |  |
482 |  |  |  |  | =head1 SEE ALSO
483 |  |  |  |  |
484 |  |  |  |  | L<Lexical::SealRequireHints>,
485 |  |  |  |  | L<base>,
486 |  |  |  |  | L<perlfunc/require>,
487 |  |  |  |  | L<perlfunc/use>
488 |  |  |  |  |
489 |  |  |  |  | =head1 AUTHOR
490 |  |  |  |  |
491 |  |  |  |  | Andrew Main (Zefram) <zefram@fysh.org>
492 |  |  |  |  |
493 |  |  |  |  | =head1 COPYRIGHT
494 |  |  |  |  |
495 |  |  |  |  | Copyright (C) 2004, 2006, 2007, 2009, 2010, 2011, 2012, 2014
496 |  |  |  |  | Andrew Main (Zefram) <zefram@fysh.org>
497 |  |  |  |  |
498 |  |  |  |  | =head1 LICENSE
499 |  |  |  |  |
500 |  |  |  |  | This module is free software; you can redistribute it and/or modify it
501 |  |  |  |  | under the same terms as Perl itself.
502 |  |  |  |  |
503 |  |  |  |  | =cut
504 |  |  |  |  |
505 | 1 | 14µs |  |  | 1;
|  |  |  |  | # spent 7µs within Module::Runtime::CORE:match which was called 4 times, avg 2µs/call: # 3 times (3µs+0s) by Module::Runtime::import at line 143, avg 933ns/call # once (4µs+0s) by Module::Runtime::is_module_name at line 222 sub Module::Runtime::CORE:match; # opcode
|  |  |  |  | # spent 5µs within Module::Runtime::CORE:qr which was called 6 times, avg 817ns/call: # once (2µs+0s) by Module::Implementation::BEGIN@8 at line 179 # once (800ns+0s) by Module::Implementation::BEGIN@8 at line 205 # once (700ns+0s) by Module::Implementation::BEGIN@8 at line 194 # once (600ns+0s) by Module::Implementation::BEGIN@8 at line 188 # once (600ns+0s) by Module::Implementation::BEGIN@8 at line 203 # once (500ns+0s) by Module::Implementation::BEGIN@8 at line 191 sub Module::Runtime::CORE:qr; # opcode
|  |  |  |  | # spent 82µs within Module::Runtime::CORE:regcomp which was called 3 times, avg 27µs/call: # once (36µs+0s) by Module::Implementation::BEGIN@8 at line 194 # once (29µs+0s) by Module::Implementation::BEGIN@8 at line 205 # once (17µs+0s) by Module::Runtime::is_module_name at line 222 sub Module::Runtime::CORE:regcomp; # opcode
|  |  |  |  | # spent 2µs within Module::Runtime::CORE:subst which was called: # once (2µs+0s) by Module::Runtime::module_notional_filename at line 266 sub Module::Runtime::CORE:subst; # opcode