blib/lib/Scope/Upper.pm

filter: Statementstmt 100% 21 / 21 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 6 / 6 Podpod n/a totaltotal 100% 27 / 27 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« xsh/threads.h ↑ Summary
1 package Scope::Upper;
2  
3 49 ▶use 5.006_001;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 49 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 49 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 =head1 NAME
9  
10 Scope::Upper - Act on upper scopes.
11  
12 =head1 VERSION
13  
14 Version 0.35
15  
16 =cut
17  
18 49 our $VERSION;
19 49 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
20 49 $VERSION = '0.35';
21 }
22  
23 =head1 SYNOPSIS
24  
25 L</reap>, L</localize>, L</localize_elem>, L</localize_delete> and L</WORDS> :
26  
27 package Scope;
28  
29 use Scope::Upper qw<
30 reap localize localize_elem localize_delete
31 :words
32 >;
33  
34 sub new {
35 my ($class, $name) = @_;
36  
37 localize '$tag' => bless({ name => $name }, $class) => UP;
38  
39 reap { print Scope->tag->name, ": end\n" } UP;
40 }
41  
42 # Get the tag stored in the caller namespace
43 sub tag {
44 my $l = 0;
45 my $pkg = __PACKAGE__;
46 $pkg = caller $l++ while $pkg eq __PACKAGE__;
47  
48 no strict 'refs';
49 ${$pkg . '::tag'};
50 }
51  
52 sub name { shift->{name} }
53  
54 # Locally capture warnings and reprint them with the name prefixed
55 sub catch {
56 localize_elem '%SIG', '__WARN__' => sub {
57 print Scope->tag->name, ': ', @_;
58 } => UP;
59 }
60  
61 # Locally clear @INC
62 sub private {
63 for (reverse 0 .. $#INC) {
64 # First UP is the for loop, second is the sub boundary
65 localize_delete '@INC', $_ => UP UP;
66 }
67 }
68  
69 ...
70  
71 package UserLand;
72  
73 {
74 Scope->new("top"); # initializes $UserLand::tag
75  
76 {
77 Scope->catch;
78 my $one = 1 + undef; # prints "top: Use of uninitialized value..."
79  
80 {
81 Scope->private;
82 eval { require Cwd };
83 print $@; # prints "Can't locate Cwd.pm in @INC
84 } # (@INC contains:) at..."
85  
86 require Cwd; # loads Cwd.pm
87 }
88  
89 } # prints "top: done"
90  
91 L</unwind> and L</want_at> :
92  
93 package Try;
94  
95 use Scope::Upper qw<unwind want_at :words>;
96  
97 sub try (&) {
98 my @result = shift->();
99 my $cx = SUB UP; # Point to the sub above this one
100 unwind +(want_at($cx) ? @result : scalar @result) => $cx;
101 }
102  
103 ...
104  
105 sub zap {
106 try {
107 my @things = qw<a b c>;
108 return @things; # returns to try() and then outside zap()
109 # not reached
110 };
111 # not reached
112 }
113  
114 my @stuff = zap(); # @stuff contains qw<a b c>
115 my $stuff = zap(); # $stuff contains 3
116  
117 L</uplevel> :
118  
119 package Uplevel;
120  
121 use Scope::Upper qw<uplevel CALLER>;
122  
123 sub target {
124 faker(@_);
125 }
126  
127 sub faker {
128 uplevel {
129 my $sub = (caller 0)[3];
130 print "$_[0] from $sub()";
131 } @_ => CALLER(1);
132 }
133  
134 target('hello'); # "hello from Uplevel::target()"
135  
136 L</uid> and L</validate_uid> :
137  
138 use Scope::Upper qw<uid validate_uid>;
139  
140 my $uid;
141  
142 {
143 $uid = uid();
144 {
145 if ($uid eq uid(UP)) { # yes
146 ...
147 }
148 if (validate_uid($uid)) { # yes
149 ...
150 }
151 }
152 }
153  
154 if (validate_uid($uid)) { # no
155 ...
156 }
157  
158 =head1 DESCRIPTION
159  
160 This module lets you defer actions I<at run-time> that will take place when the control flow returns into an upper scope.
161 Currently, you can:
162  
163 =over 4
164  
165 =item *
166  
167 hook an upper scope end with L</reap> ;
168  
169 =item *
170  
171 localize variables, array/hash values or deletions of elements in higher contexts with respectively L</localize>, L</localize_elem> and L</localize_delete> ;
172  
173 =item *
174  
175 return values immediately to an upper level with L</unwind>, L</yield> and L</leave> ;
176  
177 =item *
178  
179 gather information about an upper context with L</want_at> and L</context_info> ;
180  
181 =item *
182  
183 execute a subroutine in the setting of an upper subroutine stack frame with L</uplevel> ;
184  
185 =item *
186  
187 uniquely identify contexts with L</uid> and L</validate_uid>.
188  
189 =back
190  
191 =head1 FUNCTIONS
192  
193 In all those functions, C<$context> refers to the target scope.
194  
195 You have to use one or a combination of L</WORDS> to build the C<$context> passed to these functions.
196 This is needed in order to ensure that the module still works when your program is ran in the debugger.
197 The only thing you can assume is that it is an I<absolute> indicator of the frame, which means that you can safely store it at some point and use it when needed, and it will still denote the original scope.
198  
199 =cut
200  
201 49 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
202 49 require XSLoader;
203 49 XSLoader::load(__PACKAGE__, $VERSION);
204 }
205  
206 =head2 C<reap>
207  
208 reap { ... };
209 reap { ... } $context;
210 &reap($callback, $context);
211  
212 Adds a destructor that calls C<$callback> (in void context) when the upper scope represented by C<$context> ends.
213  
214 =head2 C<localize>
215  
216 localize $what, $value;
217 localize $what, $value, $context;
218  
219 Introduces a C<local> delayed to the time of first return into the upper scope denoted by C<$context>.
220 C<$what> can be :
221  
222 =over 4
223  
224 =item *
225  
226 A glob, in which case C<$value> can either be a glob or a reference.
227 L</localize> follows then the same syntax as C<local *x = $value>.
228 For example, if C<$value> is a scalar reference, then the C<SCALAR> slot of the glob will be set to C<$$value> - just like C<local *x = \1> sets C<$x> to C<1>.
229  
230 =item *
231  
232 A string beginning with a sigil, representing the symbol to localize and to assign to.
233 If the sigil is C<'$'>, L</localize> follows the same syntax as C<local $x = $value>, i.e. C<$value> isn't dereferenced.
234 For example,
235  
236 localize '$x', \'foo' => HERE;
237  
238 will set C<$x> to a reference to the string C<'foo'>.
239 Other sigils (C<'@'>, C<'%'>, C<'&'> and C<'*'>) require C<$value> to be a reference of the corresponding type.
240  
241 When the symbol is given by a string, it is resolved when the actual localization takes place and not when L</localize> is called.
242 Thus, if the symbol name is not qualified, it will refer to the variable in the package where the localization actually takes place and not in the one where the L</localize> call was compiled.
243 For example,
244  
245 {
246 package Scope;
247 sub new { localize '$tag', $_[0] => UP }
248 }
249  
250 {
251 package Tool;
252 {
253 Scope->new;
254 ...
255 }
256 }
257  
258 will localize C<$Tool::tag> and not C<$Scope::tag>.
259 If you want the other behaviour, you just have to specify C<$what> as a glob or a qualified name.
260  
261 Note that if C<$what> is a string denoting a variable that wasn't declared beforehand, the relevant slot will be vivified as needed and won't be deleted from the glob when the localization ends.
262 This situation never arises with C<local> because it only compiles when the localized variable is already declared.
263 Although I believe it shouldn't be a problem as glob slots definedness is pretty much an implementation detail, this behaviour may change in the future if proved harmful.
264  
265 =back
266  
267 =head2 C<localize_elem>
268  
269 localize_elem $what, $key, $value;
270 localize_elem $what, $key, $value, $context;
271  
272 Introduces a C<local $what[$key] = $value> or C<local $what{$key} = $value> delayed to the time of first return into the upper scope denoted by C<$context>.
273 Unlike L</localize>, C<$what> must be a string and the type of localization is inferred from its sigil.
274 The two only valid types are array and hash ; for anything besides those, L</localize_elem> will throw an exception.
275 C<$key> is either an array index or a hash key, depending of which kind of variable you localize.
276  
277 If C<$what> is a string pointing to an undeclared variable, the variable will be vivified as soon as the localization occurs and emptied when it ends, although it will still exist in its glob.
278  
279 =head2 C<localize_delete>
280  
281 localize_delete $what, $key;
282 localize_delete $what, $key, $context;
283  
284 Introduces the deletion of a variable or an array/hash element delayed to the time of first return into the upper scope denoted by C<$context>.
285 C<$what> can be:
286  
287 =over 4
288  
289 =item *
290  
291 A glob, in which case C<$key> is ignored and the call is equivalent to C<local *x>.
292  
293 =item *
294  
295 A string beginning with C<'@'> or C<'%'>, for which the call is equivalent to respectively C<local $a[$key]; delete $a[$key]> and C<local $h{$key}; delete $h{$key}>.
296  
297 =item *
298  
299 A string beginning with C<'&'>, which more or less does C<undef &func> in the upper scope.
300 It's actually more powerful, as C<&func> won't even C<exists> anymore.
301 C<$key> is ignored.
302  
303 =back
304  
305 =head2 C<unwind>
306  
307 unwind;
308 unwind @values, $context;
309  
310 Returns C<@values> I<from> the subroutine, eval or format context pointed by or just above C<$context>, and immediately restarts the program flow at this point - thus effectively returning C<@values> to an upper scope.
311 If C<@values> is empty, then the C<$context> parameter is optional and defaults to the current context (making the call equivalent to a bare C<return;>) ; otherwise it is mandatory.
312  
313 The upper context isn't coerced onto C<@values>, which is hence always evaluated in list context.
314 This means that
315  
316 my $num = sub {
317 my @a = ('a' .. 'z');
318 unwind @a => HERE;
319 # not reached
320 }->();
321  
322 will set C<$num> to C<'z'>.
323 You can use L</want_at> to handle these cases.
324  
325 =head2 C<yield>
326  
327 yield;
328 yield @values, $context;
329  
330 Returns C<@values> I<from> the context pointed by or just above C<$context>, and immediately restarts the program flow at this point.
331 If C<@values> is empty, then the C<$context> parameter is optional and defaults to the current context ; otherwise it is mandatory.
332  
333 L</yield> differs from L</unwind> in that it can target I<any> upper scope (besides a C<s///e> substitution context) and not necessarily a sub, an eval or a format.
334 Hence you can use it to return values from a C<do> or a C<map> block :
335  
336 my $now = do {
337 local $@;
338 eval { require Time::HiRes } or yield time() => HERE;
339 Time::HiRes::time();
340 };
341  
342 my @uniq = map {
343 yield if $seen{$_}++; # returns the empty list from the block
344 ...
345 } @things;
346  
347 Like for L</unwind>, the upper context isn't coerced onto C<@values>.
348 You can use the fifth value returned by L</context_info> to handle context coercion.
349  
350 =head2 C<leave>
351  
352 leave;
353 leave @values;
354  
355 Immediately returns C<@values> from the current block, whatever it may be (besides a C<s///e> substitution context).
356 C<leave> is actually a synonym for C<yield HERE>, while C<leave @values> is a synonym for C<yield @values, HERE>.
357  
358 Like for L</yield>, you can use the fifth value returned by L</context_info> to handle context coercion.
359  
360 =head2 C<want_at>
361  
362 my $want = want_at;
363 my $want = want_at $context;
364  
365 Like L<perlfunc/wantarray>, but for the subroutine, eval or format context located at or just above C<$context>.
366  
367 It can be used to revise the example showed in L</unwind> :
368  
369 my $num = sub {
370 my @a = ('a' .. 'z');
371 unwind +(want_at(HERE) ? @a : scalar @a) => HERE;
372 # not reached
373 }->();
374  
375 will rightfully set C<$num> to C<26>.
376  
377 =head2 C<context_info>
378  
379 my ($package, $filename, $line, $subroutine, $hasargs,
380 $wantarray, $evaltext, $is_require, $hints, $bitmask,
381 $hinthash) = context_info $context;
382  
383 Gives information about the context denoted by C<$context>, akin to what L<perlfunc/caller> provides but not limited only to subroutine, eval and format contexts.
384 When C<$context> is omitted, it defaults to the current context.
385  
386 The returned values are, in order :
387  
388 =over 4
389  
390 =item *
391  
392 I<(index 0)> : the namespace in use when the context was created ;
393  
394 =item *
395  
396 I<(index 1)> : the name of the file at the point where the context was created ;
397  
398 =item *
399  
400 I<(index 2)> : the line number at the point where the context was created ;
401  
402 =item *
403  
404 I<(index 3)> : the name of the subroutine called for this context, or C<undef> if this is not a subroutine context ;
405  
406 =item *
407  
408 I<(index 4)> : a boolean indicating whether a new instance of C<@_> was set up for this context, or C<undef> if this is not a subroutine context ;
409  
410 =item *
411  
412 I<(index 5)> : the context (in the sense of L<perlfunc/wantarray>) in which the context (in our sense) is executed ;
413  
414 =item *
415  
416 I<(index 6)> : the contents of the string being compiled for this context, or C<undef> if this is not an eval context ;
417  
418 =item *
419  
420 I<(index 7)> : a boolean indicating whether this eval context was created by C<require>, or C<undef> if this is not an eval context ;
421  
422 =item *
423  
424 I<(index 8)> : the value of the lexical hints in use when the context was created ;
425  
426 =item *
427  
428 I<(index 9)> : a bit string representing the warnings in use when the context was created ;
429  
430 =item *
431  
432 I<(index 10)> : a reference to the lexical hints hash in use when the context was created (only on perl 5.10 or greater).
433  
434 =back
435  
436 =head2 C<uplevel>
437  
438 my @ret = uplevel { ...; return @ret };
439 my @ret = uplevel { my @args = @_; ...; return @ret } @args, $context;
440 my @ret = &uplevel($callback, @args, $context);
441  
442 Executes the code reference C<$callback> with arguments C<@args> as if it were located at the subroutine stack frame pointed by C<$context>, effectively fooling C<caller> and C<die> into believing that the call actually happened higher in the stack.
443 The code is executed in the context of the C<uplevel> call, and what it returns is returned as-is by C<uplevel>.
444  
445 sub target {
446 faker(@_);
447 }
448  
449 sub faker {
450 uplevel {
451 map { 1 / $_ } @_;
452 } @_ => CALLER(1);
453 }
454  
455 my @inverses = target(1, 2, 4); # @inverses contains (0, 0.5, 0.25)
456 my $count = target(1, 2, 4); # $count is 3
457  
458 Note that if C<@args> is empty, then the C<$context> parameter is optional and defaults to the current context ; otherwise it is mandatory.
459  
460 L<Sub::Uplevel> also implements a pure-Perl version of C<uplevel>.
461 Both are identical, with the following caveats :
462  
463 =over 4
464  
465 =item *
466  
467 The L<Sub::Uplevel> implementation of C<uplevel> may execute a code reference in the context of B<any> upper stack frame.
468 The L<Scope::Upper> version can only uplevel to a B<subroutine> stack frame, and will croak if you try to target an C<eval> or a format.
469  
470 =item *
471  
472 Exceptions thrown from the code called by this version of C<uplevel> will not be caught by C<eval> blocks between the target frame and the uplevel call, while they will for L<Sub::Uplevel>'s version.
473 This means that :
474  
475 eval {
476 sub {
477 local $@;
478 eval {
479 sub {
480 uplevel { die 'wut' } CALLER(2); # for Scope::Upper
481 # uplevel(3, sub { die 'wut' }) # for Sub::Uplevel
482 }->();
483 };
484 print "inner block: $@";
485 $@ and exit;
486 }->();
487 };
488 print "outer block: $@";
489  
490 will print "inner block: wut..." with L<Sub::Uplevel> and "outer block: wut..." with L<Scope::Upper>.
491  
492 =item *
493  
494 L<Sub::Uplevel> globally overrides the Perl keyword C<caller>, while L<Scope::Upper> does not.
495  
496 =back
497  
498 A simple wrapper lets you mimic the interface of L<Sub::Uplevel/uplevel> :
499  
500 use Scope::Upper;
501  
502 sub uplevel {
503 my $frame = shift;
504 my $code = shift;
505 my $cxt = Scope::Upper::CALLER($frame);
506 &Scope::Upper::uplevel($code => @_ => $cxt);
507 }
508  
509 Albeit the three exceptions listed above, it passes all the tests of L<Sub::Uplevel>.
510  
511 =head2 C<uid>
512  
513 my $uid = uid;
514 my $uid = uid $context;
515  
516 Returns an unique identifier (UID) for the context (or dynamic scope) pointed by C<$context>, or for the current context if C<$context> is omitted.
517 This UID will only be valid for the life time of the context it represents, and another UID will be generated next time the same scope is executed.
518  
519 my $uid;
520  
521 {
522 $uid = uid;
523 if ($uid eq uid()) { # yes, this is the same context
524 ...
525 }
526 {
527 if ($uid eq uid()) { # no, we are one scope below
528 ...
529 }
530 if ($uid eq uid(UP)) { # yes, UP points to the same scope as $uid
531 ...
532 }
533 }
534 }
535  
536 # $uid is now invalid
537  
538 {
539 if ($uid eq uid()) { # no, this is another block
540 ...
541 }
542 }
543  
544 For example, each loop iteration gets its own UID :
545  
546 my %uids;
547  
548 for (1 .. 5) {
549 my $uid = uid;
550 $uids{$uid} = $_;
551 }
552  
553 # %uids has 5 entries
554  
555 The UIDs are not guaranteed to be numbers, so you must use the C<eq> operator to compare them.
556  
557 To check whether a given UID is valid, you can use the L</validate_uid> function.
558  
559 =head2 C<validate_uid>
560  
561 my $is_valid = validate_uid $uid;
562  
563 Returns true if and only if C<$uid> is the UID of a currently valid context (that is, it designates a scope that is higher than the current one in the call stack).
564  
565 my $uid;
566  
567 {
568 $uid = uid();
569 if (validate_uid($uid)) { # yes
570 ...
571 }
572 {
573 if (validate_uid($uid)) { # yes
574 ...
575 }
576 }
577 }
578  
579 if (validate_uid($uid)) { # no
580 ...
581 }
582  
583 =head1 CONSTANTS
584  
585 =head2 C<SU_THREADSAFE>
586  
587 True iff the module could have been built when thread-safety features.
588  
589 =head1 WORDS
590  
591 =head2 Constants
592  
593 =head3 C<TOP>
594  
595 my $top_context = TOP;
596  
597 Returns the context that currently represents the highest scope.
598  
599 =head3 C<HERE>
600  
601 my $current_context = HERE;
602  
603 The context of the current scope.
604  
605 =head2 Getting a context from a context
606  
607 For any of those functions, C<$from> is expected to be a context.
608 When omitted, it defaults to the current context.
609  
610 =head3 C<UP>
611  
612 my $upper_context = UP;
613 my $upper_context = UP $from;
614  
615 The context of the scope just above C<$from>.
616 If C<$from> points to the top-level scope in the current stack, then a warning is emitted and C<$from> is returned (see L</DIAGNOSTICS> for details).
617  
618 =head3 C<SUB>
619  
620 my $sub_context = SUB;
621 my $sub_context = SUB $from;
622  
623 The context of the closest subroutine above C<$from>.
624 If C<$from> already designates a subroutine context, then it is returned as-is ; hence C<SUB SUB == SUB>.
625 If no subroutine context is present in the call stack, then a warning is emitted and the current context is returned (see L</DIAGNOSTICS> for details).
626  
627 =head3 C<EVAL>
628  
629 my $eval_context = EVAL;
630 my $eval_context = EVAL $from;
631  
632 The context of the closest eval above C<$from>.
633 If C<$from> already designates an eval context, then it is returned as-is ; hence C<EVAL EVAL == EVAL>.
634 If no eval context is present in the call stack, then a warning is emitted and the current context is returned (see L</DIAGNOSTICS> for details).
635  
636 =head2 Getting a context from a level
637  
638 Here, C<$level> should denote a number of scopes above the current one.
639 When omitted, it defaults to C<0> and those functions return the same context as L</HERE>.
640  
641 =head3 C<SCOPE>
642  
643 my $context = SCOPE;
644 my $context = SCOPE $level;
645  
646 The C<$level>-th upper context, regardless of its type.
647 If C<$level> points above the top-level scope in the current stack, then a warning is emitted and the top-level context is returned (see L</DIAGNOSTICS> for details).
648  
649 =head3 C<CALLER>
650  
651 my $context = CALLER;
652 my $context = CALLER $level;
653  
654 The context of the C<$level>-th upper subroutine/eval/format.
655 It kind of corresponds to the context represented by C<caller $level>, but while e.g. C<caller 0> refers to the caller context, C<CALLER 0> will refer to the top scope in the current context.
656 If C<$level> points above the top-level scope in the current stack, then a warning is emitted and the top-level context is returned (see L</DIAGNOSTICS> for details).
657  
658 =head2 Examples
659  
660 Where L</reap> fires depending on the C<$cxt> :
661  
662 sub {
663 eval {
664 sub {
665 {
666 reap \&cleanup => $cxt;
667 ...
668 } # $cxt = SCOPE(0) = HERE
669 ...
670 }->(); # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
671 ...
672 }; # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1)
673 ...
674 }->(); # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
675 ...
676  
677 Where L</localize>, L</localize_elem> and L</localize_delete> act depending on the C<$cxt> :
678  
679 sub {
680 eval {
681 sub {
682 {
683 localize '$x' => 1 => $cxt;
684 # $cxt = SCOPE(0) = HERE
685 ...
686 }
687 # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
688 ...
689 }->();
690 # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1)
691 ...
692 };
693 # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
694 ...
695 }->();
696 # $cxt = SCOPE(4), UP SUB UP SUB = UP SUB EVAL = UP CALLER(2) = TOP
697 ...
698  
699 Where L</unwind>, L</yield>, L</want_at>, L</context_info> and L</uplevel> point to depending on the C<$cxt>:
700  
701 sub {
702 eval {
703 sub {
704 {
705 unwind @things => $cxt; # or yield @things => $cxt
706 # or uplevel { ... } $cxt
707 ...
708 }
709 ...
710 }->(); # $cxt = SCOPE(0) = SCOPE(1) = HERE = UP = SUB = CALLER(0)
711 ...
712 }; # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1) (*)
713 ...
714 }->(); # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
715 ...
716  
717 # (*) Note that uplevel() will croak if you pass that scope frame,
718 # because it cannot target eval scopes.
719  
720 =head1 DIAGNOSTICS
721  
722 =head2 C<Cannot target a scope outside of the current stack>
723  
724 This warning is emitted when L</UP>, L</SCOPE> or L</CALLER> end up pointing to a context that is above the top-level context of the current stack.
725 It indicates that you tried to go higher than the main scope, or to point across a C<DESTROY> method, a signal handler, an overloaded or tied method call, a C<require> statement or a C<sort> callback.
726 In this case, the resulting context is the highest reachable one.
727  
728 =head2 C<No targetable %s scope in the current stack>
729  
730 This warning is emitted when you ask for an L</EVAL> or L</SUB> context and no such scope can be found in the call stack.
731 The resulting context is the current one.
732  
733 =head1 EXPORT
734  
735 The functions L</reap>, L</localize>, L</localize_elem>, L</localize_delete>, L</unwind>, L</yield>, L</leave>, L</want_at>, L</context_info> and L</uplevel> are only exported on request, either individually or by the tags C<':funcs'> and C<':all'>.
736  
737 The constant L</SU_THREADSAFE> is also only exported on request, individually or by the tags C<':consts'> and C<':all'>.
738  
739 Same goes for the words L</TOP>, L</HERE>, L</UP>, L</SUB>, L</EVAL>, L</SCOPE> and L</CALLER> that are only exported on request, individually or by the tags C<':words'> and C<':all'>.
740  
741 =cut
742  
743 49 ▶use base qw<Exporter>;
Subroutine BEGIN: called CC=1 SCAR=0.0
744  
745 49 our @EXPORT = ();
746 49 our %EXPORT_TAGS = (
747 funcs => [ qw<
748 reap
749 localize localize_elem localize_delete
750 unwind yield leave
751 want_at context_info
752 uplevel
753 uid validate_uid
754 > ],
755 words => [ qw<TOP HERE UP SUB EVAL SCOPE CALLER> ],
756 consts => [ qw<SU_THREADSAFE> ],
757 );
758 49 our @EXPORT_OK = map { @$_ } values %EXPORT_TAGS;
759 49 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
760  
761 =head1 CAVEATS
762  
763 It is not possible to act upon a scope that belongs to another perl 'stack', i.e. to target a scope across a C<DESTROY> method, a signal handler, an overloaded or tied method call, a C<require> statement or a C<sort> callback.
764  
765 Be careful that local variables are restored in the reverse order in which they were localized.
766 Consider those examples:
767  
768 local $x = 0;
769 {
770 reap sub { print $x } => HERE;
771 local $x = 1;
772 ...
773 }
774 # prints '0'
775 ...
776 {
777 local $x = 1;
778 reap sub { $x = 2 } => HERE;
779 ...
780 }
781 # $x is 0
782  
783 The first case is "solved" by moving the C<local> before the C<reap>, and the second by using L</localize> instead of L</reap>.
784  
785 The effects of L</reap>, L</localize> and L</localize_elem> can't cross C<BEGIN> blocks, hence calling those functions in C<import> is deemed to be useless.
786 This is an hopeless case because C<BEGIN> blocks are executed once while localizing constructs should do their job at each run.
787 However, it's possible to hook the end of the current scope compilation with L<B::Hooks::EndOfScope>.
788  
789 Some rare oddities may still happen when running inside the debugger.
790 It may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some context-related fixes.
791  
792 Calling C<goto> to replace an L</uplevel>'d code frame does not work :
793  
794 =over 4
795  
796 =item *
797  
798 for a C<perl> older than the 5.8 series ;
799  
800 =item *
801  
802 for a C<DEBUGGING> C<perl> run with debugging flags set (as in C<perl -D ...>) ;
803  
804 =item *
805  
806 when the runloop callback is replaced by another module.
807  
808 =back
809  
810 In those three cases, L</uplevel> will look for a C<goto &sub> statement in its callback and, if there is one, throw an exception before executing the code.
811  
812 Moreover, in order to handle C<goto> statements properly, L</uplevel> currently has to suffer a run-time overhead proportional to the size of the callback in every case (with a small ratio), and proportional to the size of B<all> the code executed as the result of the L</uplevel> call (including subroutine calls inside the callback) when a C<goto> statement is found in the L</uplevel> callback.
813 Despite this shortcoming, this XS version of L</uplevel> should still run way faster than the pure-Perl version from L<Sub::Uplevel>.
814  
815 Starting from C<perl> 5.19.4, it is unfortunately no longer possible to reliably throw exceptions from L</uplevel>'d code while the debugger is in use.
816 This may be solved in a future version depending on how the core evolves.
817  
818 =head1 DEPENDENCIES
819  
820 L<perl> 5.6.1.
821  
822 A C compiler.
823 This module may happen to build with a C++ compiler as well, but don't rely on it, as no guarantee is made in this regard.
824  
825 L<XSLoader> (core since perl 5.6.0).
826  
827 =head1 SEE ALSO
828  
829 L<perlfunc/local>, L<perlsub/"Temporary Values via local()">.
830  
831 L<Alias>, L<Hook::Scope>, L<Scope::Guard>, L<Guard>.
832  
833 L<Sub::Uplevel>.
834  
835 L<Continuation::Escape> is a thin wrapper around L<Scope::Upper> that gives you a continuation passing style interface to L</unwind>.
836 It's easier to use, but it requires you to have control over the scope where you want to return.
837  
838 L<Scope::Escape>.
839  
840 =head1 AUTHOR
841  
842 Vincent Pit C<< <vpit at cpan.org> >>.
843  
844 You can contact me by mail or on C<irc.perl.org> (vincent).
845  
846 =head1 BUGS
847  
848 Please report any bugs or feature requests to C<bug-scope-upper at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Upper>.
849 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
850  
851 =head1 SUPPORT
852  
853 You can find documentation for this module with the perldoc command.
854  
855 perldoc Scope::Upper
856  
857 =head1 ACKNOWLEDGEMENTS
858  
859 Inspired by Ricardo Signes.
860  
861 The reimplementation of a large part of this module for perl 5.24 was provided by David Mitchell.
862 His work was sponsored by the Perl 5 Core Maintenance Grant from The Perl Foundation.
863  
864 Thanks to Shawn M. Moore for motivation.
865  
866 =head1 COPYRIGHT & LICENSE
867  
868 Copyright 2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019,2021,2023,2026 Vincent Pit, all rights reserved.
869  
870 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
871  
872 =cut
873  
874 49 1; # End of Scope::Upper
« xsh/threads.h ↑ Summary