view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    
       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 ( $url, @args ) = @_;
    
          as_future_cb {
             my ( $done_cb ) = @_;
    
             http_get $url, @args, $done_cb;
          }
       }

 Using Futures as enhanced CondVars

    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 Futures 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
    Futures. 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>