AsyncAwait.pm

filter: Statementstmt 93.7% 15 / 16 Branchbran 25.0% 1 / 4 Conditioncond 50.0% 1 / 2 MC/DCmcdc 0.0% 0 / 1 Subroutinesub 100% 4 / 4 Podpod n/a totaltotal 77.7% 21 / 27 CC 1 SCAR 0.0
CC
1
Cov
77%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« AsyncAwait/Backend/Coro.pm ↑ Summary
1 package Mojo::AsyncAwait;
2  
3 9 ▶use Carp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
4 9 ▶use Mojo::Loader;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 9 ▶use Import::Into;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 9 our $VERSION = '0.03';
8  
9 9 ▶my $backend = $ENV{MOJO_ASYNCAWAIT_BACKEND} // '+Coro';
Condition50%1/2
$ENV{"MOJO_ASYNCAWAIT_BACKEND"} // "+Coro"
l!l
09
MC/DC0%0/1
$ENV{"MOJO_ASYNCAWAIT_BACKEND"} // "+Coro"
$ENV{"MOJO_ASYNCAWAIT_BACKEND"}
Truth table50%1/2
A
A= $ENV{"MOJO_ASYNCAWAIT_BACKEND"}
Aresult
11
00
10 9 $backend =~ s/^\+/Mojo::AsyncAwait::Backend::/;
11 9 ▶if(my $e = Mojo::Loader::load_class($backend)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $e = Mojo::Loader::load_class($backend)) 0 9 9
12 0 ▶ Carp::croak(ref $e ? $e : "Could not find backend $backend. Perhaps you need to install it?");
Branch: 1 branch
BranchTrueFalseTotal
ref $e ? : 0 0 0
13 }
14  
15 9 ▶sub import { $backend->import::into(scalar caller) }
Subroutine import: called CC=1 SCAR=0.0
16  
17 9 1;
18  
19  
20 =encoding utf8
21  
22 =head1 NAME
23  
24 Mojo::AsyncAwait - An Async/Await implementation for Mojolicious
25  
26 =head1 SYNOPSIS
27  
28 use Mojolicious::Lite -signatures;
29 use Mojo::AsyncAwait;
30  
31 get '/' => async sub ($c) {
32  
33 my $mojo = await $c->ua->get_p('https://mojolicious.org');
34 my $cpan = await $c->ua->get_p('https://metacpan.org');
35  
36 $c->render(json => {
37 mojo => $mojo->result->code,
38 cpan => $cpan->result->code
39 });
40 };
41  
42 app->start;
43  
44 =head1 DESCRIPTION
45  
46 Async/await is a language-independent pattern that allows nonblocking
47 asynchronous code to be structured simliarly to blocking code. This is done by
48 allowing execution to be suspended by the await keyword and returning once the
49 promise passed to await has been fulfilled.
50  
51 This pattern simplies the use of both promises and nonblocking code in general
52 and is therefore a very exciting development for writing asynchronous systems.
53  
54 If you are going to use this module to create async controllers actions in
55 L<Mojolicious> applications (as seen in the L</SYNOPSIS>) before Mojolicious
56 version 8.28, you are highly encouraged to also use
57 L<Mojolicious::Plugin::PromiseActions> in order to properly handle exceptions
58 in your action.
59  
60 =head1 GOALS
61  
62 The primary goal of this module is to provide a useful Async/Await
63 implementation for users of the Mojolicious ecosystem. It is for this reason
64 that L<Mojo::Promise> is used when new promises are created. Because this is
65 the primary goal, the intention is for it to remain useful even as other goals
66 are considered.
67  
68 Secondarily, it is intended to be a testbed for early implementations of
69 Async/Await in the Perl 5 language. It is for this reason that the
70 implementation details are intended to be replaceable. The result should
71 hopefully still be backwards compatible, mostly because the interface is so
72 simple. After all, it is just two keywords.
73  
74 Of course, I always intend as much as possible that Mojolicious-focused code is
75 as useful as practically possible for the broader Perl 5 ecosystem. It is for
76 this reason that while this module returns L<Mojo::Promise>s, it can accept any
77 then-able (read: promise) which conforms enough to the Promises/A+ standard.
78 The Promises/A+ standard is intended to increase the interoperability of
79 promises, and while that line becomes more gray in Perl 5 where we don't have a
80 single ioloop implementation, we try our best.
81  
82 Finally the third goal is to improve the mobility of the knowledge of this
83 pattern between languages. Users of Javascript probably are already familiar
84 with this patthern; when coming to Perl 5 they will want to continue to use it.
85 Likewise, as Perl 5 users take on new languages, if they are familiar with
86 common patterns in their new language, they will have an easier time learning.
87 Having a useable Async/Await library in Perl 5 is key to keeping Perl 5
88 relevent in moderning coding.
89  
90 =head1 BACKENDS
91  
92 This module actually does very little on its own, it simply loads and imports
93 backend implementations of Async/Await. The reason to use this module really
94 would be to use current default implementation without regards to what that
95 implementation is nor how it works.
96  
97 When it is loaded, the C<MOJO_ASYNCAWAIT_BACKEND> is checked, if not set then
98 the current default is used.
99  
100 # From environment
101 BEGIN{ $ENV{MOJO_ASYNCAWAIT_BACKEND} = '+CoolBackend' }
102 use Mojo::AsyncAwait;
103  
104 # Currently provided default
105 use Mojo::AsyncAwait;
106  
107 The backend is specified either as a fully qualified module name, e.g.
108 C<Mojo::AsyncAwait::Backend::CoolBackend> or using the C<+> as a shortcut for
109 C<Mojo::AsyncAwait::Backend::>, e.g. C<+CoolBackend> which would mean exactly
110 the same as the former.
111  
112 =head1 CAVEATS
113  
114 First and foremost, this is all a little bit crazy. Please consider carefully
115 before using this code in production.
116  
117 While many languages have async/await as a core language feature, currently in
118 Perl we must rely on modules that provide the mechanism of suspending and
119 resuming execution.
120  
121 The default implementation relies on L<Coro> which does some very magical
122 things to the Perl interpreter. Other less magical implementations are in the
123 works however none are available yet. As available implementations change or
124 stabilize, that default may be changed. Backend implementations may be added or
125 even be spun off. If your application depends on the backend implementation,
126 you may import it manually or use the described mechanisms to load it. In that
127 case you should be sure to add the backend to your dependency list in case it
128 is spun off in the future.
129  
130 Also note that while a L<Coro>-based implementation need not rely on L</await>
131 being called directly from an L</async> function, it is currently prohibitied
132 because it is likely that other/future implementations will rely on that
133 behavior and thus it should not be relied upon.
134  
135 =head1 KEYWORDS
136  
137 Regardless of backend, L<Mojo::AsyncAwait> provides two keywords (i.e.
138 functions), both exported by default. Depending on backend, their exact
139 behavior might change slightly, however, implementers should attempt to follow
140 the api described here as closely as possible.
141  
142 Some backends may allow additional options to be passed to the keywords; those
143 options should be kept minimal and if possible follow the conventions described
144 in L<Mojo::AsyncAwait::Backend::Coro>. This generic document will not describe
145 those additional options.
146  
147 =head2 async
148  
149 my $sub = async sub { ... };
150  
151 The async keyword wraps a subroutine as an asynchronous subroutine which is
152 able to be suspended via L</await>. The return value(s) of the subroutine, when
153 called, will be wrapped in a L<Mojo::Promise>.
154  
155 The async keyword must be called with a subroutine reference, which will be the
156 body of the async subroutine.
157  
158 Note that the returned subroutine reference is not invoked for you.
159 If you want to immediately invoke it, you need to so manually.
160  
161 my $promise = async(sub{ ... })->();
162  
163 If called with a preceding name, the subroutine will be installed into the
164 current package with that name.
165  
166 async installed_sub => sub { ... };
167 installed_sub();
168  
169 Unlike the case of an anonymous wrapped async subroutine reference described
170 above, if the subroutine is installed, nothing is returned.
171  
172 =head2 await
173  
174 my $tx = await Mojo::UserAgent->new->get_p('https://mojolicious.org');
175 my @results = await (async sub { ...; return @async_results })->();
176  
177 The await keyword suspends execution of an async sub until a promise is
178 fulfilled, returning the promise's results. In list context all promise results
179 are returned. For ease of use, in scalar context the first promise result is
180 returned and the remainder are discarded.
181  
182 If the value passed to await is not a promise (defined as having a C<then>
183 method), it will be wrapped in a Mojo::Promise for consistency. This is mostly
184 inconsequential to the user.
185  
186 Note that await can only take one promise as an argument. If you wanted to
187 await multiple promises you probably want L<Mojo::Promise/all> or less likely
188 L<Mojo::Promise/race>.
189  
190 my $results = await Mojo::Promise->all(@promises);
191  
192 =head1 AUTHORS
193  
194 Joel Berger <joel.a.berger@gmail.com>
195  
196 Marcus Ramberg <mramberg@cpan.org>
197  
198 =head1 CONTRIBUTORS
199  
200 Sebastian Riedel <kraih@mojolicious.org>
201  
202 =head1 ADDITIONAL THANKS
203  
204 Matt S Trout (mst)
205  
206 Paul Evans (LeoNerd)
207  
208 John Susek
209  
210 =head1 COPYRIGHT AND LICENSE
211  
212 Copyright (C) 2018, L</AUTHORS> and L</CONTRIBUTORS>.
213  
214 This program is free software, you can redistribute it and/or modify it under
215 the terms of the Artistic License version 2.0.
216  
217 =head1 SEE ALSO
218  
219 L<Mojo::Promise>
220  
221 L<Mojo::IOLoop>
222  
223 L<Mojolicious::Plugin::PromiseActions>
224  
225 L<MDN Async/Await|https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function>
226  
227 L<Coro::State>
228  
229 L<Future::AsyncAwait>
230  
231 L<PerlX::AsyncAwait>
232  
233 =cut
234  
« AsyncAwait/Backend/Coro.pm ↑ Summary