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

Author: stmuk

doc/Language/5to6-perlvar.pod

@@ -159,9 +159,8 @@ only difference seems to be that OLDPWD is missing from Perl 6's %ENV.
 
 =item $]
 
-The version of the perl is returned by C<$*PERL.version>. As of this writing,
-that is "vunknown", which may be less than useful. For the record, C<$*PERL>
-itself contains, as of this writing, "Perl 6".
+The version of perl is returned by C<$*PERL.version>. For the beta this was
+"v6.b" with C<$*PERL> containing "Perl 6 (6.b)".
 
 =item $SYSTEM_FD_MAX
 

doc/Language/concurrency.pod

@@ -4,16 +4,16 @@
 
 =SUBTITLE Concurrency and Asynchronous Programming
 
-In common with most modern programming languages Perl 6 is designed to
+In common with most modern programming languages, Perl 6 is designed to
 L<support concurrency|http://en.wikipedia.org/wiki/Concurrent_computing>
-(allowing more than one thing to happen at the same time,) and
+(allowing more than one thing to happen at the same time) and
 asynchronous programming (sometime called event driven or reactive
 programming - that is an event or change in some part of a program
 may lead to an event or change in some other part of the program
-asynchronously to the program flow. )
+asynchronously to the program flow).
 
 The aim of the Perl concurrency design is to provide a high-level,
-composable, consistent interface regardless of how a virtual machine
+composable, consistent interface, regardless of how a virtual machine
 may implement it for a particular operating system, through layers of
 facilities as described below.
 
@@ -25,8 +25,8 @@ hyper-operators, autothreading junctions?
 
 =end comment
 
-Additionally certain Perl features may implicitly operate in an asynchronous
-fashion, so in order to ensure predictable interoperation with these features
+Additionally, certain Perl features may implicitly operate in an asynchronous
+fashion, so in order to ensure predictable interoperation with these features,
 user code should, where possible, avoid the lower level concurrency APIs
 (i.e. L<Thread> and L<Scheduler> ) and use the higher-level interfaces.
 
@@ -82,9 +82,9 @@ is illustrated with:
 
 Here the C<break> will cause the code block of the C<then> to throw an
 exception when it calls the C<result> method on the original promise
-that was passed as an argument which will subsequently cause the second
+that was passed as an argument, which will subsequently cause the second
 promise to be broken, raising an exception in turn when its result
-is taken.  The actual L<Exception> object will then be available from
+is taken. The actual L<Exception> object will then be available from
 C<cause>. If the promise had not been broken C<cause> would raise a
 L<X::Promise::CauseOnlyValidOnBroken> exception.
 
@@ -109,7 +109,7 @@ for that:
     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,)
+the code.  Similarly if the code fails (and the promise is thus broken),
 then C<cause> will be the L<Exception> object that was thrown:
 
     my $promise = Promise.start({ die "Broken Promise" });
@@ -212,13 +212,13 @@ necessary to do it for these.
 
 A L<Supply> is an asynchronous data streaming mechanism that can be
 consumed by one or more consumers simultaneously in a manner similar to
-"events" in other programming languages and can be seem as enabling
+"events" in other programming languages and can be seen as enabling
 "Event Driven" or reactive designs.
 
 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
+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>:
 

doc/Language/faq.pod

@@ -44,6 +44,12 @@ Google is often outdated.
 You could also try searching the Freenode #perl6 IRC channel log via
 L<Google|https://www.google.co.uk/search?q=site:irclog.perlgeek.de+inurl:perl6>
 
+=head2 What is the Perl 6 spec?
+
+The "spec" refers to the official test suite for Perl 6.  It's called
+roast and L<hosted on github|https://github.com/perl6/roast>. It
+is the measure of how complete a Perl 6 implementation is.
+
 =head2 Is there a glossary of Perl 6 related terms?
 
 See L<S99|http://design.perl6.org/S99.html>
@@ -513,7 +519,7 @@ Examples:
 
     class Foo { has $.i is rw};
 
