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

WANTED

@@ -17,7 +17,6 @@ Tutorials:
 API docs:
     * MOP
     * Scheduler
-    * Thread
     * KeyReducer
 
 Builtins:

lib/Language/functions.pod

@@ -277,14 +277,66 @@ sub postfix:<!>(Int $x where { $x >= 0 }) { [*] 1..$x };
 say 6!;                     # 720
 =end code
 
-=begin comment
-TODO: elaborate on (post)circumfix ops
-=end comment
+The operator declaration becomes available as soon as possible, so you can
+even recurse into a just-defined operator, if you really want to:
+
+=begin code
+sub postfix:<!>(Int $x where { $x >= 0 }) {
+    $x == 0 ?? 1 !! $x * ($x - 1)!
+}
+say 6!;                     # 720
+=end code
+
+Circumfix and postcircumfix operators are made of two delimiters, one opening
+and one closing.
+
+=begin code
+sub circumfix:<START END>(*@elems) {
+    "start", @elems, "end"
+}
+
+say START 'a', 'b', 'c' END;        # start a b c end
+=end code;
+
+Postcircumfixes also receive the the term after which they are parsed as
+an argument:
+
+=begin code
+sub postcircumfix:<!! !!>($left, $inside) {
+    "$left -> ( $inside )"
+}
+say 42!! 1 !!;      # 42 -> ( 1 )
+=end code
 
 =head2 Precedence
 
-TODO
-=comment trait-mods, tighter, equiv, etc.
+Operator precedence in Perl 6 is specified relatively to existing operators.
+With C<is tighter(&other-operator)> you can squeeze in an operator with a
+tighter precedence than the one you specified, but looser than the
+next-tighter precedence level.
+
+For example C<< infix:<*> >> has a tighter precedence than C<<< infix:<+> >>,
+and squeezinge one in between works like this:
+
+=begin code
+sub infix:<!!>($a, $b) is tighter(&infix:<+>) {
+    2 * ($a + $b)
+}
+
+say 1 + 2 * 3 !! 4;     # 29
+=end code
+
+Here the C<1 + 2 * 3 !! 4> is parsed as C<1 + ((2 * 3) !! 4)>, because the
+precedence of the new C<!!> operator is between that of C<+> and C<*>.
+
+The same effect could have been achieved with
+
+    sub infix:<!!>($a, $b) is looser(&infix:<*>) { ... }
+
+To put a new operator on the same precedence level as an existing operator,
+use C<is equiv(&other-operator)> instead.
+
+=comment TODO: is assoc
 
 =head1 Traits
 

lib/Type/Thread.pod

@@ -0,0 +1,86 @@
+=begin pod
+
+=TITLE class Thread
+
+=SUBTITLE Concurrent execution of code (low-level)
+
+    class Thread { ... }
+
+A L<thread|https://en.wikipedia.org/wiki/Thread_%28computing%29> is a sequence
+of instructions that can (potentially) run in parallel to others. Class
+C<Thread> provides a bit of abstraction over threads provided by the
+underlying virtual machines (which in turn might or might not be operating
+system threads).
+
+Since threads are fairly low-level, most applications should use other
+primitives, like L<start|/type/Promise#method start>, which also runs in
+parallel and returns a L<Promise|/type/Promise>.
+
+=begin code
+use v6;
+my @threads = (^10).map: {
+    Thread.start(
+        name => "Sleepsorter $_",
+        sub {
+            my $rand = (^10).pick;
+            sleep $rand;
+            say $rand;
+        },
+    );
+}
+
+.finish for @threads;
+=end code
+
+The current thread is availabe in the dynamic variable C<$*THREAD>.
+
+=head1 Methods
+
+=head2 method new
+
+    method new(:&code!, Bool :$app_lifetime = False, Str $name = '<anon>') returns Thread:D
+
+Creates and returns a new C<Thread>, without starting it yet. C<&code> is the
+code that will be run in a separate thread.
+
+C<$name> is a user-specified string that identifies the thread.
+
+If C<$app_lifetime> is set to C<True>, then the thread is killed when the main
+thread of the process terminates. If set to C<False>, the process will only
+terminate when the thread has finished.
+
+=head2 method start
+
+    method start(Thread:U: &code, Bool :$app_lifetime = False, Str $name = '<anon>') returns Thread:D 
+Creates, runs and returns a new C<Thread>. Note that it can (and often does)
+return before the thread's code has finished running.
+
+=head2 method run
+
+    method run(Thread:D:)
+
+Runs the thread, and returns the invocant. It is an error to run a thread that
+has already been started.
+
+=head2 method id
+
+    method id(Thread:D:) returns Int:D
+
+Returns a numeric, unique thread identifier.
+
+=head2 method finish
+
+    method finish(Thread:D)
+
+Waits for the thread to finish. This is called I<join> in other programming
+systems.
+
+=head2 method yield
+
+    method yield(Thread:U)
+
+Tells the scheduler to prefer another thread for now.
+
+    Thread.yield;
+
+=end pod