This file is indexed.

/usr/share/perl5/Future/Phrasebook.pod is in libfuture-perl 0.33-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  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
#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2013-2014 -- leonerd@leonerd.org.uk

=head1 NAME

C<Future::Phrasebook> - coding examples for C<Future> and C<Future::Utils>

This documentation-only module provides a phrasebook-like approach to giving
examples on how to use L<Future> and L<Future::Utils> to structure
Future-driven asynchronous or concurrent logic. As with any inter-dialect
phrasebook it is structured into pairs of examples; each given first in a
traditional call/return Perl style, and second in a style using Futures. In
each case, the generic function or functions in the example are named in
C<ALL_CAPITALS()> to make them stand out.

In the examples showing use of Futures, any function that is expected to
return a C<Future> instance is named with a leading C<F_> prefix. Each example
is also constructed so as to yield an overall future in a variable called
C<$f>, which represents the entire operation.

=head1 SEQUENCING

The simplest example of a sequencing operation is simply running one piece of
code, then immediately running a second. In call/return code we can just place
one after the other.

 FIRST();
 SECOND();

Using a Future it is necessary to await the result of the first C<Future>
before calling the second.

 my $f = F_FIRST()
    ->then( sub { F_SECOND(); } );

Here, the anonymous closure is invoked once the C<Future> returned by
C<F_FIRST()> succeeds. Because C<then> invokes the code block only if the
first Future succeeds, it shortcircuits around failures similar to the way that
C<die()> shortcircuits around thrown exceptions. A C<Future> representing the
entire combination is returned by the method.

Because the C<then> method itself returns a C<Future> representing the
overall operation, it can itself be further chained.

 FIRST();
 SECOND();
 THIRD();

Z<>

 my $f = F_FIRST()
    ->then( sub { F_SECOND(); } )
    ->then( sub { F_THIRD(); } );

See below for examples of ways to handle exceptions.

=head2 Passing Results

Often the result of one function can be passed as an argument to another
function.

 OUTER( INNER() );

The result of the first C<Future> is passed into the code block given to the
C<then> method.

 my $f = F_INNER()
    ->then( sub { F_OUTER( @_ ) } );

=head1 CONDITIONALS

It may be that the result of one function call is used to determine whether or
not another operation is taken.

 if( COND() == $value ) {
    ACTION();
 }

Because the C<then_with_f> code block is given the first future in addition to
its results it can decide whether to call the second function to return a new
future, or simply return the one it was given.

 my $f = F_COND()
    ->then_with_f( sub {
       my ( $f_cond, $result ) = @_;
       if( $result == $value ) {
          return F_ACTION();
       }
       else {
          return $f_cond;
       }
    });

=head1 EXCEPTION HANDLING

In regular call/return style code, if any function throws an exception, the
remainder of the block is not executed, the containing C<try> or C<eval> is
aborted, and control is passed to the corresponding C<catch> or line after the
C<eval>.

 try {
    FIRST();
 }
 catch {
    my $e = $_;
    ERROR( $e );
 };

The C<else> method on a C<Future> can be used here. It behaves similar to
C<then>, but is only invoked if the initial C<Future> fails; not if it
succeeds.

 my $f = F_FIRST()
    ->else( sub { F_ERROR( @_ ); } );

Alternatively, the second argument to the C<then> method can be applied, which
is invoked only on case of failure.

 my $f = F_FIRST()
    ->then( undef, sub { F_ERROR( @_ ); } );

Often it may be the case that the failure-handling code is in fact immediate,
and doesn't return a C<Future>. In that case, the C<else> code block can
return an immediate C<Future> instance.

 my $f = F_FIRST()
    ->else( sub {
       ERROR( @_ );
       return Future->done;
    });

Sometimes the failure handling code simply needs to be aware of the failure,
but rethrow it further up.

 try {
    FIRST();
 }
 catch {
    my $e = $_;
    ERROR( $e );
    die $e;
 };

In this case, while the C<else> block could return a new C<Future> failed with
the same exception, the C<else_with_f> block is passed the failed C<Future>
itself in addition to the failure details so it can just return that.

 my $f = F_FIRST()
    ->else_with_f( sub {
       my ( $f1, @failure ) = @_;
       ERROR( @failure );
       return $f1;
    });

The C<followed_by> method is similar again, though it invokes the code block
regardless of the success or failure of the initial C<Future>. It can be used
to create C<finally> semantics. By returning the C<Future> instance that it
was passed, the C<followed_by> code ensures it doesn't affect the result of
the operation.

 try {
    FIRST();
 }
 catch {
    ERROR( $_ );
 }
 finally {
    CLEANUP();
 };

