1Promises::Deferred(3) User Contributed Perl DocumentationPromises::Deferred(3)
2
6 Promises::Deferred - An implementation of Promises in Perl
7
9 version 1.04
10
12 use Promises::Deferred;
13 sub fetch_it {
15 my ($uri) = @_;
16 my $d = Promises::Deferred->new;
17 http_get $uri => sub {
18 my ($body, $headers) = @_;
19 $headers->{Status} == 200
20 ? $d->resolve( decode_json( $body ) )
21 : $d->reject( $body )
22 };
23 $d->promise;
24 }
25
27 This class is meant only to be used by an implementor, meaning users of
28 your functions/classes/modules should always interact with the
29 associated promise object, but you (as the implementor) should use this
30 class. Think of this as the engine that drives the promises and the
31 promises as the steering wheels that control the direction taken.
32
34 Wherever a callback is mentioned below, it may take the form of a
35 coderef:
36 sub {...}
38 or an object which has been overloaded to allow calling as a coderef:
40 use AnyEvent;
42 my $cv = AnyEvent->cond_var;
44 fetch_it('http://metacpan.org')
45 ->then( sub { say "Success"; return @_ })
46 ->then( $cv, sub { $cv->croak(@_)} )
47
49 "new"
50 This will construct an instance, it takes no arguments.
51 "promise"
53 This will return a Promises::Promise that can be used as a handle
54 for this object. It will return a new one every time it is called.
55 "status"
57 This will return the status of the asynchronous operation, which
58 will be either 'in progress', 'resolved' or 'rejected'. These three
59 strings are also constants in this package ("IN_PROGRESS",
60 "RESOLVED" and "REJECTED" respectively), which can be used to check
61 these values.
62 "result"
64 This will return the result that has been passed to either the
65 "resolve" or "reject" methods. It will always return an ARRAY
66 reference since both "resolve" and "reject" take a variable number
67 of arguments.
68 "then( ?$callback, ?$error )"
70 This method is used to register two callbacks, both of which are
71 optional. The first $callback will be called on success and it will
72 be passed all the values that were sent to the corresponding call
73 to "resolve". The second, $error will be called on error, and will
74 be passed all the values that were sent to the corresponding
75 "reject". It should be noted that this method will always return a
76 new Promises::Promise instance so that you can chain things if you
77 like.
78 The success and error callbacks are wrapped in an "eval" block, so
80 you can safely call "die()" within a callback to signal an error
81 without killing your application. If an exception is caught, the
82 next link in the chain will be "reject"'ed and receive the
83 exception in @_.
84 If this is the last link in the chain, and there is no $error
86 callback, the error will be swallowed silently. You can still find
87 it by checking the "result" method, but no action will be taken. If
88 this is not the last link in the chain, and no $error is specified,
89 we will attempt to bubble the error to the next link in the chain.
90 This allows error handling to be consolidated at the point in the
91 chain where it makes the most sense.
92 "chain( @callbacks )"
94 Utility method that takes a list of callbacks and turn them into a
95 sequence of "then"s.
96 $promise->then( sub { ...code A... } )
98 ->then( sub { ...code B... } )
99 ->then( sub { ...code C... } );
100 # equivalent to
102 $promise->chain(
104 sub { ...code A... } ),
105 sub { ...code B... } ),
106 sub { ...code C... } ),
107 );
108 "catch( $error )"
110 This method registers a a single error callback. It is the
111 equivalent of calling:
112 $promise->then( sub {@_}, $error );
114 "done( $callback, ?$error )"
116 This method is used to register two callbacks, the first $callback
117 will be called on success and it will be passed all the values that
118 were sent to the corresponding call to "resolve". The second,
119 $error is optional and will be called on error, and will be passed
120 the all the values that were sent to the corresponding "reject".
121 Unlike the "then()" method, "done()" returns an empty list
123 specifically to break the chain and to avoid deep recursion. See
124 the explanation in Promises::Cookbook::Recursion.
125 Also unlike the "then()" method, "done()" callbacks are not wrapped
127 in an "eval" block, so calling "die()" is not safe. What will
128 happen if a "done" callback calls "die()" depends on which event
129 loop you are running: the pure Perl AnyEvent::Loop will throw an
130 exception, while EV and Mojo::IOLoop will warn and continue
131 running.
132 "finally( $callback )"
134 This method is like the "finally" keyword in a "try"/"catch" block.
135 It will execute regardless of whether the promise has been resolved
136 or rejected. Typically it is used to clean up resources, like
137 closing open files etc. It returns a Promises::Promise and so can
138 be chained. The return value is discarded and the success or
139 failure of the "finally" callback will have no effect on promises
140 further down the chain.
141 "timeout( $seconds )"
143 For asynchronous backend, returns a new promise that either takes
144 on the result of the current promise or is rejected after the given
145 delay, whichever comes first.
146 The default synchronous backend does not implement a timer
148 function. The method, in that case, returns a chained promise that
149 carries over the resolution of the current promise and emits a
150 warning.
151 "resolve( @args )"
153 This is the method to call upon the successful completion of your
154 asynchronous operation, meaning typically you would call this
155 within the callback that you gave to the asynchronous
156 function/method. It takes an arbitrary list of arguments and
157 captures them as the "result" of this promise (so obviously they
158 can be retrieved with the "result" method).
159 "reject( @args )"
161 This is the method to call when an error occurs during your
162 asynchronous operation, meaning typically you would call this
163 within the callback that you gave to the asynchronous
164 function/method. It takes an arbitrary list of arguments and
165 captures them as the "result" of this promise (so obviously they
166 can be retrieved with the "result" method).
167 "is_in_progress"
169 This is a predicate method against the status value, it returns
170 true if the status is "IN_PROGRESS".
171 "is_resolved"
173 This is a predicate method against the status value, it returns
174 true if the status is "RESOLVED".
175 "is_rejected"
177 This is a predicate method against the status value, it returns
178 true if the status is "REJECTED".
179 "is_done"
181 This is a predicate method against the status value, it returns
182 true if the status is either "RESOLVED" or "REJECTED".
183 "is_unfulfilled"
185 This is a predicate method against the status value, it returns
186 true if the status is still "IN_PROGRESS".
187 "is_fulfilled"
189 This is a predicate method against the status value, it returns
190 true if the status is "RESOLVED" or if the status is "RESOLVING".
191 "is_failed"
193 This is a predicate method against the status value, it returns
194 true of the status is "REJECTED" or if the status if "REJECTING".
195
197 Stevan Little <stevan.little@iinteractive.com>
198
200 This software is copyright (c) 2020, 2019, 2017, 2014, 2012 by Infinity
201 Interactive, Inc.
202 This is free software; you can redistribute it and/or modify it under
204 the same terms as the Perl 5 programming language system itself.
205perl v5.36.0 2022-07-22 Promises::Deferred(3)