From df0b71d8d67500a54bd09dee837cdd3a665568a2 Mon Sep 17 00:00:00 2001
From: Zoffix Znet <cpan@zoffix.com>
Date: Fri, 21 Sep 2018 11:10:33 -0400
Subject: [PATCH] [6.d] Document new behaviour of `start` in sink context

POV: https://github.com/rakudo/rakudo/commit/6ee5f75778
Propspec: https://github.com/perl6/roast/commit/7a426fb4a3
Per 6.d-prep: https://github.com/perl6/6.d-prep/blob/69a7d9c5e5d8ff3bed69c6f33577ada4bb8470be/TODO/FEATURES.md#make-start-blocks-in-sink-context-attach-an-error-handler
---
 doc/Type/Promise.pod6 | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/doc/Type/Promise.pod6 b/doc/Type/Promise.pod6
index 5ec270205..d9b460338 100644
--- a/doc/Type/Promise.pod6
+++ b/doc/Type/Promise.pod6
@@ -68,6 +68,41 @@ this method:
     my $p1 = Promise.start({ ;#`( do something here ) });
     my $p2 = start { ;#`( do something here ) };
 
+As of 6.d language, C<start> statement prefix used in L<sink> context will
+automatically attach an exceptions handler. If an exception occurs in the given
+code, it will be printed and the program will then exit, like if it were
+thrown without any C<start> statement prefixes involved.
+
+    =begin code
+    use v6.c;
+    start { die }; sleep ⅓; say "hello"; # OUTPUT: «hello␤»
+    =end code
+
+    =begin code
+    use v6.d.PREVIEW;
+    start { die }; sleep ⅓; say "hello";
+    # OUTPUT: Died
+    # in block  at -e line 1
+    =end code
+
+If you wish to avoid this behaviour, use C<start> in non-sink context or
+catch the exception yourself:
+
+    =begin code
+    # Don't sink it:
+    my $ = start { die }; sleep ⅓; say "hello"; # OUTPUT: «hello␤»
+
+    # Catch yourself:
+    start { die; CATCH { default { say "caught" } } };
+    sleep ⅓;
+    say "hello";
+    # OUTPUT: «caught␤hello␤»
+    =end code
+
+This behaviour exists only syntaxically and not as part of method L<sink>
+on L<Promise> object, thus sinking a L<Promise> object or having a C<start>
+block as return value of a routine won't trigger this behaviour.
+
 =head2 method in
 
     method in(Promise:U: $seconds, :$scheduler = $*SCHEDULER --> Promise:D)