NAME

       Return::MultiLevel - Return across multiple call levels

VERSION

       version 0.08

SYNOPSIS

         use Return::MultiLevel qw(with_return);

         sub inner {
           my ($f) = @_;
           $f->(42);  # implicitly return from 'with_return' below
           print "You don't see this\n";
         }

         sub outer {
           my ($f) = @_;
           inner($f);
           print "You don't see this either\n";
         }

         my $result = with_return {
           my ($return) = @_;
           outer($return);
           die "Not reached";
         };
         print $result, "\n";  # 42

DESCRIPTION

       This module provides a way to return immediately from a deeply nested call stack. This is similar to
       exceptions, but exceptions don't stop automatically at a target frame (and they can be caught by
       intermediate stack frames using "eval"). In other words, this is more like setjmp(3)/longjmp(3) than
       "die".

       Another way to think about it is that the "multi-level return" coderef represents a
       single-use/upward-only continuation.

   Functions
       The following functions are available (and can be imported on demand).

       with_return BLOCK
           Executes  BLOCK,  passing  it  a  code  reference  (called  $return  in this description) as a single
           argument. Returns whatever BLOCK returns.

           If $return is called, it causes an immediate return  from  "with_return".  Any  arguments  passed  to
           $return  become  "with_return"'s  return value (if "with_return" is in scalar context, it will return
           the last argument passed to $return).

           It is an error to invoke $return after its surrounding BLOCK has finished executing.  In  particular,
           it is an error to call $return twice.

DEBUGGING

       This  module  uses  "unwind"  from  "Scope::Upper" to do its work. If "Scope::Upper" is not available, it
       substitutes its own pure Perl implementation. You can force the pure Perl version to be  used  regardless
       by setting the environment variable "RETURN_MULTILEVEL_PP" to 1.

       If  you  get  the  error message "Attempt to re-enter dead call frame", that means something has called a
       $return from outside of its "with_return { ... }" block.  You  can  get  a  stack  trace  of  where  that
       "with_return" was by setting the environment variable "RETURN_MULTILEVEL_DEBUG" to 1.

CAVEATS

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

AUTHORS

       •   Lukas Mai

       •   Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013,2014,2021 by Lukas Mai.

       This is free software; you can redistribute it and/or modify it under  the  same  terms  as  the  Perl  5
       programming language system itself.

perl v5.32.1                                       2021-12-25                            Return::MultiLevel(3pm)