Z<>

 my $f = F_FIRST()
    ->else( sub {
       ERROR( @_ );
       return Future->done;
    })
    ->followed_by( sub {
       CLEANUP();
       return shift;
    });

=head1 ITERATION

To repeat a single block of code multiple times, a C<while> block is often
used.

 while( COND() ) {
    FUNC();
 }

The C<Future::Utils::repeat> function can be used to repeatedly iterate a
given C<Future>-returning block of code until its ending condition is
satisfied.

 use Future::Utils qw( repeat );
 my $f = repeat {
    F_FUNC();
 } while => sub { COND() };

Unlike the statement nature of perl's C<while> block, this C<repeat> C<Future>
can yield a value; the value returned by C<< $f->get >> is the result of the
final trial of the code block.

Here, the condition function it expected to return its result immediately. If
the repeat condition function itself returns a C<Future>, it can be combined
along with the loop body. The trial C<Future> returned by the code block is
passed to the C<while> condition function.

 my $f = repeat {
    F_FUNC()
       ->followed_by( sub { F_COND(); } );
 } while => sub { shift->get };

The condition can be negated by using C<until> instead

 until( HALTING_COND() ) {
    FUNC();
 }

Z<>

 my $f = repeat {
    F_FUNC();
 } until => sub { HALTING_COND() };

=head2 Iterating with Exceptions

Technically, this loop isn't quite the same as the equivalent C<while> loop in
plain Perl, because the C<while> loop will also stop executing if the code
within it throws an exception. This can be handled in C<repeat> by testing for
a failed C<Future> in the C<until> condition.

 while(1) {
    TRIAL();
 }

Z<>

 my $f = repeat {
    F_TRIAL();
 } until => sub { shift->failure };

When a repeat loop is required to retry a failure, the C<try_repeat> function
should be used. Currently this function behaves equivalently to C<repeat>,
except that it will not print a warning if it is asked to retry after a
failure, whereas this behaviour is now deprecated for the regular C<repeat>
function so that yields a warning.

 my $f = try_repeat {
    F_TRIAL();
 } while => sub { shift->failure };

Another variation is the C<try_repeat_until_success> function, which provides
a convenient shortcut to calling C<try_repeat> with a condition that makes
another attempt each time the previous one fails; stopping once it achieves a
successful result.

 while(1) {
    eval { TRIAL(); 1 } and last;
 }

Z<>

 my $f = try_repeat_until_success {
    F_TRIAL();
 };

=head2 Iterating over a List

A variation on the idea of the C<while> loop is the C<foreach> loop; a loop
that executes once for each item in a given list, with a variable set to one
value from that list each time.

 foreach my $thing ( @THINGS ) {
    INSPECT( $thing );
 }

This can be performed with C<Future> using the C<foreach> parameter to the
C<repeat> function. When this is in effect, the block of code is passed each
item of the given list as the first parameter.

 my $f = repeat {
    my $thing = shift;
    F_INSPECT( $thing );
 } foreach => \@THINGS;

=head2 Recursing over a Tree

A regular call/return function can use recursion to walk over a tree-shaped
structure, where each item yields a list of child items.

 sub WALK
 {
    my ( $item ) = @_;
    ...
    WALK($_) foreach CHILDREN($item);
 }

This recursive structure can be turned into a C<while()>-based repeat loop by
using an array to store the remaining items to walk into, instead of using the
perl stack directly:

 sub WALK
 {
    my @more = ( $root );
    while( @more ) {
       my $item = shift @more;
       ...
       unshift @more, CHILDREN($item)
    }
 }

This arrangement then allows us to use C<fmap_void> to walk this structure
using Futures, possibly concurrently. A lexical array variable is captured
that holds the stack of remaining items, which is captured by the item code so
it can C<unshift> more into it, while also being used as the actual C<fmap>
control array.

 my @more = ( $root );

 my $f = fmap_void {
    my $item = shift;
    ...->on_done( sub {
       unshift @more, @CHILDREN;
    })
 } foreach => \@more;

By choosing to either C<unshift> or C<push> more items onto this list, the
tree can be walked in either depth-first or breadth-first order.

=head1 SHORT-CIRCUITING

Sometimes a result is determined that should be returned through several
levels of control structure. Regular Perl code has such keywords as C<return>
to return a value from a function immediately, or C<last> for immediately
stopping execution of a loop.

 sub func {
    foreach my $item ( @LIST ) {
       if( COND($item) ) {
          return $item;
       }
    }
    return MAKE_NEW_ITEM();
 }

The C<Future::Utils::call_with_escape> function allows this general form of
control flow, by calling a block of code that is expected to return a future,
and itself returning a future. Under normal circumstances the result of this
future propagates through to the one returned by C<call_with_escape>.

