.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "XS 3pm"
.TH XS 3pm "2018-11-01" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Readonly::XS \- Companion module for Readonly.pm, to speed up read\-only
scalar variables.
.SH "VERSION"
.IX Header "VERSION"
This document describes version 1.05 of Readonly::XS, February 24, 2009.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  Install this module, but do not use it.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Readonly module (q.v.) is an effective way to create
non-modifiable variables.  However, it's relatively slow.
.PP
The reason it's slow is that is implements the read-only-ness of
variables via tied objects.  This mechanism is inherently slow.  Perl
simply has to do a lot of work under the hood to make tied variables
work.
.PP
This module corrects the speed problem, at least with respect to
scalar variables.  When Readonly::XS is installed, Readonly uses it to
access the internals of scalar variables.  Instead of creating a
scalar variable object and tying it, Readonly simply flips the
SvREADONLY bit in the scalar's \s-1FLAGS\s0 structure.
.PP
Readonly arrays and hashes are not sped up by this, since the
SvREADONLY flag only works for scalars.  Arrays and hashes always use
the tie interface.
.PP
Why implement this as a separate module?  Because not everyone can use
\&\s-1XS.\s0  Not everyone has a C compiler.  Also, installations with a
statically-linked perl may not want to recompile their perl binary
just for this module.  Rather than render Readonly.pm useless for
 these people, the \s-1XS\s0 portion was put into a separate module.
.PP
Programs that you write do not need to know whether Readonly::XS is
installed or not.  They should just \*(L"use Readonly\*(R" and let Readonly
worry about whether or not it can use \s-1XS.\s0  If the Readonly::XS is
present, Readonly will be faster.  If not, it won't.  Either way, it
will still work, and your code will not have to change.
.PP
Your program can check whether Readonly.pm is using \s-1XS\s0 or not by
examining the \f(CW$Readonly::XSokay\fR variable.  It will be true if the
\&\s-1XS\s0 module was found and is being used.  Please do not change this
variable.
.SS "\s-1EXPORTS\s0"
.IX Subsection "EXPORTS"
None.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Readonly.pm
.SH "AUTHOR / COPYRIGHT"
.IX Header "AUTHOR / COPYRIGHT"
Eric Roode, roode@cpan.org
.PP
Copyright (c) 2003\-2009 by Eric J. Roode. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.PP
To avoid my spam filter, please include \*(L"Perl\*(R", \*(L"module\*(R", or this
module's name in the message's subject line, and/or GPG-sign your
message.