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

inadvertently calling magic and overloading too often.

p4raw-id: //depot/perl@28021

1 files changed, 12 insertions, 0 deletions

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))