However, the code is also passed in a future value, called here the "escape
future". If the code captures this future and completes it (either by calling
C<done> or C<fail>), then the overall returned future immediately completes
with that result instead, and the future returned by the code block is
cancelled.

 my $f = call_with_escape {
    my $escape_f = shift;

    ( repeat {
       my $item = shift;
       COND($item)->then( sub {
          my ( $result ) = @_;
          if( $result ) {
             $escape_f->done( $item );
          }
          return Future->done;
       })
    } foreach => \@ITEMS )->then( sub {
       MAKE_NEW_ITEM();
    });
 };

Here, if C<$escape_f> is completed by the condition test, the future chain
returned by the code (that is, the C<then> chain of the C<repeat> block
followed by C<MAKE_NEW_ITEM()>) will be cancelled, and C<$f> itself will
receive this result.

=head1 CONCURRENCY

This final section of the phrasebook demonstrates a number of abilities that
are simple to do with C<Future> but can't easily be done with regular
call/return style programming, because they all involve an element of
concurrency. In these examples the comparison with regular call/return code
will be somewhat less accurate because of the inherent ability for the
C<Future>-using version to behave concurrently.

=head2 Waiting on Multiple Functions

The C<< Future->wait_all >> constructor creates a C<Future> that waits for all
of the component futures to complete. This can be used to form a sequence with
concurrency.

 { FIRST_A(); FIRST_B() }
 SECOND();

Z<>

 my $f = Future->wait_all( FIRST_A(), FIRST_B() )
    ->then( sub { SECOND() } );

Unlike in the call/return case, this can perform the work of C<FIRST_A()> and
C<FIRST_B()> concurrently, only proceeding to C<SECOND()> when both are ready.

The result of the C<wait_all> C<Future> is the list of its component
C<Future>s. This can be used to obtain the results.

 SECOND( FIRST_A(), FIRST_B() );

Z<>

 my $f = Future->wait_all( FIRST_A(), FIRST_B() )
    ->then( sub {
       my ( $f_a, $f_b ) = @_
       SECOND( $f_a->get, $f_b->get );
    } );

Because the C<get> method will re-raise an exception caused by a failure of
either of the C<FIRST> functions, the second stage will fail if any of the
initial Futures failed.

As this is likely to be the desired behaviour most of the time, this kind of
control flow can be written slightly neater using C<< Future->needs_all >>
instead.

 my $f = Future->needs_all( FIRST_A(), FIRST_B() )
    ->then( sub { SECOND( @_ ) } );

The C<get> method of a C<needs_all> convergent Future returns a concatenated
list of the results of all its component Futures, as the only way it will
succeed is if all the components do.

=head2 Waiting on Multiple Calls of One Function

Because the C<wait_all> and C<needs_all> constructors take an entire list of
C<Future> instances, they can be conveniently used with C<map> to wait on the
result of calling a function concurrently once per item in a list.

 my @RESULT = map { FUNC( $_ ) } @ITEMS;
 PROCESS( @RESULT );

Again, the C<needs_all> version allows more convenient access to the list of
results.

 my $f = Future->needs_all( map { F_FUNC( $_ ) } @ITEMS )
    ->then( sub {
       my @RESULT = @_;
       F_PROCESS( @RESULT )
    } );

This form of the code starts every item's future concurrently, then waits for
all of them. If the list of C<@ITEMS> is potentially large, this may cause a
problem due to too many items running at once. Instead, the
C<Future::Utils::fmap> family of functions can be used to bound the
concurrency, keeping at most some given number of items running, starting new
ones as existing ones complete.

 my $f = fmap {
    my $item = shift;
    F_FUNC( $item )
 } foreach => \@ITEMS;

By itself, this will not actually act concurrently as it will only keep one
Future outstanding at a time. The C<concurrent> flag lets it keep a larger
number "in flight" at any one time:

 my $f = fmap {
    my $item = shift;
    F_FUNC( $item )
 } foreach => \@ITEMS, concurrent => 10;

The C<fmap> and C<fmap_scalar> functions return a Future that will eventually
give the collected results of the individual item futures, thus making them
similar to perl's C<map> operator.

Sometimes, no result is required, and the items are run in a loop simply for
some side-effect of the body.

 foreach my $item ( @ITEMS ) {
    FUNC( $item );
 }

To avoid having to collect a potentially-large set of results only to throw
them away, the C<fmap_void> function variant of the C<fmap> family yields a
Future that completes with no result after all the items are complete.

 my $f = fmap_void {
    my $item = shift;
    F_FIRST( $item )
 } foreach => \@ITEMS, concurrent => 10;

=head1 AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

=cut