Codebase list libfuture-perl / HEAD
HEAD

Tree @HEAD (Download .tar.gz)

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
NAME

    Future - represent an operation awaiting completion

SYNOPSIS

       my $future = Future->new;
    
       perform_some_operation(
          on_complete => sub {
             $future->done( @_ );
          }
       );
    
       $future->on_ready( sub {
          say "The operation is complete";
       } );

DESCRIPTION

    A Future object represents an operation that is currently in progress,
    or has recently completed. It can be used in a variety of ways to
    manage the flow of control, and data, through an asynchronous program.

    Some futures represent a single operation and are explicitly marked as
    ready by calling the done or fail methods. These are called "leaf"
    futures here, and are returned by the new constructor.

    Other futures represent a collection of sub-tasks, and are implicitly
    marked as ready depending on the readiness of their component futures
    as required. These are called "convergent" futures here as they
    converge control and data-flow back into one place. These are the ones
    returned by the various wait_* and need_* constructors.

    It is intended that library functions that perform asynchronous
    operations would use future objects to represent outstanding
    operations, and allow their calling programs to control or wait for
    these operations to complete. The implementation and the user of such
    an interface would typically make use of different methods on the
    class. The methods below are documented in two sections; those of
    interest to each side of the interface.

    It should be noted however, that this module does not in any way
    provide an actual mechanism for performing this asynchronous activity;
    it merely provides a way to create objects that can be used for control
    and data flow around those operations. It allows such code to be
    written in a neater, forward-reading manner, and simplifies many common
    patterns that are often involved in such situations.

    See also Future::Utils which contains useful loop-constructing
    functions, to run a future-returning function repeatedly in a loop.

    Unless otherwise noted, the following methods require at least version
    0.08.

 FAILURE CATEGORIES

    While not directly required by Future or its related modules, a growing
    convention of Future-using code is to encode extra semantics in the
    arguments given to the fail method, to represent different kinds of
    failure.

    The convention is that after the initial message string as the first
    required argument (intended for display to humans), the second argument
    is a short lowercase string that relates in some way to the kind of
    failure that occurred. Following this is a list of details about that
    kind of failure, whose exact arrangement or structure are determined by
    the failure category. For example, IO::Async and Net::Async::HTTP use
    this convention to indicate at what stage a given HTTP request has
    failed:

       ->fail( $message, http => ... )  # an HTTP-level error during protocol
       ->fail( $message, connect => ... )  # a TCP-level failure to connect a
                                           # socket
       ->fail( $message, resolve => ... )  # a resolver (likely DNS) failure
                                           # to resolve a hostname

    By following this convention, a module remains consistent with other
    Future-based modules, and makes it easy for program logic to gracefully
    handle and manage failures by use of the catch method.

 SUBCLASSING

    This class easily supports being subclassed to provide extra behavior,
    such as giving the get method the ability to block and wait for
    completion. This may be useful to provide Future subclasses with event
    systems, or similar.

    Each method that returns a new future object will use the invocant to
    construct its return value. If the constructor needs to perform
    per-instance setup it can override the new method, and take context
    from the given instance.

       sub new
       {
          my $proto = shift;
          my $self = $proto->SUPER::new;
    
          if( ref $proto ) {
             # Prototype was an instance
          }
          else {
             # Prototype was a class
          }
    
          return $self;
       }

    If an instance overrides the "await" method, this will be called by get
    and failure if the instance is still pending.

    In most cases this should allow future-returning modules to be used as
    if they were blocking call/return-style modules, by simply appending a
    get call to the function or method calls.

       my ( $results, $here ) = future_returning_function( @args )->get;

 DEBUGGING

    By the time a Future object is destroyed, it ought to have been
    completed or cancelled. By enabling debug tracing of objects, this fact
    can be checked. If a future object is destroyed without having been
    completed or cancelled, a warning message is printed.

       $ PERL_FUTURE_DEBUG=1 perl -MFuture -E 'my $f = Future->new'
       Future=HASH(0xaa61f8) was constructed at -e line 1 and was lost near -e line 0 before it was ready.

    Note that due to a limitation of perl's caller function within a
    DESTROY destructor method, the exact location of the leak cannot be
    accurately determined. Often the leak will occur due to falling out of
    scope by returning from a function; in this case the leak location may
    be reported as being the line following the line calling that function.

       $ PERL_FUTURE_DEBUG=1 perl -MFuture
       sub foo {
          my $f = Future->new;
       }
    
       foo();
       print "Finished\n";
    
       Future=HASH(0x14a2220) was constructed at - line 2 and was lost near - line 6 before it was ready.
       Finished

    A warning is also printed in debug mode if a Future object is destroyed
    that completed with a failure, but the object believes that failure has
    not been reported anywhere.

       $ PERL_FUTURE_DEBUG=1 perl -Mblib -MFuture -E 'my $f = Future->fail("Oops")'
       Future=HASH(0xac98f8) was constructed at -e line 1 and was lost near -e line 0 with an unreported failure of: Oops

    Such a failure is considered reported if the get or failure methods are
    called on it, or it had at least one on_ready or on_fail callback, or
    its failure is propagated to another Future instance (by a sequencing
    or converging method).

 Future::AsyncAwait::Awaitable ROLE

    Since version 0.43 this module provides the
    Future::AsyncAwait::Awaitable API. Subclass authors should note that
    several of the API methods are provided by special optimised internal
    methods, which may require overriding in your subclass if your
    internals are different from that of this module.

