.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Class::Std::Fast 3pm"
.TH Class::Std::Fast 3pm "2022-11-19" "perl v5.36.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"
Class::Std::Fast \- faster but less secure than Class::Std
.SH "VERSION"
.IX Header "VERSION"
This document describes Class::Std::Fast 0.0.8
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    package MyClass;
\&
\&    use Class::Std::Fast;
\&
\&    1;
\&
\&    package main;
\&
\&    MyClass\->new();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Class::Std::Fast allows you to use the beautiful \s-1API\s0 of Class::Std in a
faster way than Class::Std does.
.PP
You can get the object's ident via scalarifiyng your object.
.PP
Getting the objects ident is still possible via the ident method, but it's
faster to scalarify your object.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.SS "new"
.IX Subsection "new"
The constructor acts like Class::Std's constructor. For extended constructors
see Constructors below.
.PP
.Vb 2
\&    package FastObject;
\&    use Class::Std::Fast;
\&
\&    1;
\&    my $fast_obj = FastObject\->new();
.Ve
.SS "ident"
.IX Subsection "ident"
If you use Class::Std::Fast you shouldn't use this method. It's only existant
for downward compatibility.
.PP
.Vb 2
\&    # insted of
\&    my $ident = ident $self;
\&
\&    # use
\&    my $ident = ${$self};
.Ve
.SS "initialize"
.IX Subsection "initialize"
.Vb 1
\&    Class::Std::Fast::initialize();
.Ve
.PP
Imported from Class::Std. Please look at the documentation from
Class::Std for more details.
.SS "Methods for accessing Class::Std::Fast's internals"
.IX Subsection "Methods for accessing Class::Std::Fast's internals"
Class::Std::Fast exposes some of it's internals to allow the construction
of Class::Std::Fast based objects from outside the auto-generated
constructors.
.PP
You should never use these methods for doing anything else. In fact you
should not use these methods at all, unless you know what you're doing.
.SS "\s-1ID\s0"
.IX Subsection "ID"
Returns an \s-1ID\s0 for the next object to construct.
.PP
If you ever need to override the constructor created by Class::Std::Fast,
be sure to use Class::Std::Fast::ID as the source for the \s-1ID\s0 to assign to
your blessed scalar.
.PP
More precisely, you should construct your object like this:
.PP
.Vb 1
\&    my $self = bless \edo { my $foo = Class::Std::Fast::ID } , $class;
.Ve
.PP
Every other method of constructing Class::Std::Fast \- based objects will lead
to data corruption (duplicate object IDs).
.SS "\s-1ID_GENERATOR_REF\s0"
.IX Subsection "ID_GENERATOR_REF"
Returns a reference to the \s-1ID\s0 counter scalar.
.PP
The current value is the \fBnext\fR object \s-1ID\s0 !
.PP
You should never use this method unless you're trying to create
Class::Std::Fast objects from outside Class::Std::Fast (and possibly outside
perl).
.PP
In case you do (like when creating perl objects in \s-1XS\s0 code), be sure to
post-increment the \s-1ID\s0 counter \fBafter\fR creating an object, which you may do
from C with
.PP
.Vb 1
\&    sv_inc( SvRV(id_counter_ref) )
.Ve
.SS "\s-1OBJECT_CACHE_REF\s0"
.IX Subsection "OBJECT_CACHE_REF"
Returns a reference to the object cache.
.PP
You should never use this method unless your're trying to (re\-)create
Class::Std::Fast objects from outside Class::Std::Fast (and possibly outside
perl).
.PP
See <L/EXTENSIONS \s-1TO\s0 Class::Std> for a description of the object cache
facility.
.SH "EXTENSIONS TO Class::Std"
.IX Header "EXTENSIONS TO Class::Std"
.SS "Methods"
.IX Subsection "Methods"
\fIreal_can\fR
.IX Subsection "real_can"
.PP
Class::Std::Fast saves away UNIVERSAL::can as Class::Std::Fast::real_can before
overwriting it. You should not use real_can, because it does not check for
subroutines implemented via \s-1AUTOMETHOD.\s0
.PP
It is there if you need the old \fBcan()\fR for speed reasons, and know what you're
doing.
.SS "Constructors"
.IX Subsection "Constructors"
Class::Std::Fast allows the user to chose between several constructor
options.
.IP "\(bu" 4
Standard constructor
.Sp
No special synopsis. Acts like Class::Std's constructor
.IP "\(bu" 4
Basic constructor
.Sp
.Vb 2
\& use Class::Std::Fast qw(2);
\& use Class::Std::Fast constructor => \*(Aqbasic\*(Aq;
.Ve
.Sp
Does not call \s-1BUILD\s0 and \s-1START\s0 (and does not walk down the inheritance
hierarchy calling \s-1BUILD\s0 and \s-1START\s0).
.Sp
Does not perform any attribute initializations.
.Sp
Really fast, but very basic.
.IP "\(bu" 4
No constructor
.Sp
.Vb 2
\& use Class::Std::Fast qw(3);
\& use Class::Std::Fast constructor => \*(Aqnone\*(Aq;
.Ve
.Sp
No constructor is exported into the calling class.
.Sp
The recommended usage is:
.Sp
.Vb 5
\& use Class::Std::Fast constructor => none;
\& sub new {
\&     my $self = bless \edo { my $foo = Class::Std::Fast::ID } , $_[0];
\&     # do what you need to do after that
\& }
.Ve
.Sp
If you use the Object Cache (see below) the recommended usage is:
.Sp
.Vb 5
\& use Class::Std::Fast constructor => \*(Aqnone\*(Aq, cache => 1;
\& sub new {
\&     my $self = pop @{ Class::Std::Fast::OBJECT_CACHE_REF()\->{ $_[0] } }
\&        || bless \edo { my $foo = Class::Std::Fast::ID() } , $_[0];
\& }
.Ve
.SS "Destructors"
.IX Subsection "Destructors"
Class::Std sorts the \f(CW@ISA\fR hierarchy before traversing it to avoid cleaning
up the wrong class first. However, this is unneccessary if the class in
question has a linear inheritance tree.
.PP
Class authors may disable sorting by calling
.PP
.Vb 1
\& use Class::Std::Fast unsorted => 1;
.Ve
.PP
Use only if you know your class' complete inheritance tree...
.SS "Object Cache"
.IX Subsection "Object Cache"
\fISynopsis\fR
.IX Subsection "Synopsis"
.PP
.Vb 1
\& use Class::Std::Fast cache => 1;
.Ve
.PP
\fIDescription\fR
.IX Subsection "Description"
.PP
While inside out objects are basically an implementation of the Flyweight
Pattern (object data is stored outside the object), there's still one aspect
missing: object reuse. While Class::Std::Fast does not provide flyweights
in the classical sense (one object re-used again and again), it provides
something close to it: An object cache for re-using destroyed objects.
.PP
The object cache is implemented as a simple hash with the class names of the
cached objects as keys, and a list ref of cached objects as values.
.PP
The object cache is filled by the \s-1DESTROY\s0 method exported into all
Class::Std::Fast based objects: Instead of actually destroying the blessed
scalar reference (Class::Std::Fast based objects are nothing more), the
object to be destroyed is pushed into it's class' object cache.
.PP
\&\fBnew()\fR in turn does not need to create a new blessed scalar, but can just pop
one off the object cache (which is a magnitude faster).
.PP
Using the object cache is recommended for persistent applications (like
running under mod_perl), or applications creating and destroying
lots of Class::Std::Fast based objects again and again.
.PP
The exported constructor automatically uses the Object Cache when caching is
enabled by setting the cache import flag to a true value.
.PP
For an example of a user-defined constructor see \*(L"Constructors\*(R" above.
.PP
\fIMemory overhead\fR
.IX Subsection "Memory overhead"
.PP
The object cache trades speed for memory. This is a very perlish way for
adressing performance issues, but may cause your application to blow up
if you're short of memory.
.PP
On a 32bit Linux, Devel::Size reports 44 bytes for a Class::Std::Fast based
object \- so a cache containing 1 000 000 (one million) of objects needs
around 50MB of memory (Devel Size only reports the memory use it can see \-
the actual usage is system dependent and something between 4 and 32 bytes
more).
.PP
If you are anxious about falling short of memory, only enable caching for
those classes whose objects you know to be frequently created and destroyed,
and leave it turned off for the less frequently used classes \- this gives you
both speed benefits, and avoids holding a cache of object that will never be
needed again.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
see Class::Std.
.PP
Additional diagnostics are:
.IP "\(bu" 4
Class::Std::Fast loaded too late \- put >use Class::Std::Fast< somewhere at the top of your application (warning)
.Sp
Class::Std has been \*(L"use\*(R"d before Class::Std::Fast. While both classes
happily coexist in one application, Class::Std::Fast must be loaded first
for maximum speedup.
.Sp
This is due to both classes overwriting UNIVERSAL::can. Class::Std::Fast uses
the original (fast) can where appropritate, but cannot access it if
Class::Std has overwritten it before with it's (slow) replacement.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.IP "\(bu" 4
version
.IP "\(bu" 4
Class::Std
.IP "\(bu" 4
Carp
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
see Class::Std
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
.IP "\(bu" 4
You can't use the :SCALARIFY attribute for your Objects.
.Sp
We use an increment for building identifiers and not Scalar::Util::refaddr
like Class::Std.
.IP "\(bu" 4
Inheriting from non\-Class::Std::Fast modules does not work
.Sp
You cannot inherit from non\-Class::Std::Fast classes, not even if you
overwrite the default constructor. To be more precise, you cannot inherit
from classes which use something different from numeric blessed scalar
references as their objects. Even so inheriting from similarly contructed
classes like Object::InsideOut could work, you would have to make sure that
object IDs cannot be duplicated. It is therefore strongly discouraged to
build classes with Class::Std::Fast derived from non\-Class::Std::Fast classes.
.Sp
If you really need to inherit from non\-Class::Std::Fast modules, make sure
you use Class::Std::Fast::ID as described above for creating objects.
.IP "\(bu" 4
No runtime initialization with constructor => 'basic' / 'none'
.Sp
When eval'ing Class::Std::Fast based classes using the basic constructor,
make sure the last line is
.Sp
.Vb 1
\& Class::Std::Fast::initialize();
.Ve
.Sp
In contrast to Class::Std, Class::Std::Fast performs no run-time
initialization when the basic constructor is enabled, so your code has to
do it itself.
.Sp
The same holds true for constructor => 'none', of course.
.Sp
\&\s-1CUMULATIVE, PRIVATE, RESTRICTED\s0 and anticumulative methods won't work if you
leave out this line.
.SH "RCS INFORMATIONS"
.IX Header "RCS INFORMATIONS"
.IP "Last changed by" 4
.IX Item "Last changed by"
\&\f(CW$Author:\fR ac0v $
.IP "Id" 4
.IX Item "Id"
\&\f(CW$Id:\fR Fast.pm 469 2008\-05\-26 11:26:35Z ac0v $
.IP "Revision" 4
.IX Item "Revision"
\&\f(CW$Revision:\fR 469 $
.IP "Date" 4
.IX Item "Date"
\&\f(CW$Date:\fR 2008\-05\-26 13:26:35 +0200 (Mon, 26 May 2008) $
.IP "HeadURL" 4
.IX Item "HeadURL"
\&\f(CW$HeadURL:\fR file:///var/svn/repos/Hyper/Class\-Std\-Fast/branches/0.0.8/lib/Class/Std/Fast.pm $
.SH "AUTHORS"
.IX Header "AUTHORS"
Andreas 'ac0v' Specht  \f(CW\*(C`<ACID@cpan.org>\*(C'\fR
.PP
Martin Kutter \f(CW\*(C`<martin.kutter@fen\-net.de>\*(C'\fR
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (c) 2007, Andreas Specht \f(CW\*(C`<ACID@cpan.org>\*(C'\fR.
All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.