| 1 | package B::Hooks::AtRuntime; | ||||||||||
| 2 | |||||||||||
| 3 | 7 | ▶ | use warnings; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 4 | 7 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 5 | |||||||||||
| 6 | 7 | ▶ | use XSLoader; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 7 | 7 | ▶ | use Sub::Name "subname"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 8 | 7 | ▶ | use Carp; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 9 | |||||||||||
| 10 | 7 | ▶ | use parent "Exporter::Tiny"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 11 | 7 | our @EXPORT = qw/at_runtime/; | |||||||||
| 12 | 7 | our @EXPORT_OK = qw/at_runtime after_runtime lex_stuff/; | |||||||||
| 13 | |||||||||||
| 14 | BEGIN { | ||||||||||
| 15 | 7 | ▶ | our $VERSION = "6"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 16 | 7 | XSLoader::load __PACKAGE__, $VERSION; | |||||||||
| 17 | } | ||||||||||
| 18 | |||||||||||
| 19 | use constant USE_FILTER => | ||||||||||
| 20 | defined $ENV{PERL_B_HOOKS_ATRUNTIME} | ||||||||||
| 21 | 7 | ▶ | ? $ENV{PERL_B_HOOKS_ATRUNTIME} eq "filter" | ||||||||
|
Branch: 1 branch
| |||||||||||
| 22 | 7 | ▶ | : not defined &lex_stuff; | ||||||||
|
Subroutine
BEGIN: called CC=2 SCAR=6.9
| |||||||||||
| 23 | |||||||||||
| 24 | 7 | if (USE_FILTER) { | |||||||||
| 25 | require Filter::Util::Call; | ||||||||||
| 26 | |||||||||||
| 27 | # This isn't an exact replacement: it inserts the text at the start | ||||||||||
| 28 | # of the next line, rather than immediately after the current BEGIN. | ||||||||||
| 29 | # | ||||||||||
| 30 | # In theory I could use B::Hooks::Parser, which aims to emulate | ||||||||||
| 31 | # lex_stuff on older perls, but that uses a source filter to ensure | ||||||||||
| 32 | # PL_linebuf has some extra space in it (since it can't be | ||||||||||
| 33 | # reallocated without adjusting pointers we can't get to). This | ||||||||||
| 34 | # means BHP::setup needs to be called at least one source line | ||||||||||
| 35 | # before we want to insert any text (so the filter has a chance to | ||||||||||
| 36 | # run), which makes it precisely useless for our purposes :(. | ||||||||||
| 37 | |||||||||||
| 38 | 7 | ▶ | no warnings "redefine"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 39 | *lex_stuff = subname "lex_stuff", sub { | ||||||||||
| 40 | 55 | ▶ | my ($str) = @_; | ||||||||
|
Subroutine
__ANON__: called CC=3 SCAR=11.0
| |||||||||||
| 41 | |||||||||||
| 42 | 55 | ▶ | compiling_string_eval() and croak | ||||||||
|
Branch: 1 branch
| |||||||||||
| 43 | "Can't stuff into a string eval"; | ||||||||||
| 44 | |||||||||||
| 45 | 55 | ▶ | if (defined(my $extra = remaining_text())) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 46 | 1 | $extra =~ s/\n+\z//; | |||||||||
| 47 | 1 | carp "Extra text '$extra' after call to lex_stuff"; | |||||||||
| 48 | } | ||||||||||
| 49 | |||||||||||
| 50 | Filter::Util::Call::filter_add(sub { | ||||||||||
| 51 | 55 | ▶ | $_ = $str; | ||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||
| 52 | 55 | Filter::Util::Call::filter_del(); | |||||||||
| 53 | 55 | return 1; | |||||||||
| 54 | 55 | }); | |||||||||
| 55 | }; | ||||||||||
| 56 | } | ||||||||||
| 57 | |||||||||||
| 58 | 7 | my @Hooks; | |||||||||
| 59 | |||||||||||
| 60 | sub replace_hooks { | ||||||||||
| 61 | 196 | ▶ | my ($new) = @_; | ||||||||
|
Subroutine
replace_hooks: called CC=2 SCAR=6.9
Pod
undocumented
| |||||||||||
| 62 | |||||||||||
| 63 | # By deleting the stash entry we ensure the only ref to the glob is | ||||||||||
| 64 | # through the optree it was compiled into. This means that if that | ||||||||||
| 65 | # optree is ever freed, the glob will disappear along with anything | ||||||||||
| 66 | # closed over by the user's callbacks. | ||||||||||
| 67 | 196 | delete $B::Hooks::AtRuntime::{hooks}; | |||||||||
| 68 | |||||||||||
| 69 | 7 | ▶ | no strict "refs"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 70 | 196 | ▶ | $new and *{"hooks"} = $new; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 71 | } | ||||||||||
| 72 | |||||||||||
| 73 | sub clear { | ||||||||||
| 74 | 98 | ▶ | my ($depth) = @_; | ||||||||
|
Subroutine
clear: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||
| 75 | 98 | $Hooks[$depth] = undef; | |||||||||
| 76 | 98 | replace_hooks $Hooks[$depth - 1]; | |||||||||
| 77 | } | ||||||||||
| 78 | |||||||||||
| 79 | sub find_hooks { | ||||||||||
| 80 | 118 | ▶ | USE_FILTER and compiling_string_eval() and croak | ||||||||
|
Subroutine
find_hooks: called CC=3 SCAR=11.0
Pod
undocumented
| |||||||||||
| 81 | "Can't use at_runtime from a string eval"; | ||||||||||
| 82 | |||||||||||
| 83 | 116 | ▶ | my $depth = count_BEGINs() | ||||||||
|
Branch: 1 branch
| |||||||||||
| 84 | or croak "You must call at_runtime at compile time"; | ||||||||||
| 85 | |||||||||||
| 86 | 114 | my $hk; | |||||||||
| 87 | 114 | ▶ | unless ($hk = $Hooks[$depth]) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 88 | # Close over an array of callbacks so we don't need to keep | ||||||||||
| 89 | # stuffing text into the buffer. | ||||||||||
| 90 | 98 | my @hooks; | |||||||||
| 91 | 98 | $hk = $Hooks[$depth] = \@hooks; | |||||||||
| 92 | 98 | replace_hooks $hk; | |||||||||
| 93 | |||||||||||
| 94 | # This must be all on one line, so we don't mess up perl's idea | ||||||||||
| 95 | # of the current line number. | ||||||||||
| 96 | 98 | lex_stuff(q{B::Hooks::AtRuntime::run(@B::Hooks::AtRuntime::hooks);} . | |||||||||
| 97 | "BEGIN{B::Hooks::AtRuntime::clear($depth)}"); | ||||||||||
| 98 | } | ||||||||||
| 99 | |||||||||||
| 100 | 114 | return $hk; | |||||||||
| 101 | } | ||||||||||
| 102 | |||||||||||
| 103 | sub at_runtime (&) { | ||||||||||
| 104 | 109 | ▶ | my ($cv) = @_; | ||||||||
|
Subroutine
at_runtime: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 105 | 109 | my $hk = find_hooks; | |||||||||
| 106 | 105 | push @$hk, subname scalar(caller) . "::(at_runtime)", $cv; | |||||||||
| 107 | } | ||||||||||
| 108 | |||||||||||
| 109 | sub after_runtime (&) { | ||||||||||
| 110 | 9 | ▶ | my ($cv) = @_; | ||||||||
|
Subroutine
after_runtime: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 111 | 9 | my $hk = find_hooks; | |||||||||
| 112 | 9 | push @$hk, \subname scalar(caller) . "::(after_runtime)", $cv; | |||||||||
| 113 | } | ||||||||||
| 114 | |||||||||||
| 115 | 7 | 1; | |||||||||
| 116 | |||||||||||
| 117 | =head1 NAME | ||||||||||
| 118 | |||||||||||
| 119 | B::Hooks::AtRuntime - Lower blocks from compile time to runtime | ||||||||||
| 120 | |||||||||||
| 121 | =head1 SYNOPSIS | ||||||||||
| 122 | |||||||||||
| 123 | # My::Module | ||||||||||
| 124 | sub import { | ||||||||||
| 125 | at_runtime { warn "TWO" }; | ||||||||||
| 126 | } | ||||||||||
| 127 | |||||||||||
| 128 | # elsewhere | ||||||||||
| 129 | warn "ONE"; | ||||||||||
| 130 | use My::Module; | ||||||||||
| 131 | warn "THREE"; | ||||||||||
| 132 | |||||||||||
| 133 | =head1 DESCRIPTION | ||||||||||
| 134 | |||||||||||
| 135 | This module allows code that runs at compile-time to do something at | ||||||||||
| 136 | runtime. A block passed to C<at_runtime> gets compiled into the code | ||||||||||
| 137 | that's currently compiling, and will be called when control reaches that | ||||||||||
| 138 | point at runtime. In the example in the SYNOPSIS, the warnings will | ||||||||||
| 139 | occur in order, and if that section of code runs more than once, so will | ||||||||||
| 140 | all three warnings. | ||||||||||
| 141 | |||||||||||
| 142 | =head2 at_runtime | ||||||||||
| 143 | |||||||||||
| 144 | at_runtime { ... }; | ||||||||||
| 145 | |||||||||||
| 146 | This sets up a block to be called at runtime. It must be called from | ||||||||||
| 147 | within a C<BEGIN> block or C<use>, otherwise there will be no compiling | ||||||||||
| 148 | code to insert into. The innermost enclosing C<BEGIN> block, which would | ||||||||||
| 149 | normally be invisible once the section of code it is in has been | ||||||||||
| 150 | compiled, will effectively leave behind a call to the given block. For | ||||||||||
| 151 | example, this | ||||||||||
| 152 | |||||||||||
| 153 | BEGIN { warn "ONE" } warn "one"; | ||||||||||
| 154 | BEGIN { warn "TWO"; at_runtime { warn "two" }; } | ||||||||||
| 155 | |||||||||||
| 156 | will warn "ONE TWO one two", with the last warning 'lowered' out of the | ||||||||||
| 157 | C<BEGIN> block and back into the runtime control flow. | ||||||||||
| 158 | |||||||||||
| 159 | This applies even if calls to other subs intervene between C<BEGIN> and | ||||||||||
| 160 | C<at_runtime>. The lowered block is always inserted at the innermost | ||||||||||
| 161 | point where perl is still compiling, so something like this | ||||||||||
| 162 | |||||||||||
| 163 | # My::Module | ||||||||||
| 164 | sub also_at_runtime { | ||||||||||
| 165 | my ($msg) = @_; | ||||||||||
| 166 | at_runtime { warn $msg }; | ||||||||||
| 167 | } | ||||||||||
| 168 | |||||||||||
| 169 | sub import { | ||||||||||
| 170 | my ($class, $one, $two) = @_; | ||||||||||
| 171 | at_runtime { warn $one }; | ||||||||||
| 172 | also_at_runtime $two; | ||||||||||
| 173 | } | ||||||||||
| 174 | |||||||||||
| 175 | # | ||||||||||
| 176 | warn "one"; | ||||||||||
| 177 | BEGIN { at_runtime { warn "two" } } | ||||||||||
| 178 | BEGIN { My::Module::also_at_runtime "three" } | ||||||||||
| 179 | use My::Module "four", "five"; | ||||||||||
| 180 | |||||||||||
| 181 | will still put the warnings in order. | ||||||||||
| 182 | |||||||||||
| 183 | =head2 after_runtime | ||||||||||
| 184 | |||||||||||
| 185 | after_runtime { ... }; | ||||||||||
| 186 | |||||||||||
| 187 | This arranges to call the block when runtime execution reaches the end | ||||||||||
| 188 | of the surrounding compiling scope. For example, this will warn in order: | ||||||||||
| 189 | |||||||||||
| 190 | warn "one"; | ||||||||||
| 191 | { | ||||||||||
| 192 | warn "two"; | ||||||||||
| 193 | BEGIN { | ||||||||||
| 194 | after_runtime { warn "five" }; | ||||||||||
| 195 | at_runtime { warn "three" }; | ||||||||||
| 196 | } | ||||||||||
| 197 | warn "four"; | ||||||||||
| 198 | } | ||||||||||
| 199 | warn "six"; | ||||||||||
| 200 | |||||||||||
| 201 | No exception handling is done, so if the block throws an exception it | ||||||||||
| 202 | will propogate normally into the surrounding code. (This is different | ||||||||||
| 203 | from the way perl calls C<DESTROY> methods, which have their exceptions | ||||||||||
| 204 | converted into warnings.) | ||||||||||
| 205 | |||||||||||
| 206 | Note that the block will be called during stack unwind, so the package, | ||||||||||
| 207 | file and line information for C<caller 0> will be the point where the | ||||||||||
| 208 | surrounding scope was called. This is the same as a C<DESTROY> method. | ||||||||||
| 209 | |||||||||||
| 210 | =head2 Object lifetimes | ||||||||||
| 211 | |||||||||||
| 212 | C<at_runtime> and C<after_runtime> are careful to make sure the | ||||||||||
| 213 | anonymous sub passed to them doesn't live any longer than it has to. | ||||||||||
| 214 | That sub, and any lexicals it has closed over, will be destroyed when | ||||||||||
| 215 | the optree it has been compiled into is destroyed: for code outside any | ||||||||||
| 216 | sub, this is when the containing file or eval finishes executing; for | ||||||||||
| 217 | named subs, this is when the sub is un- or redefined; and for anonymous | ||||||||||
| 218 | subs, this is not until both the code containing the C<sub { }> | ||||||||||
| 219 | expression and all instances generated by that expression have been | ||||||||||
| 220 | destroyed. | ||||||||||
| 221 | |||||||||||
| 222 | =head2 lex_stuff | ||||||||||
| 223 | |||||||||||
| 224 | lex_stuff $text; | ||||||||||
| 225 | |||||||||||
| 226 | This is the function underlying C<at_runtime>. Under perl 5.12 and | ||||||||||
| 227 | later, this is just a Perl wrapper for the core function | ||||||||||
| 228 | L<lex_stuff_sv|perlapi/lex_stuff_sv>. Under earlier versions it is | ||||||||||
| 229 | implemented with a source filter, with some limitations, see L</CAVEATS> | ||||||||||
| 230 | below. | ||||||||||
| 231 | |||||||||||
| 232 | This function pushes text into perl's line buffer, at the point perl is | ||||||||||
| 233 | currently compiling. You should probably not try to push too much at | ||||||||||
| 234 | once without giving perl a chance to compile it. If C<$text> contains | ||||||||||
| 235 | newlines, they will affect perl's idea of the current line number. You | ||||||||||
| 236 | probably shouldn't use this function at all. | ||||||||||
| 237 | |||||||||||
| 238 | =head2 Exports | ||||||||||
| 239 | |||||||||||
| 240 | B::Hooks::AtRuntime uses L<Exporter::Tiny>, so you can customise its | ||||||||||
| 241 | exports as described by that module's documentation. C<at_runtime> is | ||||||||||
| 242 | exported by default; C<after_runtime> and C<lex_stuff> can be exported | ||||||||||
| 243 | on request. | ||||||||||
| 244 | |||||||||||
| 245 | =head1 CAVEATS | ||||||||||
| 246 | |||||||||||
| 247 | =head2 Incompatible changes from version 1 | ||||||||||
| 248 | |||||||||||
| 249 | Version 1 used a different implementation for C<at_runtime>, which left | ||||||||||
| 250 | an extra scope between the provided block and the code it was compiled | ||||||||||
| 251 | into. Version 2 has removed this. | ||||||||||
| 252 | |||||||||||
| 253 | =head2 Perls before 5.12 | ||||||||||
| 254 | |||||||||||
| 255 | Versions of perl before 5.12.0 don't have the C<lex_stuff_sv> function, | ||||||||||
| 256 | and don't export enough for it to be possible to emulate it entirely. | ||||||||||
| 257 | (L<B::Hooks::Parser> gets as close as it can, and just exactly doesn't | ||||||||||
| 258 | quite do what we need for C<at_runtime>.) This means our C<lex_stuff> | ||||||||||
| 259 | has to fall back to using a source filter to insert the text, which has | ||||||||||
| 260 | a couple of important limitations. | ||||||||||
| 261 | |||||||||||
| 262 | =over 4 | ||||||||||
| 263 | |||||||||||
| 264 | =item * You cannot stuff text into a string C<eval>. | ||||||||||
| 265 | |||||||||||
| 266 | String evals aren't affected by source filters, so the stuffed text | ||||||||||
| 267 | would end up getting inserted into the innermost compiling scope that | ||||||||||
| 268 | B<wasn't> a string eval. Since this would be rather confusing, and | ||||||||||
| 269 | different from what 5.12 does, C<lex_stuff> and C<at_runtime> will croak | ||||||||||
| 270 | if you try to use them to affect a string eval. | ||||||||||
| 271 | |||||||||||
| 272 | =item * Stuffed text appears at the start of the next line. | ||||||||||
| 273 | |||||||||||
| 274 | This, unfortunately, is rather annoying. With a filter, the earliest | ||||||||||
| 275 | point at which we can insert text is the start of the next line. This | ||||||||||
| 276 | means that if there is any text between the closing brace of the | ||||||||||
| 277 | C<BEGIN> block or the semicolon of the C<use> that caused the insertion, | ||||||||||
| 278 | and the end of the line, the insertion will certainly be in the wrong | ||||||||||
| 279 | place and probably cause a syntax error. | ||||||||||
| 280 | |||||||||||
| 281 | C<lex_stuff> (and, therefore, C<at_runtime>) will issue a warning if | ||||||||||
| 282 | this is going to happen (specifically, if there are any non-space | ||||||||||
| 283 | non-comment characters between the point where we want to insert and the | ||||||||||
| 284 | point we're forced to settle for), but this may not be something you can | ||||||||||
| 285 | entirely control. If you are writing a module like the examples above | ||||||||||
| 286 | which calls C<at_runtime> from its C<import> method, what matters is | ||||||||||
| 287 | that B<users of your module> not put anything on a line after your | ||||||||||
| 288 | module's C<use> statement. | ||||||||||
| 289 | |||||||||||
| 290 | =back | ||||||||||
| 291 | |||||||||||
| 292 | If you want to use the filter implementation on perl 5.12 (for testing), | ||||||||||
| 293 | set C<PERL_B_HOOKS_ATRUNTIME=filter> in the environment. If the filter | ||||||||||
| 294 | implementation is in use, C<B::Hooks::AtRuntime::USE_FILTER> will be | ||||||||||
| 295 | true. | ||||||||||
| 296 | |||||||||||
| 297 | =head1 SEE ALSO | ||||||||||
| 298 | |||||||||||
| 299 | L<B::Hooks::Parser> will insert text 'here' in perls before 5.12, but | ||||||||||
| 300 | requires a setup step at least one source line in advance. | ||||||||||
| 301 | |||||||||||
| 302 | L<Hook::AfterRuntime> uses it to implement something somewhat similar to | ||||||||||
| 303 | this module. | ||||||||||
| 304 | |||||||||||
| 305 | L<Scope::OnExit> and L<B::Hooks::EndOfScope> provide hooks into | ||||||||||
| 306 | different points in the surrounding scope. | ||||||||||
| 307 | |||||||||||
| 308 | L<Filter::Util::Call> is the generic interface to the source filtering | ||||||||||
| 309 | mechanism. | ||||||||||
| 310 | |||||||||||
| 311 | =head1 AUTHOR | ||||||||||
| 312 | |||||||||||
| 313 | Ben Morrow <ben@morrow.me.uk> | ||||||||||
| 314 | |||||||||||
| 315 | =head1 BUGS | ||||||||||
| 316 | |||||||||||
| 317 | Please report any bugs to <bug-B-Hooks-AtRuntime@rt.cpan.org>. | ||||||||||
| 318 | |||||||||||
| 319 | =head1 ACKNOWLEDGEMENTS | ||||||||||
| 320 | |||||||||||
| 321 | Zefram's work on the core lexer API made this module enormously easier. | ||||||||||
| 322 | |||||||||||
| 323 | =head1 COPYRIGHT | ||||||||||
| 324 | |||||||||||
| 325 | Copyright 2015 Ben Morrow. | ||||||||||
| 326 | |||||||||||
| 327 | Released under the 2-clause BSD licence. | ||||||||||
| 328 | |||||||||||
| 329 | =cut | ||||||||||