CONSTRUCTORS

 new

       $future = Future->new
    
       $future = $orig->new

    Returns a new Future instance to represent a leaf future. It will be
    marked as ready by any of the done, fail, or cancel methods. It can be
    called either as a class method, or as an instance method. Called on an
    instance it will construct another in the same class, and is useful for
    subclassing.

    This constructor would primarily be used by implementations of
    asynchronous interfaces.

 done (class method)

 fail (class method)

       $future = Future->done( @values )
    
       $future = Future->fail( $exception, $category, @details )

    Since version 0.26.

    Shortcut wrappers around creating a new Future then immediately marking
    it as done or failed.

 wrap

       $future = Future->wrap( @values )

    Since version 0.14.

    If given a single argument which is already a Future reference, this
    will be returned unmodified. Otherwise, returns a new Future instance
    that is already complete, and will yield the given values.

    This will ensure that an incoming argument is definitely a Future, and
    may be useful in such cases as adapting synchronous code to fit
    asynchronous libraries driven by Future.

 call

       $future = Future->call( \&code, @args )

    Since version 0.15.

    A convenient wrapper for calling a CODE reference that is expected to
    return a future. In normal circumstances is equivalent to

       $future = $code->( @args )

    except that if the code throws an exception, it is wrapped in a new
    immediate fail future. If the return value from the code is not a
    blessed Future reference, an immediate fail future is returned instead
    to complain about this fact.

METHODS

    As there are a lare number of methods on this class, they are
    documented here in several sections.

INSPECTION METHODS

    The following methods query the internal state of a Future instance
    without modifying it or otherwise causing side-effects.

 is_ready

       $ready = $future->is_ready

    Returns true on a leaf future if a result has been provided to the done
    method, failed using the fail method, or cancelled using the cancel
    method.

    Returns true on a convergent future if it is ready to yield a result,
    depending on its component futures.

 is_done

       $done = $future->is_done

    Returns true on a future if it is ready and completed successfully.
    Returns false if it is still pending, failed, or was cancelled.

 is_failed

       $failed = $future->is_failed

    Since version 0.26.

    Returns true on a future if it is ready and it failed. Returns false if
    it is still pending, completed successfully, or was cancelled.

 is_cancelled

       $cancelled = $future->is_cancelled

    Returns true if the future has been cancelled by cancel.

 state

       $str = $future->state

    Since version 0.36.

    Returns a string describing the state of the future, as one of the
    three states named above; namely done, failed or cancelled, or pending
    if it is none of these.

IMPLEMENTATION METHODS

    These methods would primarily be used by implementations of
    asynchronous interfaces.

 done

       $future->done( @result )

    Marks that the leaf future is now ready, and provides a list of values
    as a result. (The empty list is allowed, and still indicates the future
    as ready). Cannot be called on a convergent future.

    If the future is already cancelled, this request is ignored. If the
    future is already complete with a result or a failure, an exception is
    thrown.

    Since version 0.45: this method is also available under the name
    resolve.

 fail

       $future->fail( $exception, $category, @details )

    Marks that the leaf future has failed, and provides an exception value.
    This exception will be thrown by the get method if called.

    The exception must evaluate as a true value; false exceptions are not
    allowed. A failure category name and other further details may be
    provided that will be returned by the failure method in list context.

    If the future is already cancelled, this request is ignored. If the
    future is already complete with a result or a failure, an exception is
    thrown.

    If passed a Future::Exception instance (i.e. an object previously
    thrown by the get), the additional details will be preserved. This
    allows the additional details to be transparently preserved by such
    code as

       ...
       catch {
          return Future->fail($@);
       }

    Since version 0.45: this method is also available under the name
    reject.

 die

       $future->die( $message, $category, @details )

    Since version 0.09.

    A convenient wrapper around fail. If the exception is a non-reference
    that does not end in a linefeed, its value will be extended by the file
    and line number of the caller, similar to the logic that die uses.

    Returns the $future.

 on_cancel

       $future->on_cancel( $code )

    If the future is not yet ready, adds a callback to be invoked if the
    future is cancelled by the cancel method. If the future is already
    ready the method is ignored.

    If the future is later cancelled, the callbacks will be invoked in the
    reverse order to that in which they were registered.

       $on_cancel->( $future )

    If passed another Future instance, the passed instance will be
    cancelled when the original future is cancelled. In this case, the
    reference is only strongly held while the target future remains
    pending. If it becomes ready, then there is no point trying to cancel
    it, and so it is removed from the originating future's cancellation
    list.

