File Coverage

blib/lib/Future.pm
Criterion Covered Total %
statement 79 108 73.1
branch 17 24 70.8
condition 16 30 53.3
subroutine 22 40 55.0
pod 1 1 100.0
total 135 203 66.5


line stmt bran cond sub pod time code
1             # You may distribute under the terms of either the GNU General Public License
2             # or the Artistic License (the same terms as Perl itself)
3             #
4             # (C) Paul Evans, 2011-2022 -- leonerd@leonerd.org.uk
5              
6             package Future;
7              
8 34     34   2076464 use v5.10;
  34         180  
9 34     34   174 use strict;
  34         73  
  34         681  
10 34     34   158 use warnings;
  34         63  
  34         886  
11 34     34   163 no warnings 'recursion'; # Disable the "deep recursion" warning
  34         55  
  34         5501  
12              
13             our $VERSION = '0.48_003';
14              
15             # we are not overloaded, but we want to check if other objects are
16             require overload;
17              
18             require Future::Exception;
19              
20             our @CARP_NOT = qw( Future::Utils );
21              
22             BEGIN {
23 34 50 66 34   280 if( !$ENV{PERL_FUTURE_NO_XS} and eval { require Future::XS } ) {
  12         1797  
24 0         0 our @ISA = qw( Future::XS );
25 0         0 *DEBUG = \&Future::XS::DEBUG;
26             }
27             else {
28 34         14344 require Future::PP;
29 34         447 our @ISA = qw( Future::PP );
30 34         1841 *DEBUG = \&Future::PP::DEBUG;
31             }
32             }
33              
34             our $TIMES = DEBUG || $ENV{PERL_FUTURE_TIMES};
35              
36             # All of the methods provided in this file actually live in Future::_base::
37             # which is supplied as a base class for actual Future::PP and Future::XS to
38             # use.
39             package
40             Future::_base;
41              
42 34     34   261 use Scalar::Util qw( blessed );
  34         60  
  34         1768  
43 34     34   183 use B qw( svref_2object );
  34         51  
  34         1467  
44 34     34   167 use Time::HiRes qw( tv_interval );
  34         56  
  34         234  
