From 4f4531b83e1fbbc2b40fedd6ef8b92d21e079d9f Mon Sep 17 00:00:00 2001 From: Father Chrysostomos Date: Sat, 28 Dec 2013 06:06:27 -0800 Subject: [PATCH] COW documentation plus read-only documentation, since hysterically the two are intertwined. --- pod/perlguts.pod | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ sv.c | 4 ++++ 2 files changed, 52 insertions(+) diff --git a/pod/perlguts.pod b/pod/perlguts.pod index b9f6ba7..3fb5137 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -908,6 +908,54 @@ following code: If the order of C and C had been reversed, then the macro C would need to be called instead of C. +=head2 Read-Only Values + +In Perl 5.16 and earlier, copy-on-write (see the next section) shared a +flag bit with read-only scalars. So the only way to test whether +C, etc., will raise a "Modification of a read-only value" error +in those versions is: + + SvREADONLY(sv) && !SvIsCOW(sv) + +Under Perl 5.18 and later, SvREADONLY only applies to read-only variables, +and, under 5.20, copy-on-write scalars can also be read-only, so the above +check is incorrect. You just want: + + SvREADONLY(sv) + +If you need to do this check often, define your own macro like this: + + #if PERL_VERSION >= 18 + # define SvTRULYREADONLY(sv) SvREADONLY(sv) + #else + # define SvTRULYREADONLY(sv) (SvREADONLY(sv) && !SvIsCOW(sv)) + #endif + +=head2 Copy on Write + +Perl implements a copy-on-write (COW) mechanism for scalars, in which +string copies are not immediately made when requested, but are deferred +until made necessary by one or the other scalar changing. This is mostly +transparent, but one must take care not to modify string buffers that are +shared by multiple SVs. + +You can test whether an SV is using copy-on-write with C. + +You can force an SV to make its own copy of its string buffer by calling C or SvPV_force_nolen(sv). + +If you want to make the SV drop its string buffer, use +C or simply +C. + +All of these functions will croak on read-only scalars (see the previous +section for more on those). + +To test that your code is behaving correctly and not modifying COW buffers, +on systems that support L (i.e., Unix) you can configure perl with +C<-Accflags=-DPERL_DEBUG_READONLY_COW> and it will turn buffer violations +into crashes. You will find it to be marvellously slow, so you may want to +skip perl's own tests. + =head2 Magic Variables [This section still under construction. Ignore everything here. Post no diff --git a/sv.c b/sv.c index 7f05c02..94f1906 100644 --- a/sv.c +++ b/sv.c @@ -4955,6 +4955,10 @@ the C parameter gets passed to C when unreffing. C calls this function with flags set to 0. +This function is expected to be used to signal to perl that this SV is +about to be written to, and any extra book-keeping needs to be taken care +of. Hence, it croaks on read-only values. + =cut */ -- 2.7.4