USER METHODS

    These methods would primarily be used by users of asynchronous
    interfaces, on objects returned by such an interface.

 on_ready

       $future->on_ready( $code )

    If the future is not yet ready, adds a callback to be invoked when the
    future is ready. If the future is already ready, invokes it
    immediately.

    In either case, the callback will be passed the future object itself.
    The invoked code can then obtain the list of results by calling the get
    method.

       $on_ready->( $future )

    If passed another Future instance, the passed instance will have its
    done, fail or cancel methods invoked when the original future completes
    successfully, fails, or is cancelled respectively.

    Returns the $future.

 result

       @result = $future->result
    
       $result = $future->result

    Since version 0.44.

    If the future is ready and completed successfully, returns the list of
    results that had earlier been given to the done method on a leaf
    future, or the list of component futures it was waiting for on a
    convergent future. In scalar context it returns just the first result
    value.

    If the future is ready but failed, this method raises as an exception
    the failure that was given to the fail method. If additional details
    were given to the fail method, an exception object is constructed to
    wrap them of type Future::Exception.

    If the future was cancelled or is not yet ready an exception is thrown.

 get

       @result = $future->get
    
       $result = $future->get

    If the future is ready, returns the result or throws the failure
    exception as per "result".

    If it is not yet ready then "await" is invoked to wait for a ready
    state, and the result returned as above.

 await

       $f = $f->await

    Since version 0.44.

    Blocks until the future instance is no longer pending.

    Returns the invocant future itself, so it is useful for chaining.

    Usually, calling code would either force the future using "get", or use
    either then chaining or async/await syntax to wait for results. This
    method is useful in cases where the exception-throwing part of get is
    not required, perhaps because other code will be testing the result
    using "is_done" or similar.

       if( $f->await->is_done ) {
          ...
       }

    This method is intended for subclasses to override. The default
    implementation will throw an exception if called on a still-pending
    instance.

 block_until_ready

       $f = $f->block_until_ready

    Since version 0.40.

    Now a synonym for "await". New code should invoke await directly.

 unwrap

       @values = Future->unwrap( @values )

    Since version 0.26.

    If given a single argument which is a Future reference, this method
    will call get on it and return the result. Otherwise, it returns the
    list of values directly in list context, or the first value in scalar.
    Since it involves an implicit blocking wait, this method can only be
    used on immediate futures or subclasses that implement "await".

    This will ensure that an outgoing argument is definitely not a Future,
    and may be useful in such cases as adapting synchronous code to fit
    asynchronous libraries that return Future instances.

 on_done

       $future->on_done( $code )

    If the future is not yet ready, adds a callback to be invoked when the
    future is ready, if it completes successfully. If the future completed
    successfully, invokes it immediately. If it failed or was cancelled, it
    is not invoked at all.

    The callback will be passed the result passed to the done method.

       $on_done->( @result )

    If passed another Future instance, the passed instance will have its
    done method invoked when the original future completes successfully.

    Returns the $future.

 failure

       $exception = $future->failure
    
       $exception, $category, @details = $future->failure

    If the future is ready, returns the exception passed to the fail method
    or undef if the future completed successfully via the done method.

    If it is not yet ready then "await" is invoked to wait for a ready
    state.

    If called in list context, will additionally yield the category name
    and list of the details provided to the fail method.

    Because the exception value must be true, this can be used in a simple
    if statement:

       if( my $exception = $future->failure ) {
          ...
       }
       else {
          my @result = $future->result;
          ...
       }

 on_fail

       $future->on_fail( $code )

    If the future is not yet ready, adds a callback to be invoked when the
    future is ready, if it fails. If the future has already failed, invokes
    it immediately. If it completed successfully or was cancelled, it is
    not invoked at all.

    The callback will be passed the exception and other details passed to
    the fail method.

       $on_fail->( $exception, $category, @details )

    If passed another Future instance, the passed instance will have its
    fail method invoked when the original future fails.

    To invoke a done method on a future when another one fails, use a CODE
    reference:

       $future->on_fail( sub { $f->done( @_ ) } );

    Returns the $future.

 cancel

       $future->cancel

    Requests that the future be cancelled, immediately marking it as ready.
    This will invoke all of the code blocks registered by on_cancel, in the
    reverse order. When called on a convergent future, all its component
    futures are also cancelled. It is not an error to attempt to cancel a
    future that is already complete or cancelled; it simply has no effect.

    Returns the $future.

