Document SvGAMAGIC(), and its significance w.r.t. the side effects of

inadvertently calling magic and overloading too often.

p4raw-id: //depot/perl@28021

2 files changed, 26 insertions, 0 deletions

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index ec4dc71af0..88f64435e2 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -3525,6 +3525,20 @@ See C<SvCUR>.  Access the character as *(SvEND(sv)).
 =for hackers
 Found in file sv.h
 
+=item SvGAMAGIC
+X<SvGAMAGIC>
+
+Returns true if the SV has get magic or overloading. If either is true then
+the scalar is active data, and has the potential to return a new value every
+time it is accessed. Hence you must be careful to only read it once per user
+logical operation and work with that returned value. If neither is true then
+the scalar's value cannot change unless written to.
+
+	char*	SvGAMAGIC(SV* sv)
+
+=for hackers
+Found in file sv.h
+
 =item SvGROW
 X<SvGROW>
 
diff --git a/sv.h b/sv.h
index b6d4b14447..71389c9d89 100644
--- a/sv.h
+++ b/sv.h
@@ -992,6 +992,18 @@ in gv.h: */
 	(SvROK(sv) && (SvFLAGS(SvRV(sv)) &= ~SVf_AMAGIC))
 #endif
 
+/*
+=for apidoc Am|char*|SvGAMAGIC|SV* sv
+
+Returns true if the SV has get magic or overloading. If either is true then
+the scalar is active data, and has the potential to return a new value every
+time it is accessed. Hence you must be careful to only read it once per user
+logical operation and work with that returned value. If neither is true then
+the scalar's value cannot change unless written to.
+
+=cut
+*/
+
 #define SvGAMAGIC(sv)           (SvGMAGICAL(sv) || SvAMAGIC(sv))
 
 #define Gv_AMG(stash)           (PL_amagic_generation && Gv_AMupdate(stash))