1package B::COW;
2
3use strict;
4use warnings;
5
6# ABSTRACT: B::COW additional B helpers to check COW status
7
8use base 'Exporter';
9
10our $VERSION = '0.004'; # VERSION: generated by DZP::OurPkgVersion
11
12use XSLoader;
13
14XSLoader::load(__PACKAGE__);
15
16my @all_export = qw{ can_cow is_cow cowrefcnt cowrefcnt_max };
17
18our @EXPORT_OK = (
19    @all_export,
20);
21
22our %EXPORT_TAGS = (
23    all => [@all_export],
24);
25
26
271;
28
29__END__
30
31=pod
32
33=encoding utf-8
34
35=head1 NAME
36
37B::COW - B::COW additional B helpers to check COW status
38
39=head1 VERSION
40
41version 0.004
42
43=head1 SYNOPSIS
44
45 #!perl
46
47 use strict;
48 use warnings;
49
50 use Test::More;    # just used for illustration purpose
51
52 use B::COW qw{:all};
53
54 if ( can_cow() ) {    # $] >= 5.020
55     ok !is_cow(undef);
56
57     my $str = "abcdef";
58     ok is_cow($str);
59     is cowrefcnt($str), 1;
60
61     my @a;
62     push @a, $str for 1 .. 100;
63
64     ok is_cow($str);
65     ok is_cow( $a[0] );
66     ok is_cow( $a[99] );
67     is cowrefcnt($str), 101;
68     is cowrefcnt( $a[-1] ), 101;
69
70     delete $a[99];
71     is cowrefcnt($str), 100;
72     is cowrefcnt( $a[-1] ), 100;
73
74     {
75         my %h = ( 'a' .. 'd' );
76         foreach my $k ( sort keys %h ) {
77             ok is_cow($k);
78             is cowrefcnt($k), 0;
79         }
80     }
81
82 }
83 else {
84     my $str = "abcdef";
85     is is_cow($str),    undef;
86     is cowrefcnt($str), undef;
87     is cowrefcnt_max(), undef;
88 }
89
90 done_testing;
91
92=head1 DESCRIPTION
93
94B::COW provides some naive additional B helpers to check the COW status of one SvPV.
95
96=head2 COW or Copy On Write introduction
97
98A COWed SvPV is sharing its string (the PV) with other SvPVs.
99It's a (kind of) Read Only C string, that would be Copied On Write (COW).
100
101More than one SV can share the same PV, but when one PV need to alter it,
102it would perform a copy of it, decrease the COWREFCNT counter.
103
104One SV can then drop the COW flag when it's the only one holding a pointer
105to the PV.
106
107The COWREFCNT is stored at the end of the PV, after the the "\0".
108
109That value is limited to 255, when we reach 255, a new PV would be created,
110
111=for markdown [![](https://github.com/atoomic/B-COW/workflows/linux/badge.svg)](https://github.com/atoomic/B-COW/actions) [![](https://github.com/atoomic/B-COW/workflows/macos/badge.svg)](https://github.com/atoomic/B-COW/actions) [![](https://github.com/atoomic/B-COW/workflows/windows/badge.svg)](https://github.com/atoomic/B-COW/actions)
112
113=head1 FUNCTIONS
114
115=head2 can_cow()
116
117Return a boolean value. True if your Perl version support Copy On Write for SvPVs
118
119=head2 is_cow( PV )
120
121Return a boolean value. True if the SV is cowed SvPV. (check the SV FLAGS)
122
123=head2 cowrefcnt( PV )
124
125Return one integer representing the COW RefCount value.
126If the string is not COW, then it will return undef.
127
128=head2 cowrefcnt_max()
129
130Will return the SV_COW_REFCNT_MAX of your Perl. (if COW is supported, this should
131be 255 unless customized).
132
133=head1 AUTHOR
134
135Nicolas R. <atoomic@cpan.org>
136
137=head1 COPYRIGHT AND LICENSE
138
139This software is copyright (c) 2018 by Nicolas R.
140
141This is free software; you can redistribute it and/or modify it under
142the same terms as the Perl 5 programming language system itself.
143
144=cut
145