-    for (1..10000) -> $i {
+    for (1..1_000_000) -> $i {
         my $obj = Foo.new;
         $obj.i = $i;
         say $obj.i;
@@ -526,11 +532,16 @@ Examples:
 
     has i => ( is=> 'rw');
 
-    for my $i (1..10000) {
+    for my $i (1..1_000_000) {
         my $obj = Foo->new;
         $obj->i($i);
         say $obj->i;
     }
 
+    __PACKAGE__->meta->make_immutable;
+
+    1;
+
+
 
 =end pod

doc/Language/modules.pod

@@ -21,7 +21,7 @@ files in a namespace.
 
 =head2 Basic Structure
 
-Module distributions in Perl 6 have the same stucture as any distribution in
+Module distributions in Perl 6 have the same structure as any distribution in
 the Perl family of languages:  there is a main project directory containing
 a C<README> and C<LICENSE> file, a C<lib> directory for modules, a C<t>
 directory for tests, and possibly a C<bin> directory for executable programs

doc/Language/nativecall.pod

@@ -78,7 +78,7 @@ how to do the marshalling.
 
     sub message_box(Str is encoded('utf8')) is native('libgui') { * }
 
-To specify how to marshall string return types, just apply this trait to the
+To specify how to marshal string return types, just apply this trait to the
 routine itself.
 
     sub input_box() returns Str is encoded('utf8') is native('libgui') { * }

doc/Type/Callable.pod

@@ -9,4 +9,20 @@
 Role for objects which support calling them. It's used in L<Block>,
 L<Routine>, L<Sub>, L<Method>, L<Submethod> and L<Macro> types.
 
+=head1 Methods
+
+=head2 method assuming
+
+    method assuming (Callable:D $self: |primers)
+
+Returns a C<Callable> that implements the same behaviour as the
+original, but has the values passed to .assuming already bound to the
+corresponding parameters.
+
+    sub add(Int $x,Int $y) { $x + $y };
+    my &add_to_5 = &add.assuming(5);
+    say add_to_5(4); #-> 9
+
+=comment according to design docs it's Callable but in rakudo it's assuming is in Block
+
 =end pod

doc/Type/Junction.pod

@@ -67,7 +67,7 @@ produce an empty list:
     my @a = ();
     so all(@a) # True, because there are 0 False's
 
-To express "all, but at least one", you can use C<@a && all(@a)
+To express "all, but at least one", you can use C<@a && all(@a)>
 
     say so @a && all(@a);   # False
 

doc/Type/Supply.pod

@@ -343,15 +343,127 @@ Creates a "rotoring" supply with the same semantics as List.rotor.
 Creates a new supply in which all values flowing through the given supply
 are emitted, but with the given delay in seconds.
 
-=head2 throttle
+=head2 method throttle
 
-    method throttle(Supply:D: $elems, $seconds, $delay = 0, :$scheduler) returns Supply:D
+    method throttle(Supply:D:
+      $limit,                 # values / time or simultaneous processing
+      $seconds or $callable,  # time-unit / code to process simultaneously
+      $delay = 0,             # initial delay before starting, in seconds
+      :$control,              # supply to emit control messages on (optional)
+      :$status,               # supply to tap status messages from (optional)
+      :$bleed,                # supply to bleed messages to (optional)
+      :$vent-at,              # bleed when so many buffered (optional)
+      :$scheduler,            # scheduler to use, default $*SCHEDULER
+      ) returns Supply:D
 
-Produces a C<Supply> that throttles emitting the values of the given Supply
-on the created C<Supply> by the number of elements (specified by the first
-parameter) per number of seconds (specified by the second parameter).
-Optionally allows for specification of delay (in number of seconds), and
-scheduler to be used (defaults to $*SCHEDULER).
+Produces a C<Supply> from a given Supply, but makes sure the number of
+messages passed through, is limited.
+
+It has two modes of operation: per time-unit or by maximum number of
+execution of a block of code: this is determined by the second positional
+parameter.
+
+The first positional parameter specifies the limit that should be applied.
+
+If the second positional parameter is a C<Callable>, then the limit indicates
+the maximum number of parallel processes executing the Callable, which is
+given the value that was received.  The emitted values in this case will be
+the C<Promise>s that were obtained from C<start>ing the Callable.
+
+If the second positional parameter is a numeric value, it is interpreted as
+the time-unit (in seconds).  If you specify B<.1> as the value, then it makes
+sure you don't exceed the limit for every tenth of a second.
+    
+If the limit is exceeded, then incoming messages are buffered until there
+is room to pass on / execute the Callable again.
+
+The third positional parameter is optional: it indicates the number of
+seconds the throttle will wait before passing on any values.
+
+The :control named parameter optionally specifies a Supply that you can
+use to control the throttle while it is in operation.  Messages that
+can be sent, are strings in the form of "key:value".  Please see below
+for the types of messages that you can send to control the throttle.
+
+The :status named parameter optionally specifies a Supply that will receive
+any status messages.  If specified, it will at least send one status message
+after the original Supply is exhausted.  The status message is a hash with
+the following keys:
+
+=over 2 
+
+=item allowed
+
+The current number of messages / callables that is still allowed to be
+passed / executed.
+
+=item bled
+
+The number of messages routed to the :bleed Supply.
+
+=item buffered
+
+The number of messages currently buffered because of overflow.
+
+=item emitted
+
+The number of messages emitted (passed through).
+
+=item id
+
+The id of this status message (a monotonically increasing number).  Handy
+if you want to log status messages.
+
+=item limit
+
+The current limit that is being applied.
+
+=item vent-at
+
+The maximum number of messages that may be buffered before they're
+automatically re-routed to the :bleed Supply.
+
+=back
+
+The :bleed named parameter optionally specifies a Supply that will receive
+any values that were either explicitly bled (with the B<bleed> control
+message), or automatically bled (if there's a B<vent-at> active).
+
+The :vent-at named parameter indicates the number of values that may be
+buffered before any additional value will be routed to the :bleed Supply.
+Defaults to 0 if not specified (causing no automatic bleeding to happen).
+Only makes sense if a :bleed Supply has also been specified.
+
+The :scheduler named parameter indicates the scheduler to be used.  Defaults
+to $*SCHEDULER.
+
+=head3 control messages
+
+These messages can be sent to the :control Supply.  A control message
+consists of a string of the form "key: value", e.g. "limit: 4".
+
+=over 2
+
+=item limit
+
+Change the number of messages (as initially given in the first positional)
+to the value given.
+
+=item bleed
+
+Route the given number of buffered messages to the :bleed Supply.
+
+=item vent-at
+
+Change the maximum number of buffered values before automatic bleeding
+takes place.  If the value is lower than before, will cause immediate
+rerouting of buffered values to match the new maximum.
+
+=item status
+
+Send a status message to the :status Supply with the given id.
+
+=back
 
 =head2 method stable
 
@@ -472,7 +584,7 @@ supplies are done.  Can also be called as a class method.
 
 =head2 method zip-latest
 
-    method zip(Supply @*supplies, :&with = &[,], :$initial) returns Supply:D
+    method zip-latest(Supply @*supplies, :&with = &[,], :$initial) returns Supply:D
 
 Creates a supply that emits combined values as soon as there is a new value
 seen on B<any> of the supplies.  By default, C<Lists|/type/List> are