From d3c633bad10e97654c0903dcb92dcebbee444ce6 Mon Sep 17 00:00:00 2001
From: Father Chrysostomos <sprout@cpan.org>
Date: Wed, 12 Nov 2014 22:29:27 -0800
Subject: [PATCH] Document sub inlining changes

Most of the changes do not need to be documented, because the previous
behaviour did not match the documentation or was just plain buggy.
---
 pod/perlsub.pod | 33 +++++++++++++++++++++++++++------
 1 file changed, 27 insertions(+), 6 deletions(-)

diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 3146037..10eedf5 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -1639,11 +1639,12 @@ The following functions would all be inlined:
     sub N () { int(OPT_BAZ) / 3 }
 
     sub FOO_SET () { 1 if FLAG_MASK & FLAG_FOO }
+    sub FOO_SET2 () { if (FLAG_MASK & FLAG_FOO) { 1 } }
 
-Be aware that these will not be inlined; as they contain inner scopes,
-the constant folding doesn't reduce them to a single constant:
-
-    sub foo_set () { if (FLAG_MASK & FLAG_FOO) { 1 } }
+(Be aware that the last example was not always inlined in Perl 5.20 and
+earlier, which did not behave consistently with subroutines containing
+inner scopes.)  You can countermand inlining by using an explicit
+C<return>:
 
     sub baz_val () {
 	if (OPT_BAZ) {
@@ -1653,6 +1654,7 @@ the constant folding doesn't reduce them to a single constant:
 	    return 42;
 	}
     }
+    sub bonk_val () { return 12345 }
 
 As alluded to earlier you can also declare inlined subs dynamically at
 BEGIN time if their body consists of a lexically-scoped scalar which
@@ -1682,6 +1684,24 @@ normal lexical variable, e.g. this will print C<79907>, not C<79908>:
     }
     print RT_79908(); # prints 79907
 
+As of Perl 5.22, this buggy behavior, while preserved for backward
+compatibility, is detected and emits a deprecation warning.  If you want
+the subroutine to be inlined (with no warning), make sure the variable is
+not used in a context where it could be modified aside from where it is
+declared.
+
+    # Fine, no warning
+    BEGIN {
+        my $x = 54321;
+        *INLINED = sub () { $x };
+    }
+    # Warns.  Future Perl versions will stop inlining it.
+    BEGIN {
+        my $x;
+        $x = 54321;
+        *ALSO_INLINED = sub () { $x };
+    }
+
 If you really want a subroutine with a C<()> prototype that returns a
 lexical variable you can easily force it to not be inlined by adding
 an explicit C<return>:
@@ -1694,7 +1714,7 @@ an explicit C<return>:
     print RT_79908(); # prints 79908
 
 The easiest way to tell if a subroutine was inlined is by using
-L<B::Deparse>, consider this example of two subroutines returning
+L<B::Deparse>.  Consider this example of two subroutines returning
 C<1>, one with a C<()> prototype causing it to be inlined, and one
 without (with deparse output truncated for clarity):
 
@@ -1727,7 +1747,8 @@ of the function will still be using the old value of the function.  If
 you need to be able to redefine the subroutine, you need to ensure
 that it isn't inlined, either by dropping the C<()> prototype (which
 changes calling semantics, so beware) or by thwarting the inlining
-mechanism in some other way, e.g. by adding an explicit C<return>:
+mechanism in some other way, e.g. by adding an explicit C<return>, as
+mentioned above:
 
     sub not_inlined () { return 23 }
 
-- 
1.8.3.1