NAME
    Class::InsideOut - a safe, simple inside-out object construction kit

SYNOPSIS
     package My::Class;
 
     use Class::InsideOut qw( property register id );
     use Scalar::Util qw( refaddr );

     # declare a lexical property hash with 'my'
     property my %name; 

     sub new {
       my $class = shift;
       my $self = \do {my $scalar};
       bless $self, $class;
   
       # register the object for thread-safety
       register( $self ); 
     }

     sub name {
       my $self = shift;
       if ( @_ ) { 
   
         # use 'refaddr' to access properties for an object
         $name{ refaddr $self } = shift;
     
         return $self;
       }
       return $name{ refaddr $self };
     }
 
     sub greeting {
       my $self = shift;
   
       # use 'id' as a mnemonic alias for 'refaddr'
       return "Hello, my name is " . $name { id $self };
     }

DESCRIPTION
    This is an alpha release for a work in progress. It is a functional but
    incomplete implementation of a simple, safe and streamlined toolkit for
    building inside-out objects. Unlike most other inside-out object
    building modules already on CPAN, this module aims for minimalism and
    robustness.

    It uses no source filters, no attributes or CHECK blocks, supports any
    underlying object type including foreign inheritance, does not leak
    memory, is overloading-safe, is thread-safe for Perl 5.8 or better and
    should be mod_perl compatible.

    In its current state, it provides the minimal support necessary for safe
    inside-out objects. All other implementation details, including writing
    a constructor and accessors, are left to the user. Future versions will
    add basic accessor support and serialization support.

  Inside-out object basics

    To be written.

USAGE
  Importing `Class::InsideOut'

    To be written.

  Declaring and accessing object properties

    To be written.

  Object destruction

    To be written.

  Foreign inheritance

    To be written.

  Serialization

    To be written.

  Thread-safety

    To be written.

FUNCTIONS
  `property'

      property my %name;

    Declares an inside-out property. The argument must be a lexical hash,
    though the `my' keyword can be included as part of the argument rather
    than as a separate statement. No accessor is created, but the property
    will be tracked for memory cleanup during object destruction and for
    proper thread-safety.

  `register'

      register $object;

    Registers an object for thread-safety. This should be called as part of
    a constructor on a object blessed into the current package. Returns the
    object (without modification).

  `id'

      $name{ id $object } = "Larry";

    This is a shorter, mnemonic alias for `Scalar::Util::refaddr'. It
    returns the memory address of an object (just like `refaddr') as the
    index to access the properties of an inside-out object.

  `CLONE'

    `CLONE' is automatically exported to provide thread-safety to modules
    using `Class::InsideOut'. See perlmod for details. It will be called
    automatically by Perl if threads are in use and a new interpreter thread
    is created. It should never be called directly.

  `DESTROY'

    This destructor is automatically exported to modules using
    `Class::InsideOut' to clean up object property memory usage during
    object destruction. It should never be called directly. `DESTROY' will
    call a user-supplied `DEMOLISH' method if one exists to allow for
    additional, custom destruction actions such as closing sockets or
    database handles. `DEMOLISH' is called prior to deleting object
    properties.

SEE ALSO
    *   Object::InsideOut -- Currently the most full-featured, robust
        implementation of inside-out objects, but foreign inheritance is
        handled via delegation. Highly recommended if a more full-featured
        inside-out object builder is needed. Array-based mode is faster than
        hash-based implementations.

    *   Class::Std -- Despite the name, does not reflect best practices for
        inside-out objects. Does not provide thread-safety with CLONE, is
        not mod_perl safe and doesn't support foreign inheritance.

    *   Class::BuildMethods -- Generates accessors with encapsulated storage
        using a flyweight inside-out variant. Lexicals properties are
        hidden; accessors must be used everywhere. Not thread-safe.

    *   Lexical::Attributes -- The original inside-out implementation, but
        missing some key features like thread-safety. Also, uses source
        filters to provide Perl-6-like object syntax.

    *   Class::MakeMethods::Templates::InsideOut -- Not a very robust
        implementation. Not thread-safe. Not overloading-safe. Has a steep
        learning curve for the Class::MakeMethods system.

    *   Object::LocalVars -- My own original thought experiment with
        'outside-in' objects and local variable aliasing. Not
        production-safe and offers very weak encapsulation.

BUGS
    Please report bugs using the CPAN Request Tracker at
    http://rt.cpan.org/NoAuth/Bugs.html?Dist=Class-InsideOut

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

AUTHOR
    David A. Golden (DAGOLDEN)

    dagolden@cpan.org

    http://dagolden.com/

COPYRIGHT
    Copyright (c) 2006 by David A. Golden

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

    The full text of the license can be found in the LICENSE file included
    with this module.