From 2bf695bea7e58f1b998f32cc43c9df6f94fee169 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Fri, 20 May 2022 13:18:30 -0600 Subject: perlapi: Document SV_CHECK_THINKFIRST* --- sv.h | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) (limited to 'sv.h') diff --git a/sv.h b/sv.h index 9c0da53b9b..46769c5ad3 100644 --- a/sv.h +++ b/sv.h @@ -2153,11 +2153,17 @@ Returns the hash for C created by C>. #define sv_usepvn(sv, p, l) sv_usepvn_flags(sv, p, l, 0) #define sv_usepvn_mg(sv, p, l) sv_usepvn_flags(sv, p, l, SV_SMAGIC) -/* We are about to replace the SV's current value. So if it's copy on write - we need to normalise it. Use the SV_COW_DROP_PV flag hint to say that - the value is about to get thrown away, so drop the PV rather than go to - the effort of making a read-write copy only for it to get immediately - discarded. */ +/* +=for apidoc Am|void|SV_CHECK_THINKFIRST_COW_DROP|SV * sv + +Call this when you are about to replace the PV value in C, which is +potentially copy-on-write. It stops any sharing with other SVs, so that no +Copy on Write (COW) actually happens. This COW would be useless, as it would +immediately get changed to something else. This function also removes any +other encumbrances that would be problematic when changing C. + +=cut +*/ #define SV_CHECK_THINKFIRST_COW_DROP(sv) if (SvTHINKFIRST(sv)) \ sv_force_normal_flags(sv, SV_COW_DROP_PV) @@ -2177,6 +2183,19 @@ Returns the hash for C created by C>. #define CAN_COW_FLAGS (SVp_POK|SVf_POK) +/* +=for apidoc Am|void|SV_CHECK_THINKFIRST|SV * sv + +Remove any encumbrances from C, that need to be taken care of before it +is modifiable. For example if it is Copy on Write (COW), now is the time to +make that copy. + +If you know that you are about to change the PV value of C, instead use +L> to avoid the write that would be +immediately written again. + +=cut +*/ #define SV_CHECK_THINKFIRST(sv) if (SvTHINKFIRST(sv)) \ sv_force_normal_flags(sv, 0) -- cgit v1.2.1