view release on metacpan or  search on metacpan

README  view on Meta::CPAN

          $cv->send;
        });

        $cv->recv;

    When run, the above client will print something like this:

        $VAR1 = {
              'start' => '1363232705.96839',
              'end' => '1.027309',
              'logs' => [
                          [
                            '0.000179',
                            30,
                            'going to compute some operation in a worker'
                          ],
                          [
                            '0.023881061050415',
                            30,
                            'about to compute some operation'
                          ],
                          [
                            '1.025965',
                            30,
                            'finished some operation'
                          ]
                        ],
              'timers' => {
                            'computing some operation' => [
                                                            '0.024089061050415',
                                                            '1.02470206105041'
                                                          ]
                          }
            };

ERROR HANDLING
    In a synchronous program, if you expected some operation to throw an
    exception you might wrap it in "eval" like this:

        my $crypted;

        eval {
          $crypted = hash('secret');
        };

        if ($@) {
          say "hash failed: $@";
        } else {
          say "hashed password is $crypted";
        }

    But in an asynchronous program, typically "hash" would initiate some
    kind of asynchronous operation and then return immediately, allowing the
    program to go about other tasks while waiting for the result. Since the
    error might come back at any time in the future, the program needs a way
    to map the exception that is thrown back to the original context.

    AnyEvent::Task accomplishes this mapping with Callback::Frame.

    Callback::Frame lets you preserve error handlers (and "local" variables)
    across asynchronous callbacks. Callback::Frame is not tied to
    AnyEvent::Task, AnyEvent or any other async framework and can be used
    with almost all callback-based libraries.

    However, when using AnyEvent::Task, libraries that you use in the client
    must be AnyEvent compatible. This restriction obviously does not apply
    to your server code, that being the main purpose of this module:
    accessing blocking resources from an asynchronous program. In your
    server code, when there is an error condition you should simply "die" or
    "croak" as in a synchronous program.

    As an example usage of Callback::Frame, here is how we would handle
    errors thrown from a worker process running the "hash" method in an
    asychronous client program:

        use Callback::Frame;

        frame(code => sub {

          $client->checkout->hash('secret', sub {
            my ($checkout, $crypted) = @_;
            say "Hashed password is $crypted";
          });

        }, catch => sub {

          my $back_trace = shift;
          say "Error is: $@";
          say "Full back-trace: $back_trace";

        })->(); ## <-- frame is created and then immediately executed

    Of course if "hash" is something like a bcrypt hash function it is
    unlikely to raise an exception so maybe that's a bad example. On the
    other hand, maybe it's a really good example: In addition to errors that
    occur while running your callbacks, AnyEvent::Task uses Callback::Frame
    to throw errors if the worker process times out, so if the bcrypt "cost"
    is really cranked up it might hit the default 30 second time limit.

  Rationale for Callback::Frame
    Why not just call the callback but set $@ and indicate an error has
    occurred? This is the approach taken with AnyEvent::DBI for example. I
    believe the Callback::Frame interface is superior to this method. In a
    synchronous program, exceptions are out-of-band messages and code
    doesn't need to locally handle them. It can let them "bubble up" the
    stack, perhaps to a top-level error handler. Invoking the callback when
    an error occurs forces exceptions to be handled in-band.

    How about having AnyEvent::Task expose an error callback? This is the
    approach taken by AnyEvent::Handle for example. I believe
    Callback::Frame is superior to this method also. Although separate
    callbacks are (sort of) out-of-band, you still have to write error
    handler callbacks and do something relevant locally instead of allowing
    the exception to bubble up to an error handler.

    In servers, Callback::Frame helps you maintain the "dynamic state"
    (error handlers and dynamic variables) installed for a single
    connection. In other words, any errors that occur while servicing that
    connection will be able to be caught by an error handler specific to
    that connection. This lets you send an error response to the client and
    collect associated log messages in a Log::Defer object specific to that
    connection.

    Callback::Frame provides an error handler stack so you can have a
    top-level handler as well as nested handlers (similar to nested
    "eval"s). This is useful when you wish to have a top-level "bail-out"
    error handler and also nested error handlers that know how to retry or
    recover from an error in an async sub-operation.

    Callback::Frame is designed to be easily used with callback-based
    libraries that don't know about Callback::Frame. "fub" is a shortcut for
    "frame" with just the "code" argument. Instead of passing "sub { ... }"
    into libraries you can pass in "fub { ... }". When invoked, this wrapped
    callback will first re-establish any error handlers that you installed
    with "frame" and then run your provided code. Libraries that force
    in-band error signalling can be handled with callbacks such as "fub {
    die $@ if $@; ... }". Separate error callbacks should simply be "fub {
    die "failed becase ..." }".

    It's important that all callbacks be created with "fub" (or "frame")
    even if you don't expect them to fail so that the dynamic context is
    preserved for nested callbacks that may. An exception is the callbacks
    provided to AnyEvent::Task checkouts: These are automatically wrapped in
    frames for you (although explicitly passing in fubs is fine too).

    The Callback::Frame documentation explains how this works in much more
    detail.

  Reforking of workers after errors
    If a worker throws an error, the client receives the error but the
    worker process stays running. As long as the client has a reference to
    the checkout (and as long as the exception wasn't "fatal" -- see below),
    it can still be used to communicate with that worker so you can access
    error states, rollback transactions, or do any sort of required
    clean-up.

    However, once the checkout object is destroyed, by default the worker
    will be shutdown instead of returning to the client's worker pool as in
    the normal case where no errors were thrown. This is a "safe-by-default"
    behaviour that may help in the event that an exception thrown by a
    worker leaves the worker process in a broken/inconsistent state for some
    reason (for example a DBI connection died). This can be overridden by
    setting the "dont_refork_after_error" option to 1 in the client
    constructor. This will only matter if errors are being thrown frequently
    and your "setup" routines take a long time (aside from the setup
    routine, creating new workers is quite fast since the server has already
    compiled all the application code and just has to fork).

    There are cases where workers will never be returned to the worker pool:
    workers that have thrown fatal errors such as loss of worker connection
    or hung worker timeout errors. These errors are stored in the checkout
    and for as long as the checkout exists any methods on the checkout will
    immediately return the stored fatal error. Your client process can
    invoke this behaviour manually by calling the "throw_fatal_error" method
    on a checkout object to cancel an operation and force-terminate a
    worker.

    Another reason that a worker might not be returned to the worker pool is
    if it has been checked out "max_checkouts" times. If "max_checkouts" is
    specified as an argument to the Client constructor, then workers will be
    destroyed and reforked after being checked out this number of times.
    When not specified, workers are never re-forked for this reason. This
    parameter is useful for coping with libraries that leak memory or
    otherwise become slower/more resource-hungry over time.

COMPARISON WITH HTTP
    Why a custom protocol, client, and server? Can't we just use something
    like HTTP?

    It depends.

    AnyEvent::Task clients send discrete messages and receive ordered
    replies from workers, much like HTTP. The AnyEvent::Task protocol can be
    extended in a backwards-compatible manner like HTTP. AnyEvent::Task
    communication can be pipelined and possibly in the future even
    compressed like HTTP.

    The current AnyEvent::Task server obeys a very specific implementation
    policy: It is like a CGI server in that each process it forks is
    guaranteed to be handling only one connection at once so it can perform
    blocking operations without worrying about holding up other connections.