NAME
    Callback::Frame - Preserve error handlers and "local" variables across
    callbacks

SYNOPSIS
        use Callback::Frame;

        my $callback;

        frame(name => "base frame",
              code => sub {
                        $callback = frame(name => "frame #1",
                                          code => sub {
                                                    die "some error";
                                                  });
                      },
              catch => sub {
                         my $stack_trace = shift;
                         print $stack_trace;
                         ## Also, $@ is set to "some error at ..."
                       }
        )->();

        $callback->();

    This will print something like:

        some error at synopsis.pl line 9.
        ----- Callback::Frame stack-trace -----
        synopsis.pl:10 - frame #1
        synopsis.pl:17 - base frame

BACKGROUND
    When programming with callbacks in perl, you create anonymous functions
    with "sub { ... }". These functions are especially useful because when
    they are called they will preserve their surrounding lexical
    environment.

    In other words, the following bit of code

        my $callback;
        {
          my $var = 123;
          $callback = sub { $var };
        }
        print $callback->();

    will print 123 even though $var is no longer in scope when the callback
    is invoked.

    Sometimes people call these anonymous functions that reference variables
    in their surrounding lexical scope "closures". Whatever you call them,
    they are essential for convenient and efficient asynchronous
    programming.

    The Callback::Frame philosophy is that for many applications we really
    like callback style and don't wish to run (or pretend to run) multiple
    blocking tasks at once. Callback::Frame just tries to simplify the
    management of dynamic environments (defined below) while leaving
    callback style alone.

DESCRIPTION
    The problem that this module solves is that although closures preserve
    their lexical environment, they don't preserve error handlers or "local"
    variables.

    Consider the following piece of broken code:

        use AnyEvent;

        eval {
          $watcher = AE::timer 0.1, 0,
            sub {
              die "some error";
            };
        };

        ## broken!
        if ($@) {
          print STDERR "Oops: $@";
        }

        AE::cv->recv;

    The intent behind the "eval" above is obviously to catch any exceptions
    thrown inside the callback. However, this will not work because the
    "eval" will only be in effect while installing the callback in the event
    loop, not while running the callback. When the event loop calls the
    callback, it will probably wrap its own "eval" around the callback and
    you will see something like this:

        EV: error in callback (ignoring): some error at broken.pl line 6.

    (The above applies to EV which is a well-designed event loop. Other
    event loops may fail more catastrophically.)

    So the root of the problem is that the dynamic environment has not been
    preserved. In this case it is the dynamic exception handlers that were
    not preserved. In some other cases we would like to preserve dynamically
    scoped (aka "local") variables (see below).

    By the way, "lexical" and "dynamic" are the lisp terms. When it applies
    to variables, perl confusingly calls dynamic scoping "local" scoping,
    even though the scope is temporal, not local.

    Here is how we could fix this code using Callback::Frame:

        use AnyEvent;
        use Callback::Frame;

        frame(
          code => sub {
            $watcher = AE::timer 0.1, 0,
              frame(code => sub {
                              die "some error";
                            });
          }, catch => sub {
            print STDERR "Oops: $@";
          }
        )->();

        AE::cv->recv;

    Now we see the desired error message:

        Oops: some error at fixed.pl line 8.

    We created two frames to accomplish this: A root frame to contain the
    exception handler, and a nested frame to use as a callback. Because the
    nested callback frame is created while the root frame is executing, the
    callback will preserve the dynamic environment (including the exception
    handler) of the root frame.

USAGE
    This module exports two functions, "frame" and "fub".

    "frame" is the general interface and requires at least a "code" argument
    which should be a coderef (a function or a closure). It will return
    another coderef that "wraps" the coderef you passed in. When this codref
    is run, it will re-instate the dynamic environment that was present when
    the frame was created, and then run the coderef that you passed in as
    "code".

    IMPORTANT NOTE: All callbacks that may be invoked outside the dynamic
    environment of the current frame should be created with "frame" or "fub"
    so that the dynamic environment will be correctly re-applied when the
    callback is invoked.

    "fub" is a wrapper around frame and exists to simplify converting
    existing callbacks into Callback::Frame enabled code. For example, given
    the following AnyEvent statement:

        $watcher = AE::io $sock, 0, sub { do_stuff() };

    In order for the callback to have its dynamic environment maintained,
    you just need to change it to this:

        $watcher = AE::io $sock, 0, fub { do_stuff() };

    "frame" and "fub" both also accept "catch" and "local" parameters which
    are described in detail below.

    Libraries that wrap callbacks in frames can use the
    "Callback::Frame::is_frame()" function to determine if a given callback
    is already wrapped in a frame. It returns true if the callback is
    wrapped in a frame and is therefore suitable for use with
    "existing_frame". Sometimes libraries like to automatically wrap a
    callback in a frame unless it already is one:

        if (!Callback::Frame::is_frame($callback)) {
          $callback = fub { $callback->(); };
        }

    If you wish to run a coderef inside an existing frame's dynamic
    environment, when creating a frame you can pass in an existing frame as
    the "existing_frame" parameter. When this frame is executed, the "code"
    of the frame will be run inside "existing_frame"'s dynamic environment.
    This is useful for throwing exceptions from within some given callback's
    environment (timeouts for example):

        frame(existing_frame => $callback, code => sub {
          die "request timed out";
        })->();

    "existing_frame" is also useful for extracting/setting a callback's
    local variables.

    Although you should never need to, the internal frame stack can be
    accessed at $Callback::Frame::top_of_stack. When this variable is
    defined, a frame is currently being executed.

