File Coverage

blib/lib/Mojolicious/Plugin/Future.pm
Criterion Covered Total %
statement 24 24 100.0
branch 2 2 100.0
condition 2 3 66.6
subroutine 6 6 100.0
pod 1 1 100.0
total 35 36 97.2


line stmt bran cond sub pod time code
1             package Mojolicious::Plugin::Future;
2 1     1   436 use Mojo::Base 'Mojolicious::Plugin';
  1         2  
  1         5  
3              
4 1     1   362 use Future::Mojo;
  1         6347  
  1         24  
5 1     1   5 use Scalar::Util 'weaken';
  1         2  
  1         225  
6              
7             our $VERSION = '0.001';
8              
9             my %futures;
10              
11             sub register {
12 1     1 1 36 my ($self, $app, $options) = @_;
13            
14 1     2   9 $app->helper(future => sub { shift; Future::Mojo->new(@_) });
  2         16028  
  2         29  
15            
16             $app->helper(adopt_future => sub {
17 2     2   307 my ($c, $f) = @_;
18 2         5 my $tx = $c->render_later->tx;
19 2         52 my $fkey = "$f";
20 2         6 $futures{$fkey} = $f;
21 2         5 weaken(my $weak_c = $c);
22             return $f->on_ready(sub {
23 2         1416 my $f = shift;
24 2         4 delete $futures{$fkey};
25 2 100 66     11 $weak_c->helpers->reply->exception(scalar $f->failure)
26             if defined $weak_c and $f->is_failed;
27 2         53045 undef $tx;
28 2         10 });
29 1         27 });
30             }
31              
32             1;
33              
34             =head1 NAME
35              
36             Mojolicious::Plugin::Future - use Future in Mojolicious applications
37              
38             =head1 SYNOPSIS
39              
40             use Mojolicious::Lite;
41            
42             plugin 'Future';
43            
44             use Scalar::Util 'weaken';
45             use Mojo::UserAgent;
46             my $ua = Mojo::UserAgent->new;
47             get '/async_callback' => sub {
48             my $c = shift;
49             my $f = $c->future;
50             weaken(my $weak_f = $f); # only close over weakened Future
51             $ua->get('http://example.com', sub {
52             my ($ua, $tx) = @_;
53             $tx->success ? $weak_f->done($tx->result) : $weak_f->fail($tx->error->{message});
54             });
55             $c->adopt_future($f->on_done(sub {
56             my ($result) = @_;
57             $c->render(json => {result => $result->text});
58             }));
59             };
60            
61             get '/future_returning' => sub {
62             my $c = shift;
63             $c->adopt_future(returns_a_future()->then(sub {
64             my @result = @_;
65             return returns_another_future(@result);
66             })->on_done(sub {
67             my @result = @_;
68             $c->render(json => {result => \@result});
69             }));
70             };
71              
72             =head1 DESCRIPTION
73              
74             L is a convenient way to use L in a
75             L application. The final future in a sequence or convergence is
76             passed to the L helper, which takes care of the details of
77             asynchronous rendering in a similar fashion to
78             L.
79              
80             =head1 HELPERS
81              
82             =head2 adopt_future
83              
84             $f = $c->adopt_future($f);
85              
86             Disables automatic rendering, stores the Future instance, keeps a reference to
87             L in case the underlying connection gets closed
88             early, and calls L<< Mojolicious::Plugin::DefaultHelpers/"reply->exception" >>
89             if the Future fails.
90              
91             =head2 future
92              
93             my $f = $c->future;
94             my $f = $c->future($loop);
95              
96             Convenience method to return a new L object.
97              
98             =head1 METHODS
99              
100             L inherits all methods from L
101             and implements the following new ones.
102              
103             =head2 register
104              
105             $plugin->register(Mojolicious->new);
106              
107             Register helper in L application.
108              
109             =head1 BUGS
110              
111             Report any issues on the public bugtracker.
112              
113             =head1 AUTHOR
114              
115             Dan Book
116              
117             =head1 COPYRIGHT AND LICENSE
118              
119             This software is Copyright (c) 2017 by Dan Book.
120              
121             This is free software, licensed under:
122              
123             The Artistic License 2.0 (GPL Compatible)
124              
125             =head1 SEE ALSO
126              
127             L, L