1Promises::Deferred(3) User Contributed Perl DocumentationPromises::Deferred(3)
2
3
4

NAME

6       Promises::Deferred - An implementation of Promises in Perl
7

VERSION

9       version 1.04
10

SYNOPSIS

12         use Promises::Deferred;
13
14         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

DESCRIPTION

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

CALLBACKS

34       Wherever a callback is mentioned below, it may take the form of a
35       coderef:
36
37           sub {...}
38
39       or an object which has been overloaded to allow calling as a coderef:
40
41           use AnyEvent;
42
43           my $cv = AnyEvent->cond_var;
44           fetch_it('http://metacpan.org')
45               ->then( sub { say "Success"; return @_ })
46               ->then( $cv, sub { $cv->croak(@_)} )
47

METHODS

49       "new"
50           This will construct an instance, it takes no arguments.
51
52       "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
56       "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
63       "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
69       "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
79           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
85           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
93       "chain( @callbacks )"
94           Utility method that takes a list of callbacks and turn them into a
95           sequence of "then"s.
96
97               $promise->then( sub { ...code A... } )
98                       ->then( sub { ...code B... } )
99                       ->then( sub { ...code C... } );
100
101               # equivalent to
102
103               $promise->chain(
104                   sub { ...code A... } ),
105                   sub { ...code B... } ),
106                   sub { ...code C... } ),
107               );
108
109       "catch( $error )"
110           This method registers a a single error callback.  It is the
111           equivalent of calling:
112
113               $promise->then( sub {@_}, $error );
114
115       "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
122           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
126           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
133       "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
142       "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
147           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
152       "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
160       "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
168       "is_in_progress"
169           This is a predicate method against the status value, it returns
170           true if the status is "IN_PROGRESS".
171
172       "is_resolved"
173           This is a predicate method against the status value, it returns
174           true if the status is "RESOLVED".
175
176       "is_rejected"
177           This is a predicate method against the status value, it returns
178           true if the status is "REJECTED".
179
180       "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
184       "is_unfulfilled"
185           This is a predicate method against the status value, it returns
186           true if the status is still "IN_PROGRESS".
187
188       "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
192       "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

AUTHOR

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
203       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.
205
206
207
208perl v5.36.0                      2022-07-22             Promises::Deferred(3)
Impressum