Provided by: libclass-std-fast-perl_0.0.8-4_all bug

NAME

       Class::Std::Fast - faster but less secure than Class::Std

VERSION

       This document describes Class::Std::Fast 0.0.8

SYNOPSIS

           package MyClass;

           use Class::Std::Fast;

           1;

           package main;

           MyClass->new();

DESCRIPTION

       Class::Std::Fast allows you to use the beautiful API of Class::Std in a faster way than
       Class::Std does.

       You can get the object's ident via scalarifiyng your object.

       Getting the objects ident is still possible via the ident method, but it's faster to
       scalarify your object.

SUBROUTINES/METHODS

   new
       The constructor acts like Class::Std's constructor. For extended constructors see
       Constructors below.

           package FastObject;
           use Class::Std::Fast;

           1;
           my $fast_obj = FastObject->new();

   ident
       If you use Class::Std::Fast you shouldn't use this method. It's only existant for downward
       compatibility.

           # insted of
           my $ident = ident $self;

           # use
           my $ident = ${$self};

   initialize
           Class::Std::Fast::initialize();

       Imported from Class::Std. Please look at the documentation from Class::Std for more
       details.

   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.

       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.

   ID
       Returns an ID for the next object to construct.

       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 ID to assign to your blessed scalar.

       More precisely, you should construct your object like this:

           my $self = bless \do { my $foo = Class::Std::Fast::ID } , $class;

       Every other method of constructing Class::Std::Fast - based objects will lead to data
       corruption (duplicate object IDs).

   ID_GENERATOR_REF
       Returns a reference to the ID counter scalar.

       The current value is the next object ID !

       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).

       In case you do (like when creating perl objects in XS code), be sure to post-increment the
       ID counter after creating an object, which you may do from C with

           sv_inc( SvRV(id_counter_ref) )

   OBJECT_CACHE_REF
       Returns a reference to the object cache.

       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).

       See <L/EXTENSIONS TO Class::Std> for a description of the object cache facility.

EXTENSIONS TO Class::Std

   Methods
       real_can

       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 AUTOMETHOD.

       It is there if you need the old can() for speed reasons, and know what you're doing.

   Constructors
       Class::Std::Fast allows the user to chose between several constructor options.

       •   Standard constructor

           No special synopsis. Acts like Class::Std's constructor

       •   Basic constructor

            use Class::Std::Fast qw(2);
            use Class::Std::Fast constructor => 'basic';

           Does not call BUILD and START (and does not walk down the inheritance hierarchy
           calling BUILD and START).

           Does not perform any attribute initializations.

           Really fast, but very basic.

       •   No constructor

            use Class::Std::Fast qw(3);
            use Class::Std::Fast constructor => 'none';

           No constructor is exported into the calling class.

           The recommended usage is:

            use Class::Std::Fast constructor => none;
            sub new {
                my $self = bless \do { my $foo = Class::Std::Fast::ID } , $_[0];
                # do what you need to do after that
            }

           If you use the Object Cache (see below) the recommended usage is:

            use Class::Std::Fast constructor => 'none', cache => 1;
            sub new {
                my $self = pop @{ Class::Std::Fast::OBJECT_CACHE_REF()->{ $_[0] } }
                   || bless \do { my $foo = Class::Std::Fast::ID() } , $_[0];
            }

   Destructors
       Class::Std sorts the @ISA 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.

       Class authors may disable sorting by calling

        use Class::Std::Fast unsorted => 1;

       Use only if you know your class' complete inheritance tree...

   Object Cache
       Synopsis

        use Class::Std::Fast cache => 1;

       Description

       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.

       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.

       The object cache is filled by the DESTROY 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.

       new() 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).

       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.

       The exported constructor automatically uses the Object Cache when caching is enabled by
       setting the cache import flag to a true value.

       For an example of a user-defined constructor see "Constructors" above.

       Memory overhead

       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.

       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).

       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.

DIAGNOSTICS

       see Class::Std.

       Additional diagnostics are:

       •   Class::Std::Fast loaded too late - put >use Class::Std::Fast< somewhere at the top of
           your application (warning)

           Class::Std has been "use"d before Class::Std::Fast. While both classes happily coexist
           in one application, Class::Std::Fast must be loaded first for maximum speedup.

           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.

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

       •   version

       •   Class::Std

       •   Carp

INCOMPATIBILITIES

       see Class::Std

BUGS AND LIMITATIONS

       •   You can't use the :SCALARIFY attribute for your Objects.

           We use an increment for building identifiers and not Scalar::Util::refaddr like
           Class::Std.

       •   Inheriting from non-Class::Std::Fast modules does not work

           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.

           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.

       •   No runtime initialization with constructor => 'basic' / 'none'

           When eval'ing Class::Std::Fast based classes using the basic constructor, make sure
           the last line is

            Class::Std::Fast::initialize();

           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.

           The same holds true for constructor => 'none', of course.

           CUMULATIVE, PRIVATE, RESTRICTED and anticumulative methods won't work if you leave out
           this line.

RCS INFORMATIONS

       Last changed by
           $Author: ac0v $

       Id  $Id: Fast.pm 469 2008-05-26 11:26:35Z ac0v $

       Revision
           $Revision: 469 $

       Date
           $Date: 2008-05-26 13:26:35 +0200 (Mon, 26 May 2008) $

       HeadURL
           $HeadURL:
           file:///var/svn/repos/Hyper/Class-Std-Fast/branches/0.0.8/lib/Class/Std/Fast.pm $

AUTHORS

       Andreas 'ac0v' Specht  "<ACID@cpan.org>"

       Martin Kutter "<martin.kutter@fen-net.de>"

LICENSE AND COPYRIGHT

       Copyright (c) 2007, Andreas Specht "<ACID@cpan.org>".  All rights reserved.

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.