SEQUENCING METHODS

    The following methods all return a new future to represent the
    combination of its invocant followed by another action given by a code
    reference. The combined activity waits for the first future to be
    ready, then may invoke the code depending on the success or failure of
    the first, or may run it regardless. The returned sequence future
    represents the entire combination of activity.

    The invoked code could return a future, or a result directly.

    Since version 0.45: if a non-future result is returned it will be
    wrapped in a new immediate Future instance. This behaviour can be
    disabled by setting the PERL_FUTURE_STRICT environment variable to a
    true value at compiletime:

       $ PERL_FUTURE_STRICT=1 perl ...

    The combined future will then wait for the result of this second one.
    If the combinined future is cancelled, it will cancel either the first
    future or the second, depending whether the first had completed. If the
    code block throws an exception instead of returning a value, the
    sequence future will fail with that exception as its message and no
    further values.

    Note that since the code is invoked in scalar context, you cannot
    directly return a list of values this way. Any list-valued results must
    be done by returning a Future instance.

       sub {
          ...
          return Future->done( @results );
       }

    As it is always a mistake to call these sequencing methods in void
    context and lose the reference to the returned future (because
    exception/error handling would be silently dropped), this method warns
    in void context.

 then

       $future = $f1->then( \&done_code )

    Since version 0.13.

    Returns a new sequencing Future that runs the code if the first
    succeeds. Once $f1 succeeds the code reference will be invoked and is
    passed the list of results. It should return a future, $f2. Once $f2
    completes the sequence future will then be marked as complete with
    whatever result $f2 gave. If $f1 fails then the sequence future will
    immediately fail with the same failure and the code will not be
    invoked.

       $f2 = $done_code->( @result )

 else

       $future = $f1->else( \&fail_code )

    Since version 0.13.

    Returns a new sequencing Future that runs the code if the first fails.
    Once $f1 fails the code reference will be invoked and is passed the
    failure and other details. It should return a future, $f2. Once $f2
    completes the sequence future will then be marked as complete with
    whatever result $f2 gave. If $f1 succeeds then the sequence future will
    immediately succeed with the same result and the code will not be
    invoked.

       $f2 = $fail_code->( $exception, $category, @details )

 then (2 arguments)

       $future = $f1->then( \&done_code, \&fail_code )

    The then method can also be passed the $fail_code block as well, giving
    a combination of then and else behaviour.

    This operation is similar to those provided by other future systems,
    such as Javascript's Q or Promises/A libraries.

 catch

       $future = $f1->catch(
          name => \&code,
          name => \&code, ...
       )

    Since version 0.33.

    Returns a new sequencing Future that behaves like an else call which
    dispatches to a choice of several alternative handling functions
    depending on the kind of failure that occurred. If $f1 fails with a
    category name (i.e. the second argument to the fail call) which exactly
    matches one of the string names given, then the corresponding code is
    invoked, being passed the same arguments as a plain else call would
    take, and is expected to return a Future in the same way.

       $f2 = $code->( $exception, $category, @details )

    If $f1 does not fail, fails without a category name at all, or fails
    with a category name that does not match any given to the catch method,
    then the returned sequence future immediately completes with the same
    result, and no block of code is invoked.

    If passed an odd-sized list, the final argument gives a function to
    invoke on failure if no other handler matches.

       $future = $f1->catch(
          name => \&code, ...
          \&fail_code,
       )

    This feature is currently still a work-in-progress. It currently can
    only cope with category names that are literal strings, which are all
    distinct. A later version may define other kinds of match (e.g.
    regexp), may specify some sort of ordering on the arguments, or any of
    several other semantic extensions. For more detail on the ongoing
    design, see https://rt.cpan.org/Ticket/Display.html?id=103545.

 then (multiple arguments)

       $future = $f1->then( \&done_code, @catch_list, \&fail_code )

    Since version 0.33.

    The then method can be passed an even-sized list inbetween the
    $done_code and the $fail_code, with the same meaning as the catch
    method.

 transform

       $future = $f1->transform( %args )

    Returns a new sequencing Future that wraps the one given as $f1. With
    no arguments this will be a trivial wrapper; $future will complete or
    fail when $f1 does, and $f1 will be cancelled when $future is.

    By passing the following named arguments, the returned $future can be
    made to behave differently to $f1:

    done => CODE

      Provides a function to use to modify the result of a successful
      completion. When $f1 completes successfully, the result of its get
      method is passed into this function, and whatever it returns is
      passed to the done method of $future

    fail => CODE

      Provides a function to use to modify the result of a failure. When
      $f1 fails, the result of its failure method is passed into this
      function, and whatever it returns is passed to the fail method of
      $future.

 then_with_f

       $future = $f1->then_with_f( ... )

    Since version 0.21.

    Returns a new sequencing Future that behaves like then, but also passes
    the original future, $f1, to any functions it invokes.

       $f2 = $done_code->( $f1, @result )
       $f2 = $catch_code->( $f1, $category, @details )
       $f2 = $fail_code->( $f1, $category, @details )

    This is useful for conditional execution cases where the code block may
    just return the same result of the original future. In this case it is
    more efficient to return the original future itself.

 then_done

 then_fail

       $future = $f->then_done( @result )
    
       $future = $f->then_fail( $exception, $category, @details )

    Since version 0.22.

    Convenient shortcuts to returning an immediate future from a then
    block, when the result is already known.

 else_with_f

       $future = $f1->else_with_f( \&code )

    Since version 0.21.

    Returns a new sequencing Future that runs the code if the first fails.
    Identical to else, except that the code reference will be passed both
    the original future, $f1, and its exception and other details.

       $f2 = $code->( $f1, $exception, $category, @details )

    This is useful for conditional execution cases where the code block may
    just return the same result of the original future. In this case it is
    more efficient to return the original future itself.

 else_done

 else_fail

       $future = $f->else_done( @result )
    
       $future = $f->else_fail( $exception, $category, @details )

    Since version 0.22.

    Convenient shortcuts to returning an immediate future from a else
    block, when the result is already known.

 catch_with_f

       $future = $f1->catch_with_f( ... )

    Since version 0.33.

    Returns a new sequencing Future that behaves like catch, but also
    passes the original future, $f1, to any functions it invokes.

 followed_by

       $future = $f1->followed_by( \&code )

    Returns a new sequencing Future that runs the code regardless of
    success or failure. Once $f1 is ready the code reference will be
    invoked and is passed one argument, $f1. It should return a future,
    $f2. Once $f2 completes the sequence future will then be marked as
    complete with whatever result $f2 gave.

       $f2 = $code->( $f1 )

 without_cancel

       $future = $f1->without_cancel

    Since version 0.30.

    Returns a new sequencing Future that will complete with the success or
    failure of the original future, but if cancelled, will not cancel the
    original. This may be useful if the original future represents an
    operation that is being shared among multiple sequences; cancelling one
    should not prevent the others from running too.

    Note that this only prevents cancel propagating from $future to $f1; if
    the original $f1 instance is cancelled then the returned $future will
    have to be cancelled too.

 retain

       $f = $f->retain

    Since version 0.36.

    Creates a reference cycle which causes the future to remain in memory
    until it completes. Returns the invocant future.

    In normal situations, a Future instance does not strongly hold a
    reference to other futures that it is feeding a result into, instead
    relying on that to be handled by application logic. This is normally
    fine because some part of the application will retain the top-level
    Future, which then strongly refers to each of its components down in a
    tree. However, certain design patterns, such as mixed Future-based and
    legacy callback-based API styles might end up creating Futures simply
    to attach callback functions to them. In that situation, without
    further attention, the Future may get lost due to having no strong
    references to it. Calling ->retain on it creates such a reference which
    ensures it persists until it completes. For example:

       Future->needs_all( $fA, $fB )
          ->on_done( $on_done )
          ->on_fail( $on_fail )
          ->retain;

