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 $promise->resolve($tx) if !$err || $err->{code};
20 $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 new
155 my $promise = Mojo::Promise->new;
156 Construct a new Mojo::Promise object.
158 race
160 my $new = Mojo::Promise->race(@promises);
161 Returns a new Mojo::Promise object that fulfills or rejects as soon as
163 one of the passed Mojo::Promise objects fulfills or rejects, with the
164 value or reason from that promise.
165 reject
167 my $new = Mojo::Promise->reject(@reason);
168 $promise = $promise->reject(@reason);
169 Build rejected Mojo::Promise object or reject the promise with one or
171 more rejection reasons.
172 # Longer version
174 my $promise = Mojo::Promise->new->reject(@reason);
175 resolve
177 my $new = Mojo::Promise->resolve(@value);
178 $promise = $promise->resolve(@value);
179 Build resolved Mojo::Promise object or resolve the promise with one or
181 more fulfillment values.
182 # Longer version
184 my $promise = Mojo::Promise->new->resolve(@value);
185 then
187 my $new = $promise->then(sub {...});
188 my $new = $promise->then(sub {...}, sub {...});
189 my $new = $promise->then(undef, sub {...});
190 Appends fulfillment and rejection handlers to the promise, and returns
192 a new Mojo::Promise object resolving to the return value of the called
193 handler.
194 # Pass along the fulfillment value or rejection reason
196 $promise->then(
197 sub {
198 my @value = @_;
199 say "The result is $value[0]";
200 return @value;
201 },
202 sub {
203 my @reason = @_;
204 warn "Something went wrong: $reason[0]";
205 return @reason;
206 }
207 );
208 # Change the fulfillment value or rejection reason
210 $promise->then(
211 sub {
212 my @value = @_;
213 return "This is good: $value[0]";
214 },
215 sub {
216 my @reason = @_;
217 return "This is bad: $reason[0]";
218 }
219 );
220 wait
222 $promise->wait;
223 Start "ioloop" and stop it again once the promise has been fulfilled or
225 rejected, does nothing when "ioloop" is already running.
226
228 Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.
229perl v5.28.0 2018-10-19 Mojo::Promise(3)