Merge pull request #2794 from lukasvalle/master

 Example for the "hyper for" and the "race for" statements.

Author: Altai-man

doc/Language/control.pod6

@@ -531,6 +531,25 @@ Assigning C<Empty> will effectively undefine an Array, using C<for> over an
 undefined array will not even enter the loop, as shown, effectively behaving in
 the same way as above when C<Empty> was used directly.
 
+
+With C<hyper> and C<race> the for loop is potentially iterated in parallel.
+See also the documentaion for C<hyper> and C<race> in class L<Map|/type/Map>.
+
+
+=for code
+my $primes_h = hyper for ^10_000 -> $number { $number if $number.is-prime };
+say $primes_h.elems;   # OUTPUT: «1229␤»
+say $primes_h.tail: 5; # OUTPUT: «(9931 9941 9949 9967 9973)␤»
+
+with C<hyper> the order of elements is preserved.
+
+=for code
+my $primes_r = race for ^10_000 -> $number { $number if $number.is-prime };
+say $primes_r.elems; # OUTPUT: «1229␤»
+
+Unlike hyper, C<race> does not preserve the order of elements.
+
+
 =head1 X<gather/take|control flow,gather take>
 
 X<|lazy list,gather>X<|lazy list,take>