NESTING AND STACK-TRACES
    Callback::Frame tries to make adding error handling support to an
    existing asynchronous application as easy as possible by not forcing you
    to pass extra parameters around. It should also make lifer easier
    because as a side effect of adding error checking it also can be made to
    produce detailed and useful "stack traces" that track the callback
    history of some connection or transaction.

    Frames can be nested. When an exception is raised, the most deeply
    nested "catch" handler is invoked. If this handler itself throws an
    error, the next most deeply nested handler is invoked with the new
    exception but the original stack trace. If the last "catch" handler
    re-throws the error, the error will be thrown in whatever dynamic
    environment was in place when the callback was called, usually the event
    loop's top-level handler (probably not what you want).

    When a "catch" handler is called, not only is $@ set, but also a
    stack-trace string is passed in as the first argument. All frames will
    be listed in this stack-trace, starting with the most deeply nested
    frame.

    If you want you can use simple frame names like "accepted" but if you
    are recording error messages in a log you might find it useful to name
    your frames things like "accepted connection from $ip:$port at $time"
    and "connecting to $host (timeout = $timeout seconds)".

    All frames you omit the name from will be shown as "ANONYMOUS FRAME" in
    stack-traces.

    Since multiple frames can be created within the same parent frame and
    therefore multiple child frames can be active at once, frames aren't
    necessarily arranged in terms of a stack. Really, the frame "stack" is
    more of a tree data structure (known in lisp as a "spaghetti stack").
    This occurs most often when two asynchronous request frames are started
    up concurrently while the same frame is in effect. At this point the
    "stack" has essentially branched. If you are ever surprised by an
    exception handler being called twice, this is probably what is
    happening.

"LOCAL" VARIABLES
    In the same way that using "catch" as described above preserves the
    dynamic environment of error handlers, "local" preserves the dynamic
    environment of variables. Of course, the scope of these bindings is not
    actually local in the physical sense of the word, only in the perl
    sense.

    Technically, "local" maintains the dynamic environment of bindings. The
    distinction between variables and bindings is subtle but important. See,
    when a lexical binding is created, it is there "forever" -- or at least
    until it is no longer reachable by your program according to the rules
    of lexical scoping. Therefore, lexical variables are statically mapped
    to bindings and it is redundant to distinguish between lexical variables
    and bindings.

    However, with dynamic variables the same variable can refer to different
    bindings at different times. That's why they are called "dynamic" and
    lexical variables are sometimes called "static".

    Because any code in any file, function, or package can access a dynamic
    variable, they are the opposite of local. They are global. However, the
    bindings are only global for a little while at a time. After a while
    they will go out of scope and then they are no longer visible at all. Or
    sometimes they will get "shadowed" by some other binding and will come
    back again later.

    To make this concrete, here the binding containing 2 is lost forever:

        our $foo = 1;
        my $cb;

        {
          local $foo;
          $foo = 2;
          $cb = sub {
            return $foo;
          };
        }

        say $foo;     # 1
        say $cb->();  # 1  <- not 2!
        say $foo;     # 1

    Here's a way to "fix" that using Callback::Frame:

        our $foo = 1;
        my $cb;

        frame(local => __PACKAGE__ . '::foo',
              code => sub {
          $foo = 2;
          $cb = fub {
            return $foo;
          };
        })->();

        say $foo;     # 1
        say $cb->();  # 2  <- hooray!
        say $foo;     # 1

    Don't be fooled into thinking that this is a lexical binding though.
    While the callback $cb is executing, all parts of the program will see
    the 2 binding:

        our $foo = 1;
        my $cb;

        sub global_foo_getter {
          return $foo;
        }

        frame(local => __PACKAGE__ . '::foo',
              code => sub {
          $foo = 2;
          $cb = fub {
            return global_foo_getter();
          };
        })->();

        say $foo;     # 1
        say $cb->();  # 2  <- still 2
        say $foo;     # 1

    You can install multiple local variables in the same frame:

        frame(local => __PACKAGE__ . '::foo',
              local => 'main::bar',
              ... );

    Note that if you have both "catch" and "local" elements in a frame, in
    the event of an error the local bindings will not be present inside the
    "catch" handler (use a nested frame if you need this).

    All variable names must be fully package qualified. The best way to do
    this for variables in your current package is to use the ugly
    "__PACKAGE__" technique.

    Objects stored in local bindings managed by Callback::Frame will not be
    destroyed until all references to the frame-wrapped callback that
    contains the binding are destroyed, along with all references to any
    deeper frames.

SEE ALSO
    <The Callback::Frame github repo>

    AnyEvent::Task uses Callback::Frame.

    This module's "catch" syntax is of course modeled after "normal
    language" style exception handling as implemented by Try::Tiny &c.

    This module depends on Guard to maintain the
    $Callback::Frame::active_frames datastructure and to ensure that "local"
    binding updates aren't lost even when exceptions or other non-local
    returns occur.

    AnyEvent::Debug is a very interesting and useful module that provides an
    interactive debugger for AnyEvent applications and uses some of the same
    techniques that Callback::Frame does. AnyEvent::Callback and
    AnyEvent::CallbackStack sort of solve the dynamic error handler problem.
    Unlike these modules, Callback::Frame is not related at all to AnyEvent,
    except that it happens to be useful in AnyEvent libraries and
    applications (among other things).

    Miscellaneous other modules: IO::Lambda::Backtrace,
    POE::Filter::ErrorProof

    Python Tornado's <StackContext> and "async_callback"

    <Let Over Lambda, Chapter 2>

    <UNWIND-PROTECT vs. Continuations>

BUGS
    For now, "local" bindings can only be created in the scalar namespace.
    Also, none of the other nifty things that local can do (like localising
    a hash table value) are supported yet.

AUTHOR
    Doug Hoyte, "<doug@hcsw.org>"

COPYRIGHT & LICENSE
    Copyright 2012-2013 Doug Hoyte.

    This module is licensed under the same terms as perl itself.

