1Mojo::Promise(3) User Contributed Perl Documentation Mojo::Promise(3)
2
6 Mojo::Promise - Promises/A+
7
9 use Mojo::Promise;
10 use Mojo::UserAgent;
11 # Wrap continuation-passing style APIs with promises
13 my $ua = Mojo::UserAgent->new;
14 sub get {
15 my $promise = Mojo::Promise->new;
16 $ua->get(@_ => sub {
17 my ($ua, $tx) = @_;
18 my $err = $tx->error;
19 if (!$err || $err->{code}) { $promise->resolve($tx) }
20 else { $promise->reject($err->{message}) }
21 });
22 return $promise;
23 }
24 # Perform non-blocking operations sequentially
26 get('https://mojolicious.org')->then(sub {
27 my $mojo = shift;
28 say $mojo->res->code;
29 return get('https://metacpan.org');
30 })->then(sub {
31 my $cpan = shift;
32 say $cpan->res->code;
33 })->catch(sub {
34 my $err = shift;
35 warn "Something went wrong: $err";
36 })->wait;
37 # Synchronize non-blocking operations (all)
39 my $mojo = get('https://mojolicious.org');
40 my $cpan = get('https://metacpan.org');
41 Mojo::Promise->all($mojo, $cpan)->then(sub {
42 my ($mojo, $cpan) = @_;
43 say $mojo->[0]->res->code;
44 say $cpan->[0]->res->code;
45 })->catch(sub {
46 my $err = shift;
47 warn "Something went wrong: $err";
48 })->wait;
49 # Synchronize non-blocking operations (race)
51 my $mojo = get('https://mojolicious.org');
52 my $cpan = get('https://metacpan.org');
53 Mojo::Promise->race($mojo, $cpan)->then(sub {
54 my $tx = shift;
55 say $tx->req->url, ' won!';
56 })->catch(sub {
57 my $err = shift;
58 warn "Something went wrong: $err";
59 })->wait;
60
62 Mojo::Promise is a Perl-ish implementation of Promises/A+
63 <https://promisesaplus.com>.
64
66 A promise is an object representing the eventual completion or failure
67 of a non-blocking operation. It allows non-blocking functions to return
68 values, like blocking functions. But instead of immediately returning
69 the final value, the non-blocking function returns a promise to supply
70 the value at some point in the future.
71 A promise can be in one of three states:
73 pending
75 Initial state, neither fulfilled nor rejected.
76 fulfilled
78 Meaning that the operation completed successfully.
79 rejected
81 Meaning that the operation failed.
82 A pending promise can either be fulfilled with a value or rejected with
84 a reason. When either happens, the associated handlers queued up by a
85 promise's "then" method are called.
86
88 Mojo::Promise implements the following attributes.
89 ioloop
91 my $loop = $promise->ioloop;
92 $promise = $promise->ioloop(Mojo::IOLoop->new);
93 Event loop object to control, defaults to the global Mojo::IOLoop
95 singleton. Note that this attribute is weakened.
96
98 Mojo::Promise inherits all methods from Mojo::Base and implements the
99 following new ones.
100 all
102 my $new = Mojo::Promise->all(@promises);
103 Returns a new Mojo::Promise object that either fulfills when all of the
105 passed Mojo::Promise objects have fulfilled or rejects as soon as one
106 of them rejects. If the returned promise fulfills, it is fulfilled with
107 the values from the fulfilled promises in the same order as the passed
108 promises. This method can be useful for aggregating results of multiple
109 promises.
110 catch
112 my $new = $promise->catch(sub {...});
113 Appends a rejection handler callback to the promise, and returns a new
115 Mojo::Promise object resolving to the return value of the callback if
116 it is called, or to its original fulfillment value if the promise is
117 instead fulfilled.
118 # Longer version
120 my $new = $promise->then(undef, sub {...});
121 # Pass along the rejection reason
123 $promise->catch(sub {
124 my @reason = @_;
125 warn "Something went wrong: $reason[0]";
126 return @reason;
127 });
128 # Change the rejection reason
130 $promise->catch(sub {
131 my @reason = @_;
132 return "This is bad: $reason[0]";
133 });
134 clone
136 my $new = $promise->clone;
137 Return a new Mojo::Promise object cloned from this promise that is
139 still pending.
140 finally
142 my $new = $promise->finally(sub {...});
143 Appends a fulfillment and rejection handler to the promise, and returns
145 a new Mojo::Promise object resolving to the original fulfillment value
146 or rejection reason.
147 # Do something on fulfillment and rejection
149 $promise->finally(sub {
150 my @value_or_reason = @_;
151 say "We are done!";
152 });
153 race
155 my $new = Mojo::Promise->race(@promises);
156 Returns a new Mojo::Promise object that fulfills or rejects as soon as
158 one of the passed Mojo::Promise objects fulfills or rejects, with the
159 value or reason from that promise.
160 reject
162 my $new = Mojo::Promise->reject(@reason);
163 $promise = $promise->reject(@reason);
164 Build rejected Mojo::Promise object or reject the promise with one or
166 more rejection reasons.
167 # Longer version
169 my $promise = Mojo::Promise->new->reject(@reason);
170 resolve
172 my $new = Mojo::Promise->resolve(@value);
173 $promise = $promise->resolve(@value);
174 Build resolved Mojo::Promise object or resolve the promise with one or
176 more fulfillment values.
177 # Longer version
179 my $promise = Mojo::Promise->new->resolve(@value);
180 then
182 my $new = $promise->then(sub {...});
183 my $new = $promise->then(sub {...}, sub {...});
184 my $new = $promise->then(undef, sub {...});
185 Appends fulfillment and rejection handlers to the promise, and returns
187 a new Mojo::Promise object resolving to the return value of the called
188 handler.
189 # Pass along the fulfillment value or rejection reason
191 $promise->then(
192 sub {
193 my @value = @_;
194 say "The result is $value[0]";
195 return @value;
196 },
197 sub {
198 my @reason = @_;
199 warn "Something went wrong: $reason[0]";
200 return @reason;
201 }
202 );
203 # Change the fulfillment value or rejection reason
205 $promise->then(
206 sub {
207 my @value = @_;
208 return "This is good: $value[0]";
209 },
210 sub {
211 my @reason = @_;
212 return "This is bad: $reason[0]";
213 }
214 );
215 timeout
217 my $new = Mojo::Promise->timeout(5 => 'Timeout!');
218 $promise = $promise->timeout(5 => 'Timeout!');
219 $promise = $promise->timeout(5);
220 Create a new Mojo::Promise object with a timeout or attach a timeout to
222 an existing promise. The promise will be rejected after the given
223 amount of time in seconds with a reason, which defaults to "Promise
224 timeout". Note that this method is EXPERIMENTAL and might change
225 without warning!
226 wait
228 $promise->wait;
229 Start "ioloop" and stop it again once the promise has been fulfilled or
231 rejected, does nothing when "ioloop" is already running.
232
234 Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.
235perl v5.28.1 2019-01-29 Mojo::Promise(3)