From 6a481502bc0c3abc99768de23c9c0d18036e0b8f Mon Sep 17 00:00:00 2001
From: "Paul \"LeoNerd\" Evans" <leonerd@leonerd.org.uk>
Date: Mon, 14 Oct 2024 15:24:54 +0100
Subject: [PATCH] lib/builtin.pm: Document that builtin functions have
 optimisations which may break if the functions are replaced

---
 lib/builtin.pm | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/lib/builtin.pm b/lib/builtin.pm
index 0980884359b78..eb9fd6d8fc182 100644
--- a/lib/builtin.pm
+++ b/lib/builtin.pm
@@ -1,4 +1,4 @@
-package builtin 0.015;
+package builtin 0.016;
 
 use v5.40;
 
@@ -106,6 +106,14 @@ The following bundles currently exist:
     :5.40      true false weaken unweaken is_weak blessed refaddr reftype
                ceil floor is_tainted trim indexed
 
+=head2 Function Optimisations
+
+Various optimisations that apply to many functions in the L<builtin> package
+would be broken if the functions are ever replaced or changed, such as by
+assignment into glob references.  It is suggested not to do this, so that the
+optimiser can correctly work out that intention of code which calls these
+functions.
+
 =head1 FUNCTIONS
 
 =head2 true