CONVERGENT FUTURES

    The following constructors all take a list of component futures, and
    return a new future whose readiness somehow depends on the readiness of
    those components. The first derived class component future will be used
    as the prototype for constructing the return value, so it respects
    subclassing correctly, or failing that a plain Future.

 wait_all

       $future = Future->wait_all( @subfutures )

    Returns a new Future instance that will indicate it is ready once all
    of the sub future objects given to it indicate that they are ready,
    either by success, failure or cancellation. Its result will be a list
    of its component futures.

    When given an empty list this constructor returns a new
    immediately-done future.

    This constructor would primarily be used by users of asynchronous
    interfaces.

 wait_any

       $future = Future->wait_any( @subfutures )

    Returns a new Future instance that will indicate it is ready once any
    of the sub future objects given to it indicate that they are ready,
    either by success or failure. Any remaining component futures that are
    not yet ready will be cancelled. Its result will be the result of the
    first component future that was ready; either success or failure. Any
    component futures that are cancelled are ignored, apart from the final
    component left; at which point the result will be a failure.

    When given an empty list this constructor returns an immediately-failed
    future.

    This constructor would primarily be used by users of asynchronous
    interfaces.

 needs_all

       $future = Future->needs_all( @subfutures )

    Returns a new Future instance that will indicate it is ready once all
    of the sub future objects given to it indicate that they have completed
    successfully, or when any of them indicates that they have failed. If
    any sub future fails, then this will fail immediately, and the
    remaining subs not yet ready will be cancelled. Any component futures
    that are cancelled will cause an immediate failure of the result.

    If successful, its result will be a concatenated list of the results of
    all its component futures, in corresponding order. If it fails, its
    failure will be that of the first component future that failed. To
    access each component future's results individually, use done_futures.

    When given an empty list this constructor returns a new
    immediately-done future.

    This constructor would primarily be used by users of asynchronous
    interfaces.

 needs_any

       $future = Future->needs_any( @subfutures )

    Returns a new Future instance that will indicate it is ready once any
    of the sub future objects given to it indicate that they have completed
    successfully, or when all of them indicate that they have failed. If
    any sub future succeeds, then this will succeed immediately, and the
    remaining subs not yet ready will be cancelled. Any component futures
    that are cancelled are ignored, apart from the final component left; at
    which point the result will be a failure.

    If successful, its result will be that of the first component future
    that succeeded. If it fails, its failure will be that of the last
    component future to fail. To access the other failures, use
    failed_futures.

    Normally when this future completes successfully, only one of its
    component futures will be done. If it is constructed with multiple that
    are already done however, then all of these will be returned from
    done_futures. Users should be careful to still check all the results
    from done_futures in that case.

    When given an empty list this constructor returns an immediately-failed
    future.

    This constructor would primarily be used by users of asynchronous
    interfaces.

