1=head1 NAME
2
3Readonly::XS - Companion module for Readonly.pm, to speed up read-only
4scalar variables.
5
6=head1 VERSION
7
8This document describes version 1.05 of Readonly::XS, February 24, 2009.
9
10=cut
11
12package Readonly::XS;
13
14use strict;
15use warnings;
16use vars qw($VERSION $MAGIC_COOKIE);
17
18$VERSION = '1.05';
19
20require XSLoader;
21XSLoader::load('Readonly::XS', $VERSION);
22
23
24# It is an error to use this from any module but Readonly.
25# But sooner or later, someone will.
26BEGIN
27{
28    no warnings 'uninitialized';
29    if ($MAGIC_COOKIE ne "Do NOT use or require Readonly::XS unless you're me.")
30    {
31        require Carp;
32        Carp::croak("Readonly::XS is not a standalone module. You should not use it directly.");
33    }
34}
35
36sub import
37{
38    my $func;
39    for $func (qw/is_sv_readonly make_sv_readonly/)
40    {
41        no strict 'refs';
42        no warnings 'redefine';
43        *{"Readonly::$func"} = \&$func;
44    }
45    $Readonly::XSokay = 1;
46}
47
48
491;
50__END__
51
52=head1 SYNOPSIS
53
54  Install this module, but do not use it.
55
56=head1 DESCRIPTION
57
58The Readonly module (q.v.) is an effective way to create
59non-modifiable variables.  However, it's relatively slow.
60
61The reason it's slow is that is implements the read-only-ness of
62variables via tied objects.  This mechanism is inherently slow.  Perl
63simply has to do a lot of work under the hood to make tied variables
64work.
65
66This module corrects the speed problem, at least with respect to
67scalar variables.  When Readonly::XS is installed, Readonly uses it to
68access the internals of scalar variables.  Instead of creating a
69scalar variable object and tying it, Readonly simply flips the
70SvREADONLY bit in the scalar's FLAGS structure.
71
72Readonly arrays and hashes are not sped up by this, since the
73SvREADONLY flag only works for scalars.  Arrays and hashes always use
74the tie interface.
75
76Why implement this as a separate module?  Because not everyone can use
77XS.  Not everyone has a C compiler.  Also, installations with a
78statically-linked perl may not want to recompile their perl binary
79just for this module.  Rather than render Readonly.pm useless for
80 these people, the XS portion was put into a separate module.
81
82Programs that you write do not need to know whether Readonly::XS is
83installed or not.  They should just "use Readonly" and let Readonly
84worry about whether or not it can use XS.  If the Readonly::XS is
85present, Readonly will be faster.  If not, it won't.  Either way, it
86will still work, and your code will not have to change.
87
88Your program can check whether Readonly.pm is using XS or not by
89examining the $Readonly::XSokay variable.  It will be true if the
90XS module was found and is being used.  Please do not change this
91variable.
92
93=head2 EXPORTS
94
95None.
96
97=head1 SEE ALSO
98
99Readonly.pm
100
101=head1 AUTHOR / COPYRIGHT
102
103Eric Roode, roode@cpan.org
104
105Copyright (c) 2003-2009 by Eric J. Roode. All Rights Reserved.
106This module is free software; you can redistribute it and/or modify it
107under the same terms as Perl itself.
108
109To avoid my spam filter, please include "Perl", "module", or this
110module's name in the message's subject line, and/or GPG-sign your
111message.
112
113=cut
114