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