METHODS ON CONVERGENT FUTURES

    The following methods apply to convergent (i.e. non-leaf) futures, to
    access the component futures stored by it.

 pending_futures

       @f = $future->pending_futures

 ready_futures

       @f = $future->ready_futures

 done_futures

       @f = $future->done_futures

 failed_futures

       @f = $future->failed_futures

 cancelled_futures

       @f = $future->cancelled_futures

    Return a list of all the pending, ready, done, failed, or cancelled
    component futures. In scalar context, each will yield the number of
    such component futures.

SUBCLASSING METHODS

    These methods are not intended for end-users of Future instances, but
    instead provided for authors of classes that subclass from Future
    itself.

 set_udata

       $future = $future->set_udata( $name, $value )

    Stores a Perl value within the instance, under the given name.
    Subclasses can use this to store extra data that the implementation may
    require.

    This is a safer version of attempting to use the $future instance
    itself as a hash reference.

 udata

       $value = $future->get_udata( $name )

    Returns a Perl value from the instance that was previously set with
    "set_udata".

TRACING METHODS

 set_label

 label

       $future = $future->set_label( $label )
    
       $label = $future->label

    Since version 0.28.

    Chaining mutator and accessor for the label of the Future. This should
    be a plain string value, whose value will be stored by the future
    instance for use in debugging messages or other tooling, or similar
    purposes.

 btime

 rtime

       [ $sec, $usec ] = $future->btime
    
       [ $sec, $usec ] = $future->rtime

    Since version 0.28.

    Accessors that return the tracing timestamps from the instance. These
    give the time the instance was constructed ("birth" time, btime) and
    the time the result was determined (the "ready" time, rtime). Each
    result is returned as a two-element ARRAY ref, containing the epoch
    time in seconds and microseconds, as given by
    Time::HiRes::gettimeofday.

    In order for these times to be captured, they have to be enabled by
    setting $Future::TIMES to a true value. This is initialised true at the
    time the module is loaded if either PERL_FUTURE_DEBUG or
    PERL_FUTURE_TIMES are set in the environment.

 elapsed

       $sec = $future->elapsed

    Since version 0.28.

    If both tracing timestamps are defined, returns the number of seconds
    of elapsed time between them as a floating-point number. If not,
    returns undef.

 wrap_cb

       $cb = $future->wrap_cb( $operation_name, $cb )

    Since version 0.31.

    Note: This method is experimental and may be changed or removed in a
    later version.

    This method is invoked internally by various methods that are about to
    save a callback CODE reference supplied by the user, to be invoked
    later. The default implementation simply returns the callback argument
    as-is; the method is provided to allow users to provide extra
    behaviour. This can be done by applying a method modifier of the around
    kind, so in effect add a chain of wrappers. Each wrapper can then
    perform its own wrapping logic of the callback. $operation_name is a
    string giving the reason for which the callback is being saved;
    currently one of on_ready, on_done, on_fail or sequence; the latter
    being used for all the sequence-returning methods.

    This method is intentionally invoked only for CODE references that are
    being saved on a pending Future instance to be invoked at some later
    point. It does not run for callbacks to be invoked on an
    already-complete instance. This is for performance reasons, where the
    intended behaviour is that the wrapper can provide some amount of
    context save and restore, to return the operating environment for the
    callback back to what it was at the time it was saved.

    For example, the following wrapper saves the value of a package
    variable at the time the callback was saved, and restores that value at
    invocation time later on. This could be useful for preserving context
    during logging in a Future-based program.

       our $LOGGING_CTX;
    
       no warnings 'redefine';
    
       my $orig = Future->can( "wrap_cb" );
       *Future::wrap_cb = sub {
          my $cb = $orig->( @_ );
    
          my $saved_logging_ctx = $LOGGING_CTX;
    
          return sub {
             local $LOGGING_CTX = $saved_logging_ctx;
             $cb->( @_ );
          };
       };

    At this point, any code deferred into a Future by any of its callbacks
    will observe the $LOGGING_CTX variable as having the value it held at
    the time the callback was saved, even if it is invoked later on when
    that value is different.

    Remember when writing such a wrapper, that it still needs to invoke the
    previous version of the method, so that it plays nicely in combination
    with others (see the $orig->( @_ ) part).

