From: Nicholas Clark <nick@ccl4.org>
Date: Sun, 30 Apr 2006 10:58:11 +0000 (+0000)
Subject: Document SvGAMAGIC(), and its significance w.r.t. the side effects of
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=d34786ba12ee5b96d9e34dd6fcdda158d7d2597b;p=p5sagit%2Fp5-mst-13.2.git

Document SvGAMAGIC(), and its significance w.r.t. the side effects of
inadvertently calling magic and overloading too often.

p4raw-id: //depot/perl@28021
---

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index ec4dc71..88f6443 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 b6d4b14..71389c9 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))