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

NAME

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

VERSION

9       version 0.08
10

SYNOPSIS

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

DESCRIPTION

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

DEBUGGING

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

CAVEATS

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

AUTHORS

79       •   Lukas Mai
80
81       •   Graham Ollis <plicease@cpan.org>
82

84       This software is copyright (c) 2013,2014,2021 by Lukas Mai.
85
86       This is free software; you can redistribute it and/or modify it under
87       the same terms as the Perl 5 programming language system itself.
88
89
90
91perl v5.34.0                      2022-01-21             Return::MultiLevel(3)
Impressum