EXAMPLES

    The following examples all demonstrate possible uses of a Future object
    to provide a fictional asynchronous API.

    For more examples, comparing the use of Future with regular call/return
    style Perl code, see also Future::Phrasebook.

 Providing Results

    By returning a new Future object each time the asynchronous function is
    called, it provides a placeholder for its eventual result, and a way to
    indicate when it is complete.

       sub foperation
       {
          my %args = @_;
    
          my $future = Future->new;
    
          do_something_async(
             foo => $args{foo},
             on_done => sub { $future->done( @_ ); },
          );
    
          return $future;
       }

    In most cases, the done method will simply be invoked with the entire
    result list as its arguments. In that case, it is convenient to use the
    curry module to form a CODE reference that would invoke the done
    method.

        my $future = Future->new;
    
        do_something_async(
           foo => $args{foo},
           on_done => $future->curry::done,
        );

    The caller may then use this future to wait for a result using the
    on_ready method, and obtain the result using get.

       my $f = foperation( foo => "something" );
    
       $f->on_ready( sub {
          my $f = shift;
          say "The operation returned: ", $f->result;
       } );

 Indicating Success or Failure

    Because the stored exception value of a failed future may not be false,
    the failure method can be used in a conditional statement to detect
    success or failure.

       my $f = foperation( foo => "something" );
    
       $f->on_ready( sub {
          my $f = shift;
          if( not my $e = $f->failure ) {
             say "The operation succeeded with: ", $f->result;
          }
          else {
             say "The operation failed with: ", $e;
          }
       } );

    By using not in the condition, the order of the if blocks can be
    arranged to put the successful case first, similar to a try/catch
    block.

    Because the get method re-raises the passed exception if the future
    failed, it can be used to control a try/catch block directly. (This is
    sometimes called Exception Hoisting).

       use Syntax::Keyword::Try;
    
       $f->on_ready( sub {
          my $f = shift;
          try {
             say "The operation succeeded with: ", $f->result;
          }
          catch {
             say "The operation failed with: ", $_;
          }
       } );

    Even neater still may be the separate use of the on_done and on_fail
    methods.

       $f->on_done( sub {
          my @result = @_;
          say "The operation succeeded with: ", @result;
       } );
       $f->on_fail( sub {
          my ( $failure ) = @_;
          say "The operation failed with: $failure";
       } );

 Immediate Futures

    Because the done method returns the future object itself, it can be
    used to generate a Future that is immediately ready with a result. This
    can also be used as a class method.

       my $f = Future->done( $value );

    Similarly, the fail and die methods can be used to generate a Future
    that is immediately failed.

       my $f = Future->die( "This is never going to work" );

    This could be considered similarly to a die call.

    An eval{} block can be used to turn a Future-returning function that
    might throw an exception, into a Future that would indicate this
    failure.

       my $f = eval { function() } || Future->fail( $@ );

    This is neater handled by the call class method, which wraps the call
    in an eval{} block and tests the result:

       my $f = Future->call( \&function );

 Sequencing

    The then method can be used to create simple chains of dependent tasks,
    each one executing and returning a Future when the previous operation
    succeeds.

       my $f = do_first()
                  ->then( sub {
                     return do_second();
                  })
                  ->then( sub {
                     return do_third();
                  });

    The result of the $f future itself will be the result of the future
    returned by the final function, if none of them failed. If any of them
    fails it will fail with the same failure. This can be considered
    similar to normal exception handling in synchronous code; the first
    time a function call throws an exception, the subsequent calls are not
    made.

 Merging Control Flow

    A wait_all future may be used to resynchronise control flow, while
    waiting for multiple concurrent operations to finish.

       my $f1 = foperation( foo => "something" );
       my $f2 = foperation( bar => "something else" );
    
       my $f = Future->wait_all( $f1, $f2 );
    
       $f->on_ready( sub {
          say "Operations are ready:";
          say "  foo: ", $f1->result;
          say "  bar: ", $f2->result;
       } );

    This provides an ability somewhat similar to CPS::kpar() or
    Async::MergePoint.

