Document LEAVE + exit trap

Resolves #1581

Author: AlexDaniel

doc/Language/phasers.pod6

@@ -263,7 +263,9 @@ one thrown from a C<LEAVE> phaser will not.
 
 =head2 X<LEAVE|Phasers>
 
-Runs at every block exit time (even stack unwinds from exceptions).
+Runs at every block exit time (even stack unwinds from exceptions),
+except when the program exits abruptly (e.g. with
+L«C<exit>|/routine/exit»).
 
 So C<LEAVE> phasers for a given block are necessarily evaluated after any
 C<CATCH> and C<CONTROL> phasers. This includes the C<LEAVE> variants, C<KEEP>

doc/Language/traps.pod6

@@ -1036,6 +1036,40 @@ $a.sayit;      # OUTPUT: «hi␤»
 my $b = A.new;
 $b.sayit;      # nothing
 
-=end pod
+=head2 C<LEAVE> phaser and C<exit>
+Using L«C<LEAVE>|/syntax/LEAVE» phaser to perform graceful resource
+termination is a common pattern, but it does not cover the case when
+the program is stopped with L«C<exit>|/routine/exit».
+
+The following nondeterministic example should demonstrate the
+complications of this trap:
+=begin code :skip-test
+my $x = say ‘Opened some resource’;
+LEAVE say ‘Closing the resource gracefully’ with $x;
+
+exit 42 if rand < ⅓; # ① ｢exit｣ is bad
+die ‘Dying because of unhandled exception’ if rand < ½; # ② ｢die｣ is ok
+# fallthru ③
+=end code
 
+There are three possible results:
+=begin code :skip-test
+①
+Opened some resource
+
+②
+Opened some resource
+Closing the resource gracefully
+Dying because of unhandled exception
+  in block <unit> at print.p6 line 5
+
+③
+Opened some resource
+Closing the resource gracefully
+=end code
+
+A call to C<exit> is part of normal operation for many programs, so
+beware unintentional combination of C<LEAVE> phasers and C<exit> calls.
+
+=end pod
 # vim: expandtab shiftwidth=4 ft=perl6

xt/words.pws

@@ -331,6 +331,7 @@ eyewear
 fagner
 failover
 fallbacks
+fallthru
 false's
 falsy
 fatrat
@@ -675,6 +676,7 @@ nok
 nom
 nomatch
 nonchaining
+nondeterministic
 nonintuitive
 nonspacing
 nopackage