NAME
    `AnyEvent::Future' - use Future with AnyEvent

SYNOPSIS
     use AnyEvent;
     use AnyEvent::Future;

     my $future = AnyEvent::Future->new;

     some_async_function( ..., cb => sub { $future->done( @_ ) } );

     print Future->await_any(
        $future,
        AnyEvent::Future->new_timeout( after => 10 ),
     )->get;

    Or

     use AnyEvent::Future qw( as_future_cb );

     print Future->await_any(
        as_future_cb {
           some_async_function( ..., cb => shift )
        },
        AnyEvent::Future->new_timeout( after => 10 ),
     )->get;

DESCRIPTION
    This subclass of Future integrates with AnyEvent, allowing the `await'
    method to block until the future is ready. It allows `AnyEvent'-using
    code to be written that returns `Future' instances, so that it can make
    full use of `Future''s abilities, including Future::Utils, and also that
    modules using it can provide a `Future'-based asynchronous interface of
    their own.

    For a full description on how to use Futures, see the Future
    documentation.

CONSTRUCTORS
  $f = AnyEvent::Future->new
    Returns a new leaf future instance, which will allow waiting for its
    result to be made available, using the `await' method.

  $f = AnyEvent::Future->new_delay( @args )
  $f = AnyEvent::Future->new_timeout( @args )
    Returns a new leaf future instance that will become ready at the time
    given by the arguments, which will be passed to the `AnyEvent->timer'
    method.

    `new_delay' returns a future that will complete successfully at the
    alotted time, whereas `new_timeout' returns a future that will fail with
    the message `Timeout'.

  $f = AnyEvent::Future->from_cv( $cv )
    Returns a new leaf future instance that will become ready when the given
    AnyEvent::CondVar instance is ready. The success or failure result of
    the future will be the result passed to the condvar's `send' or `croak'
    method.

METHODS
  $cv = $f->as_cv
    Returns a new `AnyEvent::CondVar' instance that wraps the given future;
    it will complete with success or failure when the future does.

    Note that because `AnyEvent::CondVar->croak' takes only a single string
    message for the argument, any subsequent failure semantics are lost from
    the Future. To capture these as well, you may wish to use an `on_fail'
    callback or the `failure' method, to obtain them.

UTILITY FUNCTIONS
    The following utility functions are exported as a convenience.

  $f = as_future { CODE }
    Returns a new leaf future instance, which is also passed in to the block
    of code. The code is called in scalar context, and its return value is
    stored on the future. This will be deleted if the future is cancelled.

     $w = CODE->( $f )

    This utility is provided for the common case of wanting to wrap an
    `AnyEvent' function which will want to receive a callback function to
    inform of completion, and which will return a watcher object reference
    that needs to be stored somewhere.

  $f = as_future_cb { CODE }
    A futher shortcut to `as_future', where the code is passed two callback
    functions for `done' and `fail' directly, avoiding boilerplate in the
    common case for creating these closures capturing the future variable.
    In many cases this can reduce the code block to a single line.

     $w = CODE->( $done_cb, $fail_cb )

EXAMPLES
  Wrapping watcher-style `AnyEvent' functions
    The `as_future_cb' utility provides an excellent wrapper to take the
    common style of `AnyEvent' function that returns a watcher object and
    takes a completion callback, and turn it into a `Future' that can be
    used or combined with other `Future'-based code. For example, the
    AnyEvent::HTTP function called `http_get' performs in this style.

     use AnyEvent::Future qw( as_future_cb );
     use AnyEvent::HTTP qw( http_get );

     my $url = ...;

     my $f = as_future_cb {
        my ( $done_cb ) = @_;

        http_get $url, $done_cb;
     };

    This could of course be easily wrapped by a convenient function to
    return futures:

     sub http_get_future
     {
        my @args = @_;

        as_future_cb {
           my ( $done_cb ) = @_;

           http_get @args, $done_cb;
        }
     }

  Using `Future's as enhanced `CondVar's
    While at first glance it may appear that a `Future' instance is much
    like an AnyEvent::CondVar, the greater set of convergence methods (such
    as `needs_all' or `needs_any'), and the various utility functions (in
    Future::Utils) makes it possible to write the same style of code in a
    more concise or powerful way.

    For example, rather than using the `CondVar' `begin' and `end' methods,
    a set of `CondVar'-returning functions can be converted into `Futures',
    combined using `needs_all', and converted back to a `CondVar' again:

     my $cv = Future->needs_all(
        Future::AnyEvent->from_cv( FUNC1() ),
        Future::AnyEvent->from_cv( FUNC2() ),
        ...
     )->as_cv;

     my @results = $cv->recv;

    This would become yet more useful if, instead of functions that return
    `CondVars', we were operating on functions that return `Future's
    directly. Because the `needs_all' will cancel any still-pending futures
    the moment one of them failed, we get a nice neat cancellation of
    outstanding work if one of them fails, in a way that would be much
    harder without the `Future's. For example, using the `http_get_future'
    function from above:

     my $cv = Future->needs_all(
        http_get_future( "http://url-1" ),
        http_get_future( "http://url-2" ),
        http_get_future( "https://url-third/secret" ),
     )->as_cv;

     my @results = $cv->recv;

    In this case, the moment any of the HTTP GET functions fails, the ones
    that are still pending are all cancelled (by dropping their cancellation
    watcher object) and the overall `recv' call throws an exception.

    Of course, there is no need to convert the outermost `Future' into a
    `CondVar'; the full set of waiting semantics are implemented on these
    instances, so instead you may simply call `get' on it to achieve the
    same effect:

     my $f = Future->needs_all(
        http_get_future( "http://url-1" ),
        ...
     );

     my @results = $f->get;

    This has other side advantages, such as the list-valued semantics of
    failures that can provide additional information besides just the error
    message, and propagation of cancellation requests.

TODO
    *   Consider whether or not it would be considered "evil" to inject a
        new method into AnyEvent::CondVar; namely by doing

         sub AnyEvent::CondVar::as_future { AnyEvent::Future->from_cv( shift ) }

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>