Move introduction of outcome {} after Channel

The way it was, we're starting to discuss Channels in the context of outcome
before we specced what a Channel is.

Author: lizmat

S17-concurrency.pod

@@ -377,7 +377,61 @@ result.
 This simply calls C<result> on each of the C<Promise>s, so any exception will
 be thrown.
 
-There is also an C<outcome> statement [keywords still negotiable].  In its
+=head1 Channels
+
+A C<Channel> is essentially a concurrent queue. One or more threads can put
+values into the C<Channel> using C<send>:
+
+    my $c = Channel.new;
+    $c.send($msg);
+
+Meanwhile, others can C<receive> them:
+
+    my $msg = $c.receive;
+
+Channels are ideal for producer/consumer scenarios, and since there can be
+many senders and many receivers, they adapt well to scaling certain pipeline
+stages out over multiple workers also. [Conjectural: The two feed operators
+C<< ==> >> and C<< <== >> are implemented using Channel to connect each of
+the stages.]
+
+A C<Channel> may be "forever", but it is possible to close it to further
+sends by telling it to C<close>:
+
+    $c.close();
+
+Trying to C<send> any further messages on a closed channel will throw the
+C<X::Channel::SendOnDone> exception. Closing a channel has no effect on the
+receiving end until all sent values have been received. At that point, any
+further calls to receive will throw C<X::Channel::ReceiveOnDone>. The
+C<done> method returns a C<Promise> that is kept when a sender has
+called C<close> and all sent messages have been received.  Note that multiple
+calls to a channel return the same promise, not a new one.
+
+While C<receive> blocks until it can read, C<poll> takes a message from the
+channel if one is there or immediately returns C<Nil> if nothing is there.
+
+The C<outcome> construct also works on channels, and will try to receive
+values from the any C<Channel> that has value(s) available until they are
+all closed.
+
+    outcome {
+        whenever $channel { take $_ }
+    }
+
+This is such a common pattern that we make a channel in list context behave
+that way:
+
+    for @$channel -> $val { ... }
+    for $channel.list -> $val { ... }
+
+(Note that this is not a combinator, but a means for transfering data from
+the reactive realm to the lazy realm.  Some reasonable amount of buffering
+is assumed between the two.)
+
+=head1 Outcome
+
+There is an C<outcome> statement [keywords still negotiable].  In its
 simplest form it just takes a list of C<Promise>s and C<Channel>s and returns
 a lazy list of all the values returned by all Promises and Channels specified:
 
@@ -427,7 +481,6 @@ timing out.
         wait 5 { say "Not done yet" }
     }
 
-
 As a degenerate case, in order to avoid blocking at all you may use a
 C<wait 0>.  Together with C<last>, this allows one to exit the C<outcome>
 prematurely whenever there is nothing happening:
@@ -458,58 +511,6 @@ like this:
         # do other stuff
     }
 
-=head1 Channels
-
-A C<Channel> is essentially a concurrent queue. One or more threads can put
-values into the C<Channel> using C<send>:
-
-    my $c = Channel.new;
-    $c.send($msg);
-
-Meanwhile, others can C<receive> them:
-
-    my $msg = $c.receive;
-
-Channels are ideal for producer/consumer scenarios, and since there can be
-many senders and many receivers, they adapt well to scaling certain pipeline
-stages out over multiple workers also. [Conjectural: The two feed operators
-C<< ==> >> and C<< <== >> are implemented using Channel to connect each of
-the stages.]
-
-A C<Channel> may be "forever", but it is possible to close it to further
-sends by telling it to C<close>:
-
-    $c.close();
-
-Trying to C<send> any further messages on a closed channel will throw the
-C<X::Channel::SendOnDone> exception. Closing a channel has no effect on the
-receiving end until all sent values have been received. At that point, any
-further calls to receive will throw C<X::Channel::ReceiveOnDone>. The
-C<done> method returns a C<Promise> that is kept when a sender has
-called C<close> and all sent messages have been received.  Note that multiple
-calls to a channel return the same promise, not a new one.
-
-While C<receive> blocks until it can read, C<poll> takes a message from the
-channel if one is there or immediately returns C<Nil> if nothing is there.
-
-The C<outcome> construct also works on channels, and will try to receive
-values from the any C<Channel> that has value(s) available until they are
-all closed.
-
-    outcome {
-        whenever $channel { take $_ }
-    }
-
-This is such a common pattern that we make a channel in list context behave
-that way:
-
-    for @$channel -> $val { ... }
-    for $channel.list -> $val { ... }
-
-(Note that this is not a combinator, but a means for transfering data from
-the reactive realm to the lazy realm.  Some reasonable amount of buffering
-is assumed between the two.)
-
 =head1 Supplies
 
 Channels are good for producer/consumer scenarios, but because each worker