1B::Hooks::AtRuntime(3pmU)ser Contributed Perl DocumentatiBo:n:Hooks::AtRuntime(3pm)
2
3
4

NAME

6       B::Hooks::AtRuntime - Lower blocks from compile time to runtime
7

SYNOPSIS

9           # My::Module
10           sub import {
11               at_runtime { warn "TWO" };
12           }
13
14           # elsewhere
15           warn "ONE";
16           use My::Module;
17           warn "THREE";
18

DESCRIPTION

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
27   at_runtime
28           at_runtime { ... };
29
30       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
37           BEGIN { warn "ONE" }    warn "one";
38           BEGIN { warn "TWO";     at_runtime { warn "two" }; }
39
40       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
43       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
47           # My::Module
48           sub also_at_runtime {
49               my ($msg) = @_;
50               at_runtime { warn $msg };
51           }
52
53           sub import {
54               my ($class, $one, $two) = @_;
55               at_runtime { warn $one };
56               also_at_runtime $two;
57           }
58
59           #
60           warn "one";
61           BEGIN { at_runtime { warn "two" } }
62           BEGIN { My::Module::also_at_runtime "three" }
63           use My::Module "four", "five";
64
65       will still put the warnings in order.
66
67   after_runtime
68           after_runtime { ... };
69
70       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
74           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
85       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
90       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
94   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
104   lex_stuff
105           lex_stuff $text;
106
107       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
112       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
118   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

CAVEATS

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
130   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
138       •   You cannot stuff text into a string "eval".
139
140           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
146       •   Stuffed text appears at the start of the next line.
147
148           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
155           "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
164       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

SEE ALSO

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
173       Hook::AfterRuntime uses it to implement something somewhat similar to
174       this module.
175
176       Scope::OnExit and B::Hooks::EndOfScope provide hooks into different
177       points in the surrounding scope.
178
179       Filter::Util::Call is the generic interface to the source filtering
180       mechanism.
181

AUTHOR

183       Ben Morrow <ben@morrow.me.uk>
184

BUGS

186       Please report any bugs to <bug-B-Hooks-AtRuntime@rt.cpan.org>.
187

ACKNOWLEDGEMENTS

189       Zefram's work on the core lexer API made this module enormously easier.
190
192       Copyright 2015 Ben Morrow.
193
194       Released under the 2-clause BSD licence.
195
196
197
198perl v5.38.0                      2023-07-20          B::Hooks::AtRuntime(3pm)
Impressum