45              
46             =head1 NAME
47              
48             C - represent an operation awaiting completion
49              
50             =head1 SYNOPSIS
51              
52             my $future = Future->new;
53              
54             perform_some_operation(
55             on_complete => sub {
56             $future->done( @_ );
57             }
58             );
59              
60             $future->on_ready( sub {
61             say "The operation is complete";
62             } );
63              
64             =head1 DESCRIPTION
65              
66             A C object represents an operation that is currently in progress, or
67             has recently completed. It can be used in a variety of ways to manage the flow
68             of control, and data, through an asynchronous program.
69              
70             Some futures represent a single operation and are explicitly marked as ready
71             by calling the C or C methods. These are called "leaf" futures
72             here, and are returned by the C constructor.
73              
74             Other futures represent a collection of sub-tasks, and are implicitly marked
75             as ready depending on the readiness of their component futures as required.
76             These are called "convergent" futures here as they converge control and
77             data-flow back into one place. These are the ones returned by the various
78             C and C constructors.
79              
80             It is intended that library functions that perform asynchronous operations
81             would use future objects to represent outstanding operations, and allow their
82             calling programs to control or wait for these operations to complete. The
83             implementation and the user of such an interface would typically make use of
84             different methods on the class. The methods below are documented in two
85             sections; those of interest to each side of the interface.
86              
87             It should be noted however, that this module does not in any way provide an
88             actual mechanism for performing this asynchronous activity; it merely provides
89             a way to create objects that can be used for control and data flow around
90             those operations. It allows such code to be written in a neater,
91             forward-reading manner, and simplifies many common patterns that are often
92             involved in such situations.
93              
94             See also L which contains useful loop-constructing functions,
95             to run a future-returning function repeatedly in a loop.
96              
97             Unless otherwise noted, the following methods require at least version
98             I<0.08>.
99              
100             =head2 FAILURE CATEGORIES
101              
102             While not directly required by C or its related modules, a growing
103             convention of C-using code is to encode extra semantics in the
104             arguments given to the C method, to represent different kinds of
105             failure.
106              
107             The convention is that after the initial message string as the first required
108             argument (intended for display to humans), the second argument is a short
109             lowercase string that relates in some way to the kind of failure that
110             occurred. Following this is a list of details about that kind of failure,
111             whose exact arrangement or structure are determined by the failure category.
112             For example, L and L use this convention to
113             indicate at what stage a given HTTP request has failed:
114              
115             ->fail( $message, http => ... ) # an HTTP-level error during protocol
116             ->fail( $message, connect => ... ) # a TCP-level failure to connect a
117             # socket
118             ->fail( $message, resolve => ... ) # a resolver (likely DNS) failure
119             # to resolve a hostname
120              
121             By following this convention, a module remains consistent with other
122             C-based modules, and makes it easy for program logic to gracefully
123             handle and manage failures by use of the C method.
124              
125             =head2 SUBCLASSING
126              
127             This class easily supports being subclassed to provide extra behavior, such as
128             giving the C method the ability to block and wait for completion. This
129             may be useful to provide C subclasses with event systems, or similar.
130              
131             Each method that returns a new future object will use the invocant to
132             construct its return value. If the constructor needs to perform per-instance
133             setup it can override the C method, and take context from the given
134             instance.
135              
136             sub new
137             {
138             my $proto = shift;
139             my $self = $proto->SUPER::new;
140              
141             if( ref $proto ) {
142             # Prototype was an instance
143             }
144             else {
145             # Prototype was a class
146             }
147              
148             return $self;
149             }
150              
151             If an instance overrides the L method, this will be called by C
152             and C if the instance is still pending.
153              
154             In most cases this should allow future-returning modules to be used as if they
155             were blocking call/return-style modules, by simply appending a C call to
156             the function or method calls.
157              
158             my ( $results, $here ) = future_returning_function( @args )->get;
159              
160             =head2 DEBUGGING
161              
162             By the time a C object is destroyed, it ought to have been completed
163             or cancelled. By enabling debug tracing of objects, this fact can be checked.
164             If a future object is destroyed without having been completed or cancelled, a
165             warning message is printed.
166              
167             $ PERL_FUTURE_DEBUG=1 perl -MFuture -E 'my $f = Future->new'
168             Future=HASH(0xaa61f8) was constructed at -e line 1 and was lost near -e line 0 before it was ready.
169              
170             Note that due to a limitation of perl's C function within a C
171             destructor method, the exact location of the leak cannot be accurately
172             determined. Often the leak will occur due to falling out of scope by returning
173             from a function; in this case the leak location may be reported as being the
174             line following the line calling that function.
175              
176             $ PERL_FUTURE_DEBUG=1 perl -MFuture
177             sub foo {
178             my $f = Future->new;
179             }
180              
181             foo();
182             print "Finished\n";
183              
184             Future=HASH(0x14a2220) was constructed at - line 2 and was lost near - line 6 before it was ready.
185             Finished
186              
187             A warning is also printed in debug mode if a C object is destroyed
188             that completed with a failure, but the object believes that failure has not
189             been reported anywhere.
190              
191             $ PERL_FUTURE_DEBUG=1 perl -Mblib -MFuture -E 'my $f = Future->fail("Oops")'
192             Future=HASH(0xac98f8) was constructed at -e line 1 and was lost near -e line 0 with an unreported failure of: Oops
193              
194             Such a failure is considered reported if the C or C methods are
195             called on it, or it had at least one C or C callback, or
196             its failure is propagated to another C instance (by a sequencing or
197             converging method).
198              
199             =head2 Future::AsyncAwait::Awaitable ROLE
200              
201             Since version 0.43 this module provides the L
202             API. Subclass authors should note that several of the API methods are provided
203             by special optimised internal methods, which may require overriding in your
204             subclass if your internals are different from that of this module.
205              
206             =cut
207              
208             =head1 CONSTRUCTORS
209              
210             =cut
211              
212             =head2 new
213              
214             $future = Future->new
215              
216             $future = $orig->new
217              
218             Returns a new C instance to represent a leaf future. It will be marked
219             as ready by any of the C, C, or C methods. It can be
220             called either as a class method, or as an instance method. Called on an
221             instance it will construct another in the same class, and is useful for
222             subclassing.
223              
224             This constructor would primarily be used by implementations of asynchronous
225             interfaces.
226              
227             =cut
228              
229 0     0   0 *AWAIT_CLONE = sub { shift->new };
230              
231             # Useful for identifying CODE references
232             sub CvNAME_FILE_LINE
233             {
234 3     3   7 my ( $code ) = @_;
235 3         20 my $cv = svref_2object( $code );
236              
237 3         47 my $name = join "::", $cv->STASH->NAME, $cv->GV->NAME;
238 3 50       25 return $name unless $cv->GV->NAME eq "__ANON__";
239              
240             # $cv->GV->LINE isn't reliable, as outside of perl -d mode all anon CODE
241             # in the same file actually shares the same GV. :(
242             # Walk the optree looking for the first COP
243 3         19 my $cop = $cv->START;
244 3   33     24 $cop = $cop->next while $cop and ref $cop ne "B::COP" and ref $cop ne "B::NULL";
      33        
245              
246 3 50       11 return $cv->GV->NAME if ref $cop eq "B::NULL";
247 3         50 sprintf "%s(%s line %d)", $cv->GV->NAME, $cop->file, $cop->line;
248             }
249              
250             =head2 done I<(class method)>
251              
252             =head2 fail I<(class method)>
253              
254             $future = Future->done( @values )
255              
256             $future = Future->fail( $exception, $category, @details )
257              
258             I
259              
260             Shortcut wrappers around creating a new C then immediately marking it
261             as done or failed.
262              
263             =head2 wrap
264              
265             $future = Future->wrap( @values )
266              
267             I
268              
269             If given a single argument which is already a C reference, this will
270             be returned unmodified. Otherwise, returns a new C instance that is
271             already complete, and will yield the given values.
272              
273             This will ensure that an incoming argument is definitely a C, and may
274             be useful in such cases as adapting synchronous code to fit asynchronous
275             libraries driven by C.
276              
277             =cut
278              
279             sub wrap
280             {
281 2     2   8 my $class = shift;
282 2         4 my @values = @_;
283              
284 2 100 66     20 if( @values == 1 and blessed $values[0] and $values[0]->isa( __PACKAGE__ ) ) {
      66        
285 1         4 return $values[0];
286             }
287             else {
288 1         3 return $class->done( @values );
289             }
290             }
291              
292             =head2 call
293              
294             $future = Future->call( \&code, @args )
295              
296             I
297              
298             A convenient wrapper for calling a C reference that is expected to
299             return a future. In normal circumstances is equivalent to
300              
301             $future = $code->( @args )
302              
303             except that if the code throws an exception, it is wrapped in a new immediate
304             fail future. If the return value from the code is not a blessed C
305             reference, an immediate fail future is returned instead to complain about this
306             fact.
307              
308             =cut
309              
310             sub call
311             {
312 107     107   579 my $class = shift;
313 107         168 my ( $code, @args ) = @_;
314              
315 107         118 my $f;
316 107 100       151 eval { $f = $code->( @args ); 1 } or $f = $class->fail( $@ );
  107         199  
  96         214  
317 107 100 66     537 blessed $f and $f->isa( "Future" ) or $f = $class->fail( "Expected " . CvNAME_FILE_LINE($code) . " to return a Future" );
318              
319 107         292 return $f;
320             }
321              
322             =head1 METHODS
323              
324             As there are a lare number of methods on this class, they are documented here
325             in several sections.
326              
327             =cut
328              
329             =head1 INSPECTION METHODS
330              
331             The following methods query the internal state of a Future instance without
332             modifying it or otherwise causing side-effects.
333              
334             =cut
335              
336             =head2 is_ready
337              
338             $ready = $future->is_ready
339              
340             Returns true on a leaf future if a result has been provided to the C
341             method, failed using the C method, or cancelled using the C
342             method.
343              
344             Returns true on a convergent future if it is ready to yield a result,
345             depending on its component futures.
346              
347             =cut
348              
349 0     0   0 *AWAIT_IS_READY = sub { shift->is_ready };
350              
351             =head2 is_done
352              
353             $done = $future->is_done
354              
355             Returns true on a future if it is ready and completed successfully. Returns
356             false if it is still pending, failed, or was cancelled.
357              
358             =cut
359              
360             =head2 is_failed
361              
362             $failed = $future->is_failed
363              
364             I
365              
366             Returns true on a future if it is ready and it failed. Returns false if it is
367             still pending, completed successfully, or was cancelled.
368              
369             =cut
370              
371             =head2 is_cancelled
372              
373             $cancelled = $future->is_cancelled
374              
375             Returns true if the future has been cancelled by C.
376              
377             =cut
378              
379 0     0   0 *AWAIT_IS_CANCELLED = sub { shift->is_cancelled };
380              
381             =head2 state
382              
383             $str = $future->state
384              
385             I
386              
387             Returns a string describing the state of the future, as one of the three
388             states named above; namely C, C or C, or C
389             if it is none of these.
390              
391             =cut
392              
393             =head1 IMPLEMENTATION METHODS
394              
395             These methods would primarily be used by implementations of asynchronous
396             interfaces.
397              
398             =cut
399              
400             =head2 done
401              
402             $future->done( @result )
403              
404             Marks that the leaf future is now ready, and provides a list of values as a
405             result. (The empty list is allowed, and still indicates the future as ready).
406             Cannot be called on a convergent future.
407              
408             If the future is already cancelled, this request is ignored. If the future is
409             already complete with a result or a failure, an exception is thrown.
410              
411             I this method is also available under the name
412             C.
413              
414             =cut
415              
416 1     1   487 *resolve = sub { shift->done( @_ ) };
417              
418             # TODO: For efficiency we can implement better versions of these as individual
419             # methods know which case is being invoked
420 0     0   0 *AWAIT_NEW_DONE = *AWAIT_DONE = sub { shift->done( @_ ) };
421              
422             =head2 fail
423              
424             $future->fail( $exception, $category, @details )
425              
426             Marks that the leaf future has failed, and provides an exception value. This
427             exception will be thrown by the C method if called.
428              
429             The exception must evaluate as a true value; false exceptions are not allowed.
430             A failure category name and other further details may be provided that will be
431             returned by the C method in list context.
432              
433             If the future is already cancelled, this request is ignored. If the future is
434             already complete with a result or a failure, an exception is thrown.
435              
436             If passed a L instance (i.e. an object previously thrown by
437             the C), the additional details will be preserved. This allows the
438             additional details to be transparently preserved by such code as
439              
440             ...
441             catch {
442             return Future->fail($@);
443             }
444              
445             I this method is also available under the name C.
446              
447             =cut
448              
449 1     1   5 *reject = sub { shift->fail( @_ ) };
450              
451             # TODO: For efficiency we can implement better versions of these as individual
452             # methods know which case is being invoked
453 0     0   0 *AWAIT_NEW_FAIL = *AWAIT_FAIL = sub { shift->fail( @_ ) };
454              
455             =head2 die
456              
457             $future->die( $message, $category, @details )
458              
459             I
460              
461             A convenient wrapper around C. If the exception is a non-reference that
462             does not end in a linefeed, its value will be extended by the file and line
463             number of the caller, similar to the logic that C uses.
464              
465             Returns the C<$future>.
466              
467             =cut
468              
469             sub die :method
470             {
471 1     1   12 my $self = shift;
472 1         3 my ( $exception, @more ) = @_;
473              
474 1 50 33     8 if( !ref $exception and $exception !~ m/\n$/ ) {
475 1         8 $exception .= sprintf " at %s line %d\n", (caller)[1,2];
476             }
477              
478 1         4 $self->fail( $exception, @more );
479             }
480              
481             =head2 on_cancel
482              
483             $future->on_cancel( $code )
484              
485             If the future is not yet ready, adds a callback to be invoked if the future is
486             cancelled by the C method. If the future is already ready the method
487             is ignored.
488              
489             If the future is later cancelled, the callbacks will be invoked in the reverse
490             order to that in which they were registered.
491              
492             $on_cancel->( $future )
493              
494             If passed another C instance, the passed instance will be cancelled
495             when the original future is cancelled. In this case, the reference is only
496             strongly held while the target future remains pending. If it becomes ready,
497             then there is no point trying to cancel it, and so it is removed from the
498             originating future's cancellation list.
499              
500             =cut
501              
502 0     0   0 *AWAIT_ON_CANCEL = *AWAIT_CHAIN_CANCEL = sub { shift->on_cancel( @_ ) };
503              
504             =head1 USER METHODS
505              
506             These methods would primarily be used by users of asynchronous interfaces, on
507             objects returned by such an interface.
508              
509             =cut
510              
511             =head2 on_ready
512              
513             $future->on_ready( $code )
514              
515             If the future is not yet ready, adds a callback to be invoked when the future
516             is ready. If the future is already ready, invokes it immediately.
517              
518             In either case, the callback will be passed the future object itself. The
519             invoked code can then obtain the list of results by calling the C method.
520              
521             $on_ready->( $future )
522              
523             If passed another C instance, the passed instance will have its
524             C, C or C methods invoked when the original future
525             completes successfully, fails, or is cancelled respectively.
526              
527             Returns the C<$future>.
528              
529             =cut
530              
531 0     0   0 *AWAIT_ON_READY = sub { shift->on_ready( @_ ) };
532              
533             =head2 result
534              
535             @result = $future->result
536              
537             $result = $future->result
538              
539             I
540              
541             If the future is ready and completed successfully, returns the list of
542             results that had earlier been given to the C method on a leaf future,
543             or the list of component futures it was waiting for on a convergent future. In
544             scalar context it returns just the first result value.
545              
546             If the future is ready but failed, this method raises as an exception the
547             failure that was given to the C method. If additional details were given
548             to the C method, an exception object is constructed to wrap them of type
549             L.
550              
551             If the future was cancelled or is not yet ready an exception is thrown.
552              
553             =cut
554              
555 0     0   0 *AWAIT_RESULT = *AWAIT_GET = sub { shift->result };
556              
557             =head2 get
558              
559             @result = $future->get
560              
561             $result = $future->get
562              
563             If the future is ready, returns the result or throws the failure exception as
564             per L.
565              
566             If it is not yet ready then L is invoked to wait for a ready state, and
567             the result returned as above.
568              
569             =cut
570              
571 0     0   0 *AWAIT_WAIT = sub { shift->get };
572              
573             =head2 await
574              
575             $f = $f->await
576              
577             I
578              
579             Blocks until the future instance is no longer pending.
580              
581             Returns the invocant future itself, so it is useful for chaining.
582              
583             Usually, calling code would either force the future using L, or use
584             either C chaining or C syntax to wait for results. This
585             method is useful in cases where the exception-throwing part of C is not
586             required, perhaps because other code will be testing the result using
587             L or similar.
588              
589             if( $f->await->is_done ) {
590             ...
591             }
592              
593             This method is intended for subclasses to override. The default implementation
594             will throw an exception if called on a still-pending instance.
595              
596             =cut
597              
598             =head2 block_until_ready
599              
600             $f = $f->block_until_ready
601              
602             I
603              
604             Now a synonym for L. New code should invoke C directly.
605              
606             =cut
607              
608             sub block_until_ready
609             {
610 0     0   0 my $self = shift;
611 0         0 return $self->await;
612             }
613              
614             =head2 unwrap
615              
616             @values = Future->unwrap( @values )
617              
618             I
619              
620             If given a single argument which is a C reference, this method will
621             call C on it and return the result. Otherwise, it returns the list of
622             values directly in list context, or the first value in scalar. Since it
623             involves an implicit blocking wait, this method can only be used on immediate
624             futures or subclasses that implement L.
625              
626             This will ensure that an outgoing argument is definitely not a C, and
627             may be useful in such cases as adapting synchronous code to fit asynchronous
628             libraries that return C instances.
629              
630             =cut
631              
632             sub unwrap
633             {
634 4     4   7 shift; # $class
635 4         6 my @values = @_;
636              
637 4 100 66     24 if( @values == 1 and blessed $values[0] and $values[0]->isa( __PACKAGE__ ) ) {
      66        
638 2         7 return $values[0]->get;
639             }
640             else {
641 2 100       7 return $values[0] if !wantarray;
642 1         5 return @values;
643             }
644             }
645              
646             =head2 on_done
647              
648             $future->on_done( $code )
649              
650             If the future is not yet ready, adds a callback to be invoked when the future
651             is ready, if it completes successfully. If the future completed successfully,
652             invokes it immediately. If it failed or was cancelled, it is not invoked at
653             all.
654              
655             The callback will be passed the result passed to the C method.
656              
657             $on_done->( @result )
658              
659             If passed another C instance, the passed instance will have its
660             C method invoked when the original future completes successfully.
661              
662             Returns the C<$future>.
663              
664             =cut
665              
666             =head2 failure
667              
668             $exception = $future->failure
669              
670             $exception, $category, @details = $future->failure
671              
672             If the future is ready, returns the exception passed to the C method or
673             C if the future completed successfully via the C method.
674              
675             If it is not yet ready then L is invoked to wait for a ready state.
676              
677             If called in list context, will additionally yield the category name and list
678             of the details provided to the C method.
679              
680             Because the exception value must be true, this can be used in a simple C
681             statement:
682              
683             if( my $exception = $future->failure ) {
684             ...
685             }
686             else {
687             my @result = $future->result;
688             ...
689             }
690              
691             =cut
692              
693             =head2 on_fail
694              
695             $future->on_fail( $code )
696              
697             If the future is not yet ready, adds a callback to be invoked when the future
698             is ready, if it fails. If the future has already failed, invokes it
699             immediately. If it completed successfully or was cancelled, it is not invoked
700             at all.
701              
702             The callback will be passed the exception and other details passed to the
703             C method.
704              
705             $on_fail->( $exception, $category, @details )
706              
707             If passed another C instance, the passed instance will have its
708             C method invoked when the original future fails.
709              
710             To invoke a C method on a future when another one fails, use a CODE
711             reference:
712              
713             $future->on_fail( sub { $f->done( @_ ) } );
714              
715             Returns the C<$future>.
716              
717             =cut
718              
719             =head2 cancel
720              
721             $future->cancel
722              
723             Requests that the future be cancelled, immediately marking it as ready. This
724             will invoke all of the code blocks registered by C, in the reverse
725             order. When called on a convergent future, all its component futures are also
726             cancelled. It is not an error to attempt to cancel a future that is already
727             complete or cancelled; it simply has no effect.
728              
729             Returns the C<$future>.
730              
731             =cut
732              
733             =head1 SEQUENCING METHODS
734              
735             The following methods all return a new future to represent the combination of
736             its invocant followed by another action given by a code reference. The
737             combined activity waits for the first future to be ready, then may invoke the
738             code depending on the success or failure of the first, or may run it
739             regardless. The returned sequence future represents the entire combination of
740             activity.
741              
742             The invoked code could return a future, or a result directly.
743              
744             I if a non-future result is returned it will be wrapped
745             in a new immediate Future instance. This behaviour can be disabled by setting
746             the C environment variable to a true value at compiletime:
747              
748             $ PERL_FUTURE_STRICT=1 perl ...
749              
750             The combined future will then wait for the result of this second one. If the
751             combinined future is cancelled, it will cancel either the first future or the
752             second, depending whether the first had completed. If the code block throws an
753             exception instead of returning a value, the sequence future will fail with
754             that exception as its message and no further values.
755              
756             Note that since the code is invoked in scalar context, you cannot directly
757             return a list of values this way. Any list-valued results must be done by
758             returning a C instance.
759              
760             sub {
761             ...
762             return Future->done( @results );
763             }
764              
765             As it is always a mistake to call these sequencing methods in void context and lose the
766             reference to the returned future (because exception/error handling would be
767             silently dropped), this method warns in void context.
768              
769             =cut
770              
771             =head2 then
772              
773             $future = $f1->then( \&done_code )
774              
775             I
776              
777             Returns a new sequencing C that runs the code if the first succeeds.
778             Once C<$f1> succeeds the code reference will be invoked and is passed the list
779             of results. It should return a future, C<$f2>. Once C<$f2> completes the
780             sequence future will then be marked as complete with whatever result C<$f2>
781             gave. If C<$f1> fails then the sequence future will immediately fail with the
782             same failure and the code will not be invoked.
783              
784             $f2 = $done_code->( @result )
785              
786             =head2 else
787              
788             $future = $f1->else( \&fail_code )
789              
790             I
791              
792             Returns a new sequencing C that runs the code if the first fails. Once
793             C<$f1> fails the code reference will be invoked and is passed the failure and
794             other details. It should return a future, C<$f2>. Once C<$f2> completes the
795             sequence future will then be marked as complete with whatever result C<$f2>
796             gave. If C<$f1> succeeds then the sequence future will immediately succeed
797             with the same result and the code will not be invoked.
798              
799             $f2 = $fail_code->( $exception, $category, @details )
800              
801             =head2 then I<(2 arguments)>
802              
803             $future = $f1->then( \&done_code, \&fail_code )
804              
805             The C method can also be passed the C<$fail_code> block as well, giving
806             a combination of C and C behaviour.
807              
808             This operation is similar to those provided by other future systems, such as
809             Javascript's Q or Promises/A libraries.
810              
811             =cut
812              
813             =head2 catch
814              
815             $future = $f1->catch(
816             name => \&code,
817             name => \&code, ...
818             )
819              
820             I
821              
822             Returns a new sequencing C that behaves like an C call which
823             dispatches to a choice of several alternative handling functions depending on
824             the kind of failure that occurred. If C<$f1> fails with a category name (i.e.
825             the second argument to the C call) which exactly matches one of the
826             string names given, then the corresponding code is invoked, being passed the
827             same arguments as a plain C call would take, and is expected to return a
828             C in the same way.
829              
830             $f2 = $code->( $exception, $category, @details )
831              
832             If C<$f1> does not fail, fails without a category name at all, or fails with a
833             category name that does not match any given to the C method, then the
834             returned sequence future immediately completes with the same result, and no
835             block of code is invoked.
836              
837             If passed an odd-sized list, the final argument gives a function to invoke on
838             failure if no other handler matches.
839              
840             $future = $f1->catch(
841             name => \&code, ...
842             \&fail_code,
843             )
844              
845             This feature is currently still a work-in-progress. It currently can only cope
846             with category names that are literal strings, which are all distinct. A later
847             version may define other kinds of match (e.g. regexp), may specify some sort
848             of ordering on the arguments, or any of several other semantic extensions. For
849             more detail on the ongoing design, see
850             L.
851              
852             =head2 then I<(multiple arguments)>
853              
854             $future = $f1->then( \&done_code, @catch_list, \&fail_code )
855              
856             I
857              
858             The C method can be passed an even-sized list inbetween the
859             C<$done_code> and the C<$fail_code>, with the same meaning as the C
860             method.
861              
862             =cut
863              
864             =head2 transform
865              
866             $future = $f1->transform( %args )
867              
868             Returns a new sequencing C that wraps the one given as C<$f1>. With no
869             arguments this will be a trivial wrapper; C<$future> will complete or fail
870             when C<$f1> does, and C<$f1> will be cancelled when C<$future> is.
871              
872             By passing the following named arguments, the returned C<$future> can be made
873             to behave differently to C<$f1>:
874              
875             =over 8
876              
877             =item done => CODE
878              
879             Provides a function to use to modify the result of a successful completion.
880             When C<$f1> completes successfully, the result of its C method is passed
881             into this function, and whatever it returns is passed to the C method of
882             C<$future>
883              
884             =item fail => CODE
885              
886             Provides a function to use to modify the result of a failure. When C<$f1>
887             fails, the result of its C method is passed into this function, and
888             whatever it returns is passed to the C method of C<$future>.
889              
890             =back
891              
892             =cut
893              
894             sub transform
895             {
896 6     6   24 my $self = shift;
897 6         11 my %args = @_;
898              
899 6         8 my $xfrm_done = $args{done};
900 6         9 my $xfrm_fail = $args{fail};
901              
902             return $self->then_with_f(
903             sub {
904 3     3   6 my ( $f, @result ) = @_;
905 3 50       11 return $f unless $xfrm_done;
906 3         16 return $f->new->done( $xfrm_done->( @result ) );
907             },
908             sub {
909 1     1   2 my ( $f, @failure ) = @_;
910 1 50       2 return $f unless $xfrm_fail;
911 1         3 return $f->new->fail( $xfrm_fail->( @failure ) );
912             }
913 6         30 );
914             }
915              
916             =head2 then_with_f
917              
918             $future = $f1->then_with_f( ... )
919              
920             I
921              
922             Returns a new sequencing C that behaves like C, but also passes
923             the original future, C<$f1>, to any functions it invokes.
924              
925             $f2 = $done_code->( $f1, @result )
926             $f2 = $catch_code->( $f1, $category, @details )
927             $f2 = $fail_code->( $f1, $category, @details )
928              
929             This is useful for conditional execution cases where the code block may just
930             return the same result of the original future. In this case it is more
931             efficient to return the original future itself.
932              
933             =cut
934              
935             =head2 then_done
936              
937             =head2 then_fail
938              
939             $future = $f->then_done( @result )
940              
941             $future = $f->then_fail( $exception, $category, @details )
942              
943             I
944              
945             Convenient shortcuts to returning an immediate future from a C block,
946             when the result is already known.
947              
948             =cut
949              
950             sub then_done
951             {
952 0     0   0 my $self = shift;
953 0         0 my ( @result ) = @_;
954 0     0   0 return $self->then_with_f( sub { return $_[0]->new->done( @result ) } );
  0         0  
955             }
956              
957             sub then_fail
958             {
959 0     0   0 my $self = shift;
960 0         0 my ( @failure ) = @_;
961 0     0   0 return $self->then_with_f( sub { return $_[0]->new->fail( @failure ) } );
  0         0  
962             }
963              
964             =head2 else_with_f
965              
966             $future = $f1->else_with_f( \&code )
967              
968             I
969              
970             Returns a new sequencing C that runs the code if the first fails.
971             Identical to C, except that the code reference will be passed both the
972             original future, C<$f1>, and its exception and other details.
973              
974             $f2 = $code->( $f1, $exception, $category, @details )
975              
976             This is useful for conditional execution cases where the code block may just
977             return the same result of the original future. In this case it is more
978             efficient to return the original future itself.
979              
980             =cut
981              
982             =head2 else_done
983              
984             =head2 else_fail
985              
986             $future = $f->else_done( @result )
987              
988             $future = $f->else_fail( $exception, $category, @details )
989              
990             I
991              
992             Convenient shortcuts to returning an immediate future from a C block,
993             when the result is already known.
994              
995             =cut
996              
997             sub else_done
998             {
999 0     0   0 my $self = shift;
1000 0         0 my ( @result ) = @_;
1001 0     0   0 return $self->else_with_f( sub { return $_[0]->new->done( @result ) } );
  0         0  
1002             }
1003              
1004             sub else_fail
1005             {
1006 0     0   0 my $self = shift;
1007 0         0 my ( @failure ) = @_;
1008 0     0   0 return $self->else_with_f( sub { return $_[0]->new->fail( @failure ) } );
  0         0  
1009             }
1010              
1011             =head2 catch_with_f
1012              
1013             $future = $f1->catch_with_f( ... )
1014              
1015             I
1016              
1017             Returns a new sequencing C that behaves like C, but also passes
1018             the original future, C<$f1>, to any functions it invokes.
1019              
1020             =cut
1021              
1022             =head2 followed_by
1023              
1024             $future = $f1->followed_by( \&code )
1025              
1026             Returns a new sequencing C that runs the code regardless of success or
1027             failure. Once C<$f1> is ready the code reference will be invoked and is passed
1028             one argument, C<$f1>. It should return a future, C<$f2>. Once C<$f2> completes
1029             the sequence future will then be marked as complete with whatever result
1030             C<$f2> gave.
1031              
1032             $f2 = $code->( $f1 )
1033              
1034             =cut
1035              
1036             =head2 without_cancel
1037              
1038             $future = $f1->without_cancel
1039              
1040             I
1041              
1042             Returns a new sequencing C that will complete with the success or
1043             failure of the original future, but if cancelled, will not cancel the
1044             original. This may be useful if the original future represents an operation
1045             that is being shared among multiple sequences; cancelling one should not
1046             prevent the others from running too.
1047              
1048             Note that this only prevents cancel propagating from C<$future> to C<$f1>; if
1049             the original C<$f1> instance is cancelled then the returned C<$future> will
1050             have to be cancelled too.
1051              
1052             =cut
1053              
1054             =head2 retain
1055              
1056             $f = $f->retain
1057              
1058             I
1059              
1060             Creates a reference cycle which causes the future to remain in memory until
1061             it completes. Returns the invocant future.
1062              
1063             In normal situations, a C instance does not strongly hold a reference
1064             to other futures that it is feeding a result into, instead relying on that to
1065             be handled by application logic. This is normally fine because some part of
1066             the application will retain the top-level Future, which then strongly refers
1067             to each of its components down in a tree. However, certain design patterns,
1068             such as mixed Future-based and legacy callback-based API styles might end up
1069             creating Futures simply to attach callback functions to them. In that
1070             situation, without further attention, the Future may get lost due to having no
1071             strong references to it. Calling C<< ->retain >> on it creates such a
1072             reference which ensures it persists until it completes. For example:
1073              
1074             Future->needs_all( $fA, $fB )
1075             ->on_done( $on_done )
1076             ->on_fail( $on_fail )
1077             ->retain;
1078              
1079             =cut
1080              
1081             sub retain
1082             {
1083 3     3   2222 my $self = shift;
1084 3     3   31 return $self->on_ready( sub { undef $self } );
  3         17  
1085             }
1086              
1087             =head1 CONVERGENT FUTURES
1088              
1089             The following constructors all take a list of component futures, and return a
1090             new future whose readiness somehow depends on the readiness of those
1091             components. The first derived class component future will be used as the
1092             prototype for constructing the return value, so it respects subclassing
1093             correctly, or failing that a plain C.
1094              
1095             =cut
1096              
1097             =head2 wait_all
1098              
1099             $future = Future->wait_all( @subfutures )
1100              
1101             Returns a new C instance that will indicate it is ready once all of
1102             the sub future objects given to it indicate that they are ready, either by
1103             success, failure or cancellation. Its result will be a list of its component
1104             futures.
1105              
1106             When given an empty list this constructor returns a new immediately-done
1107             future.
1108              
1109             This constructor would primarily be used by users of asynchronous interfaces.
1110              
1111             =cut
1112              
1113             =head2 wait_any
1114              
1115             $future = Future->wait_any( @subfutures )
1116              
1117             Returns a new C instance that will indicate it is ready once any of
1118             the sub future objects given to it indicate that they are ready, either by
1119             success or failure. Any remaining component futures that are not yet ready
1120             will be cancelled. Its result will be the result of the first component future
1121             that was ready; either success or failure. Any component futures that are
1122             cancelled are ignored, apart from the final component left; at which point the
1123             result will be a failure.
1124              
1125             When given an empty list this constructor returns an immediately-failed
1126             future.
1127              
1128             This constructor would primarily be used by users of asynchronous interfaces.
1129              
1130             =cut
1131              
1132             =head2 needs_all
1133              
1134             $future = Future->needs_all( @subfutures )
1135              
1136             Returns a new C instance that will indicate it is ready once all of the
1137             sub future objects given to it indicate that they have completed successfully,
1138             or when any of them indicates that they have failed. If any sub future fails,
1139             then this will fail immediately, and the remaining subs not yet ready will be
1140             cancelled. Any component futures that are cancelled will cause an immediate
1141             failure of the result.
1142              
1143             If successful, its result will be a concatenated list of the results of all
1144             its component futures, in corresponding order. If it fails, its failure will
1145             be that of the first component future that failed. To access each component
1146             future's results individually, use C.
1147              
1148             When given an empty list this constructor returns a new immediately-done
1149             future.
1150              
1151             This constructor would primarily be used by users of asynchronous interfaces.
1152              
1153             =cut
1154              
1155             =head2 needs_any
1156              
1157             $future = Future->needs_any( @subfutures )
1158              
1159             Returns a new C instance that will indicate it is ready once any of
1160             the sub future objects given to it indicate that they have completed
1161             successfully, or when all of them indicate that they have failed. If any sub
1162             future succeeds, then this will succeed immediately, and the remaining subs
1163             not yet ready will be cancelled. Any component futures that are cancelled are
1164             ignored, apart from the final component left; at which point the result will
1165             be a failure.
1166              
1167             If successful, its result will be that of the first component future that
1168             succeeded. If it fails, its failure will be that of the last component future
1169             to fail. To access the other failures, use C.
1170              
1171             Normally when this future completes successfully, only one of its component
1172             futures will be done. If it is constructed with multiple that are already done
1173             however, then all of these will be returned from C. Users should
1174             be careful to still check all the results from C in that case.
1175              
1176             When given an empty list this constructor returns an immediately-failed
1177             future.
1178              
1179             This constructor would primarily be used by users of asynchronous interfaces.
1180              
1181             =cut
1182              
1183             =head1 METHODS ON CONVERGENT FUTURES
1184              
1185             The following methods apply to convergent (i.e. non-leaf) futures, to access
1186             the component futures stored by it.
1187              
1188             =cut
1189              
1190             =head2 pending_futures
1191              
1192             @f = $future->pending_futures
1193              
1194             =head2 ready_futures
1195              
1196             @f = $future->ready_futures
1197              
1198             =head2 done_futures
1199              
1200             @f = $future->done_futures
1201              
1202             =head2 failed_futures
1203              
1204             @f = $future->failed_futures
1205              
1206             =head2 cancelled_futures
1207              
1208             @f = $future->cancelled_futures
1209              
1210             Return a list of all the pending, ready, done, failed, or cancelled
1211             component futures. In scalar context, each will yield the number of such
1212             component futures.
1213              
1214             =cut
1215              
1216             =head1 SUBCLASSING METHODS
1217              
1218             These methods are not intended for end-users of C instances, but
1219             instead provided for authors of classes that subclass from C itself.
1220              
1221             =cut
1222              
1223             =head2 set_udata
1224              
1225             $future = $future->set_udata( $name, $value )
1226              
1227             Stores a Perl value within the instance, under the given name. Subclasses can
1228             use this to store extra data that the implementation may require.
1229              
1230             This is a safer version of attempting to use the C<$future> instance itself as
1231             a hash reference.
1232              
1233             =cut
1234              
1235             =head2 udata
1236              
1237             $value = $future->get_udata( $name )
1238              
1239             Returns a Perl value from the instance that was previously set with
1240             L.
1241              
1242             =cut
1243              
1244             =head1 TRACING METHODS
1245              
1246             =head2 set_label
1247              
1248             =head2 label
1249              
1250             $future = $future->set_label( $label )
1251              
1252             $label = $future->label
1253              
1254             I
1255              
1256             Chaining mutator and accessor for the label of the C. This should be a
1257             plain string value, whose value will be stored by the future instance for use
1258             in debugging messages or other tooling, or similar purposes.
1259              
1260             =cut
1261              
1262             =head2 btime
1263              
1264             =head2 rtime
1265              
1266             [ $sec, $usec ] = $future->btime
1267              
1268             [ $sec, $usec ] = $future->rtime
1269              
1270             I
1271              
1272             Accessors that return the tracing timestamps from the instance. These give the
1273             time the instance was constructed ("birth" time, C) and the time the
1274             result was determined (the "ready" time, C). Each result is returned as
1275             a two-element ARRAY ref, containing the epoch time in seconds and
1276             microseconds, as given by C.
1277              
1278             In order for these times to be captured, they have to be enabled by setting
1279             C<$Future::TIMES> to a true value. This is initialised true at the time the
1280             module is loaded if either C or C are
1281             set in the environment.
1282              
1283             =cut
1284              
1285             =head2 elapsed
1286              
1287             $sec = $future->elapsed
1288              
1289             I
1290              
1291             If both tracing timestamps are defined, returns the number of seconds of
1292             elapsed time between them as a floating-point number. If not, returns
1293             C.
1294              
1295             =cut
1296              
1297             sub elapsed
1298             {
1299 4     4   1029 my $self = shift;
1300 4 50 33     10 return undef unless defined( my $btime = $self->btime ) and
1301             defined( my $rtime = $self->rtime );
1302 4         39 return tv_interval( $self->btime, $self->rtime );
1303             }
1304              
1305             =head2 wrap_cb
1306              
1307             $cb = $future->wrap_cb( $operation_name, $cb )
1308              
1309             I
1310              
1311             I
1312             version.>
1313              
1314             This method is invoked internally by various methods that are about to save a
1315             callback CODE reference supplied by the user, to be invoked later. The default
1316             implementation simply returns the callback argument as-is; the method is
1317             provided to allow users to provide extra behaviour. This can be done by
1318             applying a method modifier of the C kind, so in effect add a chain of
1319             wrappers. Each wrapper can then perform its own wrapping logic of the
1320             callback. C<$operation_name> is a string giving the reason for which the
1321             callback is being saved; currently one of C, C, C
1322             or C; the latter being used for all the sequence-returning methods.
1323              
1324             This method is intentionally invoked only for CODE references that are being
1325             saved on a pending C instance to be invoked at some later point. It
1326             does not run for callbacks to be invoked on an already-complete instance. This
1327             is for performance reasons, where the intended behaviour is that the wrapper
1328             can provide some amount of context save and restore, to return the operating
1329             environment for the callback back to what it was at the time it was saved.
1330              
1331             For example, the following wrapper saves the value of a package variable at
1332             the time the callback was saved, and restores that value at invocation time
1333             later on. This could be useful for preserving context during logging in a
1334             Future-based program.
1335              
1336             our $LOGGING_CTX;
1337              
1338             no warnings 'redefine';
1339              
1340             my $orig = Future->can( "wrap_cb" );
1341             *Future::wrap_cb = sub {
1342             my $cb = $orig->( @_ );
1343              
1344             my $saved_logging_ctx = $LOGGING_CTX;
1345              
1346             return sub {
1347             local $LOGGING_CTX = $saved_logging_ctx;
1348             $cb->( @_ );
1349             };
1350             };
1351              
1352             At this point, any code deferred into a C by any of its callbacks will
1353             observe the C<$LOGGING_CTX> variable as having the value it held at the time
1354             the callback was saved, even if it is invoked later on when that value is
1355             different.
1356              
1357             Remember when writing such a wrapper, that it still needs to invoke the
1358             previous version of the method, so that it plays nicely in combination with
1359             others (see the C<< $orig->( @_ ) >> part).
1360              
1361             =cut
1362              
1363             # Callers expect to find this in the real Future:: package
1364             sub Future::wrap_cb
1365             {
1366 306     306 1 379 my $self = shift;
1367 306         450 my ( $op, $cb ) = @_;
1368 306         603 return $cb;
1369             }
1370              
1371             =head1 EXAMPLES
1372              
1373             The following examples all demonstrate possible uses of a C
1374             object to provide a fictional asynchronous API.
1375              
1376             For more examples, comparing the use of C with regular call/return
1377             style Perl code, see also L.
1378              
1379             =head2 Providing Results
1380              
1381             By returning a new C object each time the asynchronous function is
1382             called, it provides a placeholder for its eventual result, and a way to
1383             indicate when it is complete.
1384              
1385             sub foperation
1386             {
1387             my %args = @_;
1388              
1389             my $future = Future->new;
1390              
1391             do_something_async(
1392             foo => $args{foo},
1393             on_done => sub { $future->done( @_ ); },
1394             );
1395              
1396             return $future;
1397             }
1398              
1399             In most cases, the C method will simply be invoked with the entire
1400             result list as its arguments. In that case, it is convenient to use the
1401             L module to form a C reference that would invoke the C
1402             method.
1403              
1404             my $future = Future->new;
1405              
1406             do_something_async(
1407             foo => $args{foo},
1408             on_done => $future->curry::done,
1409             );
1410              
1411             The caller may then use this future to wait for a result using the C
1412             method, and obtain the result using C.
1413              
1414             my $f = foperation( foo => "something" );
1415              
1416             $f->on_ready( sub {
1417             my $f = shift;
1418             say "The operation returned: ", $f->result;
1419             } );
1420              
1421             =head2 Indicating Success or Failure
1422              
1423             Because the stored exception value of a failed future may not be false, the
1424             C method can be used in a conditional statement to detect success or
1425             failure.
1426              
1427             my $f = foperation( foo => "something" );
1428              
1429             $f->on_ready( sub {
1430             my $f = shift;
1431             if( not my $e = $f->failure ) {
1432             say "The operation succeeded with: ", $f->result;
1433             }
1434             else {
1435             say "The operation failed with: ", $e;
1436             }
1437             } );
1438              
1439             By using C in the condition, the order of the C blocks can be
1440             arranged to put the successful case first, similar to a C/C block.
1441              
1442             Because the C method re-raises the passed exception if the future failed,
1443             it can be used to control a C/C block directly. (This is sometimes
1444             called I).
1445              
1446             use Syntax::Keyword::Try;
1447              
1448             $f->on_ready( sub {
1449             my $f = shift;
1450             try {
1451             say "The operation succeeded with: ", $f->result;
1452             }
1453             catch {
1454             say "The operation failed with: ", $_;
1455             }
1456             } );
1457              
1458             Even neater still may be the separate use of the C and C
1459             methods.
1460              
1461             $f->on_done( sub {
1462             my @result = @_;
1463             say "The operation succeeded with: ", @result;
1464             } );
1465             $f->on_fail( sub {
1466             my ( $failure ) = @_;
1467             say "The operation failed with: $failure";
1468             } );
1469              
1470             =head2 Immediate Futures
1471              
1472             Because the C method returns the future object itself, it can be used to
1473             generate a C that is immediately ready with a result. This can also be
1474             used as a class method.
1475              
1476             my $f = Future->done( $value );
1477              
1478             Similarly, the C and C methods can be used to generate a C
1479             that is immediately failed.
1480              
1481             my $f = Future->die( "This is never going to work" );
1482              
1483             This could be considered similarly to a C call.
1484              
1485             An C block can be used to turn a C-returning function that
1486             might throw an exception, into a C that would indicate this failure.
1487              
1488             my $f = eval { function() } || Future->fail( $@ );
1489              
1490             This is neater handled by the C class method, which wraps the call in
1491             an C block and tests the result:
1492              
1493             my $f = Future->call( \&function );
1494              
1495             =head2 Sequencing
1496              
1497             The C method can be used to create simple chains of dependent tasks,
1498             each one executing and returning a C when the previous operation
1499             succeeds.
1500              
1501             my $f = do_first()
1502             ->then( sub {
1503             return do_second();
1504             })
1505             ->then( sub {
1506             return do_third();
1507             });
1508              
1509             The result of the C<$f> future itself will be the result of the future
1510             returned by the final function, if none of them failed. If any of them fails
1511             it will fail with the same failure. This can be considered similar to normal
1512             exception handling in synchronous code; the first time a function call throws
1513             an exception, the subsequent calls are not made.
1514              
1515             =head2 Merging Control Flow
1516              
1517             A C future may be used to resynchronise control flow, while waiting
1518             for multiple concurrent operations to finish.
1519              
1520             my $f1 = foperation( foo => "something" );
1521             my $f2 = foperation( bar => "something else" );
1522              
1523             my $f = Future->wait_all( $f1, $f2 );
1524              
1525             $f->on_ready( sub {
1526             say "Operations are ready:";
1527             say " foo: ", $f1->result;
1528             say " bar: ", $f2->result;
1529             } );
1530              
1531             This provides an ability somewhat similar to C or
1532             L.
1533              
1534             =cut
1535              
1536             =head1 KNOWN ISSUES
1537              
1538             =head2 Cancellation of Non-Final Sequence Futures
1539              
1540             The behaviour of future cancellation still has some unanswered questions
1541             regarding how to handle the situation where a future is cancelled that has a
1542             sequence future constructed from it.
1543              
1544             In particular, it is unclear in each of the following examples what the
1545             behaviour of C<$f2> should be, were C<$f1> to be cancelled:
1546              
1547             $f2 = $f1->then( sub { ... } ); # plus related ->then_with_f, ...
1548              
1549             $f2 = $f1->else( sub { ... } ); # plus related ->else_with_f, ...
1550              
1551             $f2 = $f1->followed_by( sub { ... } );
1552              
1553             In the C-style case it is likely that this situation should be treated
1554             as if C<$f1> had failed, perhaps with some special message. The C-style
1555             case is more complex, because it may be that the entire operation should still
1556             fail, or it may be that the cancellation of C<$f1> should again be treated
1557             simply as a special kind of failure, and the C logic run as normal.
1558              
1559             To be specific; in each case it is unclear what happens if the first future is
1560             cancelled, while the second one is still waiting on it. The semantics for
1561             "normal" top-down cancellation of C<$f2> and how it affects C<$f1> are already
1562             clear and defined.
1563              
1564             =head2 Cancellation of Divergent Flow
1565              
1566             A further complication of cancellation comes from the case where a given
1567             future is reused multiple times for multiple sequences or convergent trees.
1568              
1569             In particular, it is in clear in each of the following examples what the
1570             behaviour of C<$f2> should be, were C<$f1> to be cancelled:
1571              
1572             my $f_initial = Future->new; ...
1573             my $f1 = $f_initial->then( ... );
1574             my $f2 = $f_initial->then( ... );
1575              
1576             my $f1 = Future->needs_all( $f_initial );
1577             my $f2 = Future->needs_all( $f_initial );
1578              
1579             The point of cancellation propagation is to trace backwards through stages of
1580             some larger sequence of operations that now no longer need to happen, because
1581             the final result is no longer required. But in each of these cases, just
1582             because C<$f1> has been cancelled, the initial future C<$f_initial> is still
1583             required because there is another future (C<$f2>) that will still require its
1584             result.
1585              
1586             Initially it would appear that some kind of reference-counting mechanism could
1587             solve this question, though that itself is further complicated by the
1588             C handler and its variants.
1589              
1590             It may simply be that a comprehensive useful set of cancellation semantics
1591             can't be universally provided to cover all cases; and that some use-cases at
1592             least would require the application logic to give extra information to its
1593             C objects on how they should wire up the cancel propagation logic.
1594              
1595             Both of these cancellation issues are still under active design consideration;
1596             see the discussion on RT96685 for more information
1597             (L).
1598              
1599             =cut
1600              
1601             =head1 SEE ALSO
1602              
1603             =over 4
1604              
1605             =item *
1606              
1607             L - deferred subroutine syntax for futures
1608              
1609             Provides a neat syntax extension for writing future-based code.
1610              
1611             =item *
1612              
1613             L - Future-returning IO methods
1614              
1615             Provides methods similar to core IO functions, which yield results by Futures.
1616              
1617             =item *
1618              
1619             L - an implementation of the "Promise/A+" pattern for asynchronous
1620             programming
1621              
1622             A different alternative implementation of a similar idea.
1623              
1624             =item *
1625              
1626             L - Create automatic curried method call closures for any class or
1627             object
1628              
1629             =item *
1630              
1631             "The Past, The Present and The Future" - slides from a talk given at the
1632             London Perl Workshop, 2012.
1633              
1634             L
1635              
1636             =item *
1637              
1638             "Futures advent calendar 2013"
1639              
1640             L
1641              
1642             =item *
1643              
1644             "Asynchronous Programming with Futures" - YAPC::EU 2014
1645              
1646             L
1647              
1648             =back
1649              
1650             =cut
1651              
1652             =head1 TODO
1653              
1654             =over 4
1655              
1656             =item *
1657              
1658             Consider the ability to pass the constructor a C CODEref, instead of
1659             needing to use a subclass. This might simplify async/etc.. implementations,
1660             and allows the reuse of the idea of subclassing to extend the abilities of
1661             C itself - for example to allow a kind of Future that can report
1662             incremental progress.
1663              
1664             =back
1665              
1666             =cut
1667              
1668             =head1 AUTHOR
1669              
1670             Paul Evans
1671              
1672             =cut
1673              
1674             0x55AA;