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 specifically
123 to break the chain and to avoid deep recursion. See the
124 explanation in Promises::Cookbook::Recursion.
125 Also unlike the then() method, done() callbacks are not wrapped in
127 an "eval" block, so calling die() is not safe. What will happen if
128 a "done" callback calls die() depends on which event loop you are
129 running: the pure Perl AnyEvent::Loop will throw an exception,
130 while EV and Mojo::IOLoop will warn and continue running.
131 finally( $callback )
133 This method is like the "finally" keyword in a "try"/"catch" block.
134 It will execute regardless of whether the promise has been resolved
135 or rejected. Typically it is used to clean up resources, like
136 closing open files etc. It returns a Promises::Promise and so can
137 be chained. The return value is discarded and the success or
138 failure of the "finally" callback will have no effect on promises
139 further down the chain.
140 timeout( $seconds )
142 For asynchronous backend, returns a new promise that either takes
143 on the result of the current promise or is rejected after the given
144 delay, whichever comes first.
145 The default synchronous backend does not implement a timer
147 function. The method, in that case, returns a chained promise that
148 carries over the resolution of the current promise and emits a
149 warning.
150 resolve( @args )
152 This is the method to call upon the successful completion of your
153 asynchronous operation, meaning typically you would call this
154 within the callback that you gave to the asynchronous
155 function/method. It takes an arbitrary list of arguments and
156 captures them as the "result" of this promise (so obviously they
157 can be retrieved with the "result" method).
158 reject( @args )
160 This is the method to call when an error occurs during your
161 asynchronous operation, meaning typically you would call this
162 within the callback that you gave to the asynchronous
163 function/method. It takes an arbitrary list of arguments and
164 captures them as the "result" of this promise (so obviously they
165 can be retrieved with the "result" method).
166 "is_in_progress"
168 This is a predicate method against the status value, it returns
169 true if the status is "IN_PROGRESS".
170 "is_resolved"
172 This is a predicate method against the status value, it returns
173 true if the status is "RESOLVED".
174 "is_rejected"
176 This is a predicate method against the status value, it returns
177 true if the status is "REJECTED".
178 "is_done"
180 This is a predicate method against the status value, it returns
181 true if the status is either "RESOLVED" or "REJECTED".
182 "is_unfulfilled"
184 This is a predicate method against the status value, it returns
185 true if the status is still "IN_PROGRESS".
186 "is_fulfilled"
188 This is a predicate method against the status value, it returns
189 true if the status is "RESOLVED" or if the status is "RESOLVING".
190 "is_failed"
192 This is a predicate method against the status value, it returns
193 true of the status is "REJECTED" or if the status if "REJECTING".
194
196 Stevan Little <stevan.little@iinteractive.com>
197
199 This software is copyright (c) 2020, 2019, 2017, 2014, 2012 by Infinity
200 Interactive, Inc.
201 This is free software; you can redistribute it and/or modify it under
203 the same terms as the Perl 5 programming language system itself.
204perl v5.36.0 2023-01-20 Promises::Deferred(3)