This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
COW documentation
authorFather Chrysostomos <sprout@cpan.org>
Sat, 28 Dec 2013 14:06:27 +0000 (06:06 -0800)
committerFather Chrysostomos <sprout@cpan.org>
Fri, 17 Jan 2014 01:58:47 +0000 (17:58 -0800)
plus read-only documentation, since hysterically the two are
intertwined.

pod/perlguts.pod
sv.c

index b9f6ba7..3fb5137 100644 (file)
@@ -908,6 +908,54 @@ following code:
 If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
 macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
 
+=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<sv_setsv>, 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<SvIsCOW(sv)>.
+
+You can force an SV to make its own copy of its string buffer by calling C<sv_force_normal(sv)> or SvPV_force_nolen(sv).
+
+If you want to make the SV drop its string buffer, use
+C<sv_force_normal_flags(sv, SV_COW_DROP_PV)> or simply
+C<sv_setsv(sv, NULL)>.
+
+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<mmap(2)> (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 (file)
--- a/sv.c
+++ b/sv.c
@@ -4955,6 +4955,10 @@ the C<flags> parameter gets passed to C<sv_unref_flags()>
 when unreffing.  C<sv_force_normal> 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
 */