Merge branch 'master' of github.com:perl6/doc

Author: jonathanstowe

lib/Language/concurrency.pod

@@ -94,18 +94,18 @@ A L<Promise> can also be scheduled to be automatically kept at a future time:
     my $promise2 = $promise1.then(-> $v { say $v.status; 'Second Result' });
     say $promise2.result;
 
-The method C<in> creates a new promise and schedules a new task to call
+The L<method in|/type/Promise#method_in> creates a new promise and schedules a new task to call
 C<keep> on it no earlier than the supplied number of seconds, returning
-the new L<Promise> object. This is almost directly equivalent to calling
-C<Scheduler.cue> with a code block that will C<keep> the returned promise.
+the new L<Promise> object.
 
-Possibly the most frequent requirement would be to schedule some code to
-be executed as soon as possible and obtain a promise that will be kept
-(or broken) when the code completes (or throws an exception,) this is
-performed by the method C<start> :
+A very frequent use of promises is to run a piece of code, and keep the
+promise once it returns successfully, or break it when the code dies.
+The L<start method|/type/Promise#method_start> provides a shortcut for that:
 
-    my $promise = Promise.start({ my $i = 0; for 1 .. 10 { $i += $_ }; $i});
-    say $promise.result;
+    my $promise = Promise.start(
+        { my $i = 0; for 1 .. 10 { $i += $_ }; $i}
+    );
+    say $promise.result;    # 55
 
 Here the C<result> of the promise returned is the value returned from
 the code.  Similarly if the code fails (and the promise is thus broken,)
@@ -116,62 +116,64 @@ then C<cause> will be the L<Exception> object that was thrown:
     say $promise.cause;
 
 This is considered to be such a commonly required pattern that it is
-provided as subroutines:
-
-    my $result = await start {
-                                my $i = 0;
-                                for 1 .. 10 {
-                                    $i += $_
-                                }
-                                $i
-                        }
+also provided as subroutines:
+
+    my $promise = start {
+        my $i = 0;
+        for 1 .. 10 {
+            $i += $_
+        }
+        $i
+    }
+    my $result = await $promise;
     say $result;
 
 C<await> is almost equivalent to calling C<result> on the promise object
 returned by C<start> but it will also take a list of promises and return
 the result of each:
 
-    my $result = await start({
-                                my $i = 0;
-                                for 1 .. 10 {
-                                    $i += $_
-                                }
-                                $i
-                        }),
-                        start({
-                                my $i = 0;
-                                for 1 .. 10 {
-                                    $i -= $_
-                                }
-                                $i
-                        });
-    say $result;
-
-In addition to C<await> two methods are provided that will combine a set pf
-L<Promise> objects into a new promise: C<allof> which returns a promise that
+    my $p1 = start {
+        my $i = 0;
+        for 1 .. 10 {
+            $i += $_
+        }
+        $i
+    };
+    my $p2 = start {
+        my $i = 0;
+        for 1 .. 10 {
+            $i -= $_
+        }
+        $i
+    };
+    my @result = await $p1, $p2;
+    say @result;            # 55 -55
+
+In addition to C<await>, two class methods combine several
+L<Promise> objects into a new promise: C<allof> returns a promise that
 is kept when all the original promises are kept or broken when one of them
 is broken:
 
     my $promise = Promise.allof(
-                                 Promise.in(2),
-                                 Promise.in(3)    
-                               );
+        Promise.in(2),
+        Promise.in(3)    
+    );
 
     await $promise;
-    say "All done"; # Should be no less than three seconds later
+    say "All done"; # Should be not much more than three seconds later
 
-And C<anyof> which returns a new promise that will be kept when any of the
+And C<anyof> returns a new promise that will be kept when any of the
 original promises is kept or broken when any of them is broken:
 
     my $promise = Promise.anyof(
-                                  Promise.in(3),
-                                  Promise.in(8600)
-                               );
+        Promise.in(3),
+        Promise.in(8600)
+    );
 
     await $promise;
     say "All done"; # Should be about 3 seconds later
 
-unlike C<await> however the results of the original kept promises are not
+Unlike C<await> however the results of the original kept promises are not
 available without referring to the original, so these are more useful
 when the completion or otherwise of the tasks is more important to the
 consumer than the actual results, or the results have been collected by
@@ -185,12 +187,12 @@ consumed by one or more consumers simultaneously in a manner similar to
 "events" in other programming languages and can be seem as enabling
 "Event Driven" or reactive designs.
 
-L<Supply> is a role that can be composed into your own types, but will 
+L<Supply> is a role that can be composed into your own types, but will
 frequently be used as a "type punned" class to create standalone objects.
 
 At its simplest a L<Supply> is a message stream that can have multiple
 subscribers created with the method C<tap> on to which data items can be
-placed with C<emit> :
+placed with C<emit>:
 
     my $supply = Supply.new();
 
@@ -211,25 +213,25 @@ interested in the events:
     $supply.emit("Won't trigger the tap");
 
 Calling C<close> on the L<Tap> object (or calling C<close> on the supply
-object with the tap object as an argument,) will trigger the callback
+object with the tap object as an argument,) triggers the callback
 specified by C<closing> if present and stop further events being sent to
 the tap callback but otherwise leave the supply intact to receive further
-events. Calling C<done> on the supply object will similarly call the
-C<done> callback that may be specified for any taps but will not prevent any
+events. Calling C<done> on the supply object similarly calls the
+C<done> callback that may be specified for any taps, but does not prevent any
 further events being emitted to the stream, or taps receiving them.
 
-The method C<interval> will return a new supply which will automatically
-emit a new event at the specified interval, the data that is emitted will
-be an integer starting at 0 that will be incremented for each event. The
-following code will output 0 .. 5 :
+The method C<interval> returns a new supply which peridically
+emits a new event at the specified interval. The data that is emitted
+is an integer starting at 0 that is incremented for each event. The
+following code outputs 0 .. 5 :
 
 	my $supply = Supply.interval(2);
 	$supply.tap(-> $v { say $v });
 	sleep 10;
 
-A second argument can be supplied which will specify a delay in seconds
+A second argument can be supplied which specifies a delay in seconds
 before the first event is fired. Each tap of a supply created by
-C<interval> will have its own sequence starting from 0, as illustrated
+C<interval> has its own sequence starting from 0, as illustrated
 by the following:
 
     my $supply = Supply.interval(2);
@@ -241,8 +243,8 @@ by the following:
 An existing supply object can be filtered or transformed, using the methods
 C<grep> and C<map> respectively, to create a new supply in a manner like
 the similarly named list methods: C<grep> returns a supply such that only
-those events emitted on the source stream for which the expression provided
-to the C<grep> will be enitted:
+those events emitted on the source stream for which the C<grep> condition
+is true is emitted on the second supply:
 
     my $supply = Supply.new;
     $supply.tap(-> $v { say "Original : $v" });
@@ -254,9 +256,9 @@ to the C<grep> will be enitted:
         $supply.emit($_);
     }
 
-C<map> will return a new supply such that for each item emitted to the
+C<map> returns a new supply such that for each item emitted to the
 original supply a new item which is the result of the expression passed
-to the C<map> will be emitted:
+to the C<map> is emitted:
 
      my $supply = Supply.new;
      $supply.tap(-> $v { say "Original : $v" });