KNOWN ISSUES

 Cancellation of Non-Final Sequence Futures

    The behaviour of future cancellation still has some unanswered
    questions regarding how to handle the situation where a future is
    cancelled that has a sequence future constructed from it.

    In particular, it is unclear in each of the following examples what the
    behaviour of $f2 should be, were $f1 to be cancelled:

       $f2 = $f1->then( sub { ... } ); # plus related ->then_with_f, ...
    
       $f2 = $f1->else( sub { ... } ); # plus related ->else_with_f, ...
    
       $f2 = $f1->followed_by( sub { ... } );

    In the then-style case it is likely that this situation should be
    treated as if $f1 had failed, perhaps with some special message. The
    else-style case is more complex, because it may be that the entire
    operation should still fail, or it may be that the cancellation of $f1
    should again be treated simply as a special kind of failure, and the
    else logic run as normal.

    To be specific; in each case it is unclear what happens if the first
    future is cancelled, while the second one is still waiting on it. The
    semantics for "normal" top-down cancellation of $f2 and how it affects
    $f1 are already clear and defined.

 Cancellation of Divergent Flow

    A further complication of cancellation comes from the case where a
    given future is reused multiple times for multiple sequences or
    convergent trees.

    In particular, it is in clear in each of the following examples what
    the behaviour of $f2 should be, were $f1 to be cancelled:

       my $f_initial = Future->new; ...
       my $f1 = $f_initial->then( ... );
       my $f2 = $f_initial->then( ... );
    
       my $f1 = Future->needs_all( $f_initial );
       my $f2 = Future->needs_all( $f_initial );

    The point of cancellation propagation is to trace backwards through
    stages of some larger sequence of operations that now no longer need to
    happen, because the final result is no longer required. But in each of
    these cases, just because $f1 has been cancelled, the initial future
    $f_initial is still required because there is another future ($f2) that
    will still require its result.

    Initially it would appear that some kind of reference-counting
    mechanism could solve this question, though that itself is further
    complicated by the on_ready handler and its variants.

    It may simply be that a comprehensive useful set of cancellation
    semantics can't be universally provided to cover all cases; and that
    some use-cases at least would require the application logic to give
    extra information to its Future objects on how they should wire up the
    cancel propagation logic.

    Both of these cancellation issues are still under active design
    consideration; see the discussion on RT96685 for more information
    (https://rt.cpan.org/Ticket/Display.html?id=96685).

SEE ALSO

      * Future::AsyncAwait - deferred subroutine syntax for futures

      Provides a neat syntax extension for writing future-based code.

      * Future::IO - Future-returning IO methods

      Provides methods similar to core IO functions, which yield results by
      Futures.

      * Promises - an implementation of the "Promise/A+" pattern for
      asynchronous programming

      A different alternative implementation of a similar idea.

      * curry - Create automatic curried method call closures for any class
      or object

      * "The Past, The Present and The Future" - slides from a talk given
      at the London Perl Workshop, 2012.

      https://docs.google.com/presentation/d/1UkV5oLcTOOXBXPh8foyxko4PR28_zU_aVx6gBms7uoo/edit

      * "Futures advent calendar 2013"

      http://leonerds-code.blogspot.co.uk/2013/12/futures-advent-day-1.html

      * "Asynchronous Programming with Futures" - YAPC::EU 2014

      https://www.youtube.com/watch?v=u9dZgFM6FtE

TODO

      * Consider the ability to pass the constructor a block CODEref,
      instead of needing to use a subclass. This might simplify async/etc..
      implementations, and allows the reuse of the idea of subclassing to
      extend the abilities of Future itself - for example to allow a kind
      of Future that can report incremental progress.

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>