Add PERL_MAGIC_extvalue

A new magic type PERL_MAGIC_extvalue has been added. This is available
for use like PERL_MAGIC_ext, but is a value magic: upon localization the
new value will not be magical.

6 files changed, 26 insertions, 12 deletions

diff --git a/mg_names.inc b/mg_names.inc
index 7eb9033675..5a5abb9d86 100644
--- a/mg_names.inc
+++ b/mg_names.inc
@@ -49,6 +49,7 @@
 	{ PERL_MAGIC_defelem,        "defelem(y)" },
 	{ PERL_MAGIC_lvref,          "lvref(\\)" },
 	{ PERL_MAGIC_checkcall,      "checkcall(])" },
+	{ PERL_MAGIC_extvalue,       "extvalue(^)" },
 	{ PERL_MAGIC_ext,            "ext(~)" },
 
 /* ex: set ro: */
diff --git a/mg_raw.h b/mg_raw.h
index c55e64372c..0638b09953 100644
--- a/mg_raw.h
+++ b/mg_raw.h
@@ -86,7 +86,9 @@
       "/* lvref '\\' Lvalue reference constructor */" },
     { ']', "want_vtbl_checkcall | PERL_MAGIC_VALUE_MAGIC",
       "/* checkcall ']' Inlining/mutation of call to this CV */" },
+    { '^', "magic_vtable_max | PERL_MAGIC_READONLY_ACCEPTABLE | PERL_MAGIC_VALUE_MAGIC",
+      "/* extvalue '^' Value magic available for use by extensions */" },
     { '~', "magic_vtable_max | PERL_MAGIC_READONLY_ACCEPTABLE",
-      "/* ext '~' Available for use by extensions */" },
+      "/* ext '~' Variable magic available for use by extensions */" },
 
 /* ex: set ro: */
diff --git a/mg_vtable.h b/mg_vtable.h
index 8f59573ca1..0497e2942a 100644
--- a/mg_vtable.h
+++ b/mg_vtable.h
@@ -57,7 +57,8 @@
                                          smart parameter vivification */
 #define PERL_MAGIC_lvref          '\\' /* Lvalue reference constructor */
 #define PERL_MAGIC_checkcall      ']' /* Inlining/mutation of call to this CV */
-#define PERL_MAGIC_ext            '~' /* Available for use by extensions */
+#define PERL_MAGIC_extvalue       '^' /* Value magic available for use by extensions */
+#define PERL_MAGIC_ext            '~' /* Variable magic available for use by extensions */
 
 enum {		/* pass one of these to get_vtbl */
     want_vtbl_arylen,
diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index f641641187..463809f73b 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -373,7 +373,9 @@ well.
 
 =item *
 
-XXX
+A new magic type C<PERL_MAGIC_extvalue> has been added. This is available for
+use like C<PERL_MAGIC_ext>, but is a value magic: upon localization the new
+value will not be magical.
 
 =back
 
diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index a4691e6948..13417650d6 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -1558,8 +1558,10 @@ will be lost.
                                              constructor
  ]  PERL_MAGIC_checkcall      vtbl_checkcall Inlining/mutation of call
                                              to this CV
- ~  PERL_MAGIC_ext            (none)         Available for use by
-                                             extensions
+ ^  PERL_MAGIC_extvalue       (none)         Value magic available for
+                                             use by extensions
+ ~  PERL_MAGIC_ext            (none)         Variable magic available
+                                             for use by extensions
 
 
 =for apidoc_section $magic
@@ -1576,6 +1578,7 @@ will be lost.
 =for apidoc_item ||PERL_MAGIC_env
 =for apidoc_item ||PERL_MAGIC_envelem
 =for apidoc_item ||PERL_MAGIC_ext
+=for apidoc_item ||PERL_MAGIC_extvalue
 =for apidoc_item ||PERL_MAGIC_fm
 =for apidoc_item ||PERL_MAGIC_hints
 =for apidoc_item ||PERL_MAGIC_hintselem
@@ -1616,12 +1619,15 @@ uppercase letter is typically used to represent some kind of composite type
 of that composite type.  Some internals code makes use of this case
 relationship.  However, 'v' and 'V' (vec and v-string) are in no way related.
 
-The C<PERL_MAGIC_ext> and C<PERL_MAGIC_uvar> magic types are defined
-specifically for use by extensions and will not be used by perl itself.
-Extensions can use C<PERL_MAGIC_ext> magic to 'attach' private information
-to variables (typically objects).  This is especially useful because
-there is no way for normal perl code to corrupt this private information
-(unlike using extra elements of a hash object).
+The C<PERL_MAGIC_ext>, C<PERL_MAGIC_extvalue> and C<PERL_MAGIC_uvar> magic types
+are defined specifically for use by extensions and will not be used by perl
+itself.  Extensions can use C<PERL_MAGIC_ext> or C<PERL_MAGIC_extvalue> magic to
+'attach' private information to variables (typically objects).  This is
+especially useful because there is no way for normal perl code to corrupt this
+private information (unlike using extra elements of a hash object).
+C<PERL_MAGIC_extvalue> is value magic (unlike C<PERL_MAGIC_ext> and
+C<PERL_MAGIC_uvar>) meaning that on localization the new value will not be
+magical.
 
 Similarly, C<PERL_MAGIC_uvar> magic can be used much like tie() to call a
 C function any time a scalar's value is used or changed.  The C<MAGIC>'s
diff --git a/regen/mg_vtable.pl b/regen/mg_vtable.pl
index 215c71034e..578eabeaea 100644
--- a/regen/mg_vtable.pl
+++ b/regen/mg_vtable.pl
@@ -202,8 +202,10 @@ my %mg =
                 desc => 'Extra data for restricted hashes' },
      arylen_p => { char => '@', value_magic => 1,
                    desc => 'To move arylen out of XPVAV' },
-     ext => { char => '~', desc => 'Available for use by extensions',
+     ext => { char => '~', desc => 'Variable magic available for use by extensions',
               readonly_acceptable => 1 },
+     extvalue => { char => '^', desc => 'Value magic available for use by extensions',
+              readonly_acceptable => 1, value_magic => 1 },
      checkcall => { char => ']', value_magic => 1, vtable => 'checkcall',
                     desc => 'Inlining/mutation of call to this CV'},
      debugvar => { char => '*', desc => '$DB::single, signal, trace vars',