1Return::MultiLevel(3) User Contributed Perl DocumentationReturn::MultiLevel(3)
2
3
4

NAME

6       Return::MultiLevel - return across multiple call levels
7

SYNOPSIS

9         use Return::MultiLevel qw(with_return);
10
11         sub inner {
12           my ($f) = @_;
13           $f->(42);  # implicitly return from 'with_return' below
14           print "You don't see this\n";
15         }
16
17         sub outer {
18           my ($f) = @_;
19           inner($f);
20           print "You don't see this either\n";
21         }
22
23         my $result = with_return {
24           my ($return) = @_;
25           outer($return);
26           die "Not reached";
27         };
28         print $result, "\n";  # 42
29

DESCRIPTION

31       This module provides a way to return immediately from a deeply nested
32       call stack. This is similar to exceptions, but exceptions don't stop
33       automatically at a target frame (and they can be caught by intermediate
34       stack frames using "eval"). In other words, this is more like
35       setjmp(3)/longjmp(3) than "die".
36
37       Another way to think about it is that the "multi-level return" coderef
38       represents a single-use/upward-only continuation.
39
40   Functions
41       The following functions are available (and can be imported on demand).
42
43       with_return BLOCK
44           Executes BLOCK, passing it a code reference (called $return in this
45           description) as a single argument. Returns whatever BLOCK returns.
46
47           If $return is called, it causes an immediate return from
48           "with_return". Any arguments passed to $return become
49           "with_return"'s return value (if "with_return" is in scalar
50           context, it will return the last argument passed to $return).
51
52           It is an error to invoke $return after its surrounding BLOCK has
53           finished executing. In particular, it is an error to call $return
54           twice.
55

DEBUGGING

57       This module uses "unwind" from "Scope::Upper" to do its work. If
58       "Scope::Upper" is not available, it substitutes its own pure Perl
59       implementation. You can force the pure Perl version to be used
60       regardless by setting the environment variable "RETURN_MULTILEVEL_PP"
61       to 1.
62
63       If you get the error message "Attempt to re-enter dead call frame",
64       that means something has called a $return from outside of its
65       "with_return { ... }" block. You can get a stack trace of where that
66       "with_return" was by setting the environment variable
67       "RETURN_MULTILEVEL_DEBUG" to 1.
68

BUGS AND LIMITATIONS

70       You can't use this module to return across implicit function calls,
71       such as signal handlers (like $SIG{ALRM}) or destructors ("sub DESTROY
72       { ... }").  These are invoked automatically by perl and not part of the
73       normal call chain.
74

SUPPORT AND DOCUMENTATION

76       After installing, you can find documentation for this module with the
77       "perldoc" command.
78
79           perldoc Return::MultiLevel
80
81       You can also look for information at
82       <https://metacpan.org/pod/Return::MultiLevel>.
83
84       To see a list of open bugs, visit
85       <https://rt.cpan.org/Public/Dist/Display.html?Name=Return-MultiLevel>.
86
87       To report a new bug, send an email to "bug-Return-MultiLevel [at]
88       rt.cpan.org".
89

AUTHOR

91       Lukas Mai, "<l.mai at web.de>"
92

94       Copyright 2013-2014 Lukas Mai.
95
96       This program is free software; you can redistribute it and/or modify it
97       under the terms of either: the GNU General Public License as published
98       by the Free Software Foundation; or the Artistic License.
99
100       See <http://dev.perl.org/licenses/> for more information.
101
102
103
104perl v5.30.1                      2020-02-17             Return::MultiLevel(3)
Impressum