1B::Hooks::AtRuntime(3pmU)ser Contributed Perl DocumentatiBo:n:Hooks::AtRuntime(3pm)
2
6 B::Hooks::AtRuntime - Lower blocks from compile time to runtime
7
9 # My::Module
10 sub import {
11 at_runtime { warn "TWO" };
12 }
13 # elsewhere
15 warn "ONE";
16 use My::Module;
17 warn "THREE";
18
20 This module allows code that runs at compile-time to do something at
21 runtime. A block passed to "at_runtime" gets compiled into the code
22 that's currently compiling, and will be called when control reaches
23 that point at runtime. In the example in the SYNOPSIS, the warnings
24 will occur in order, and if that section of code runs more than once,
25 so will all three warnings.
26 at_runtime
28 at_runtime { ... };
29 This sets up a block to be called at runtime. It must be called from
31 within a "BEGIN" block or "use", otherwise there will be no compiling
32 code to insert into. The innermost enclosing "BEGIN" block, which would
33 normally be invisible once the section of code it is in has been
34 compiled, will effectively leave behind a call to the given block. For
35 example, this
36 BEGIN { warn "ONE" } warn "one";
38 BEGIN { warn "TWO"; at_runtime { warn "two" }; }
39 will warn "ONE TWO one two", with the last warning 'lowered' out of the
41 "BEGIN" block and back into the runtime control flow.
42 This applies even if calls to other subs intervene between "BEGIN" and
44 "at_runtime". The lowered block is always inserted at the innermost
45 point where perl is still compiling, so something like this
46 # My::Module
48 sub also_at_runtime {
49 my ($msg) = @_;
50 at_runtime { warn $msg };
51 }
52 sub import {
54 my ($class, $one, $two) = @_;
55 at_runtime { warn $one };
56 also_at_runtime $two;
57 }
58 #
60 warn "one";
61 BEGIN { at_runtime { warn "two" } }
62 BEGIN { My::Module::also_at_runtime "three" }
63 use My::Module "four", "five";
64 will still put the warnings in order.
66 after_runtime
68 after_runtime { ... };
69 This arranges to call the block when runtime execution reaches the end
71 of the surrounding compiling scope. For example, this will warn in
72 order:
73 warn "one";
75 {
76 warn "two";
77 BEGIN {
78 after_runtime { warn "five" };
79 at_runtime { warn "three" };
80 }
81 warn "four";
82 }
83 warn "six";
84 No exception handling is done, so if the block throws an exception it
86 will propogate normally into the surrounding code. (This is different
87 from the way perl calls "DESTROY" methods, which have their exceptions
88 converted into warnings.)
89 Note that the block will be called during stack unwind, so the package,
91 file and line information for "caller 0" will be the point where the
92 surrounding scope was called. This is the same as a "DESTROY" method.
93 Object lifetimes
95 "at_runtime" and "after_runtime" are careful to make sure the anonymous
96 sub passed to them doesn't live any longer than it has to. That sub,
97 and any lexicals it has closed over, will be destroyed when the optree
98 it has been compiled into is destroyed: for code outside any sub, this
99 is when the containing file or eval finishes executing; for named subs,
100 this is when the sub is un- or redefined; and for anonymous subs, this
101 is not until both the code containing the "sub { }" expression and all
102 instances generated by that expression have been destroyed.
103 lex_stuff
105 lex_stuff $text;
106 This is the function underlying "at_runtime". Under perl 5.12 and
108 later, this is just a Perl wrapper for the core function lex_stuff_sv.
109 Under earlier versions it is implemented with a source filter, with
110 some limitations, see "CAVEATS" below.
111 This function pushes text into perl's line buffer, at the point perl is
113 currently compiling. You should probably not try to push too much at
114 once without giving perl a chance to compile it. If $text contains
115 newlines, they will affect perl's idea of the current line number. You
116 probably shouldn't use this function at all.
117 Exports
119 B::Hooks::AtRuntime uses Exporter::Tiny, so you can customise its
120 exports as described by that module's documentation. "at_runtime" is
121 exported by default; "after_runtime" and "lex_stuff" can be exported on
122 request.
123
125 Incompatible changes from version 1
126 Version 1 used a different implementation for "at_runtime", which left
127 an extra scope between the provided block and the code it was compiled
128 into. Version 2 has removed this.
129 Perls before 5.12
131 Versions of perl before 5.12.0 don't have the "lex_stuff_sv" function,
132 and don't export enough for it to be possible to emulate it entirely.
133 (B::Hooks::Parser gets as close as it can, and just exactly doesn't
134 quite do what we need for "at_runtime".) This means our "lex_stuff" has
135 to fall back to using a source filter to insert the text, which has a
136 couple of important limitations.
137 • You cannot stuff text into a string "eval".
139 String evals aren't affected by source filters, so the stuffed text
141 would end up getting inserted into the innermost compiling scope
142 that wasn't a string eval. Since this would be rather confusing,
143 and different from what 5.12 does, "lex_stuff" and "at_runtime"
144 will croak if you try to use them to affect a string eval.
145 • Stuffed text appears at the start of the next line.
147 This, unfortunately, is rather annoying. With a filter, the
149 earliest point at which we can insert text is the start of the next
150 line. This means that if there is any text between the closing
151 brace of the "BEGIN" block or the semicolon of the "use" that
152 caused the insertion, and the end of the line, the insertion will
153 certainly be in the wrong place and probably cause a syntax error.
154 "lex_stuff" (and, therefore, "at_runtime") will issue a warning if
156 this is going to happen (specifically, if there are any non-space
157 non-comment characters between the point where we want to insert
158 and the point we're forced to settle for), but this may not be
159 something you can entirely control. If you are writing a module
160 like the examples above which calls "at_runtime" from its "import"
161 method, what matters is that users of your module not put anything
162 on a line after your module's "use" statement.
163 If you want to use the filter implementation on perl 5.12 (for
165 testing), set "PERL_B_HOOKS_ATRUNTIME=filter" in the environment. If
166 the filter implementation is in use, "B::Hooks::AtRuntime::USE_FILTER"
167 will be true.
168
170 B::Hooks::Parser will insert text 'here' in perls before 5.12, but
171 requires a setup step at least one source line in advance.
172 Hook::AfterRuntime uses it to implement something somewhat similar to
174 this module.
175 Scope::OnExit and B::Hooks::EndOfScope provide hooks into different
177 points in the surrounding scope.
178 Filter::Util::Call is the generic interface to the source filtering
180 mechanism.
181
183 Ben Morrow <ben@morrow.me.uk>
184
186 Please report any bugs to <bug-B-Hooks-AtRuntime@rt.cpan.org>.
187
189 Zefram's work on the core lexer API made this module enormously easier.
190
192 Copyright 2015 Ben Morrow.
193 Released under the 2-clause BSD licence.
195perl v5.38.0 2023-07-20 B::Hooks::AtRuntime(3pm)