view release on metacpan or  search on metacpan

lib/Class/InsideOut/Manual/Advanced.pod  view on Meta::CPAN

C<<< Class::InsideOut >>> also supports serialization of singleton objects for recent
versions of C<<< Storable >>> (2.14 or later) that support C<<< STORABLE_attach >>>.  Users
must signal that C<<< STORABLE_attach >>> should be used instead of C<<< STORABLE_thaw >>> by
adding C<<< :singleton >>> to their import line as follows:

   use Class::InsideOut qw( :std :singleton );

When attaching, the singleton object will be recreated in one of two ways:

1. If the singleton class contains an C<<< ATTACH >>> method, it will be called with
three arguments: the class name, a flag for whether this is part of a dclone,
and a data structure representing the object:

     $data = {
         class => ref $obj,              # class name
         type => $type,                  # object reference type
         contents => $contents,          # object reference contents
         properties => \%property_vals,  # HoH of classes and properties
     }

C<<< contents >>> is a reference of the same type as C<<< type >>>.  C<<< properties >>> is a
multi-level hash, with the names of the class and any superclasses as top-level
keys and property labels as second-level keys.  This data may be used to
reconstruct or reattach to the singleton.  The C<<< ATTACH >>> method should return
the singleton.

2. If no C<<< ATTACH >>> routine is found, but the class has or inherits a C<<< new >>>
method, then C<<< new >>> will be called with no arguments and the result will be
returned as the singleton.

=head2 Thread-safety

Because C<<< Class::InsideOut >>> uses memory addresses as indices to object
properties, special handling is necessary for use with threads.  When a new
thread is created, the Perl interpreter is cloned, and all objects in the new
thread will have new memory addresses.  Starting with Perl 5.8, if a C<<< CLONE >>>
function exists in a package, it will be called when a thread is created to
provide custom responses to thread cloning.  (See L<perlmod> for details.)
To avoid bugs in the implementation of threading, Perl 5.8.5 or later is
strongly recommended.

C<<< Class::InsideOut >>> itself has a C<<< CLONE >>> function that automatically fixes up
properties in a new thread to reflect the new memory addresses for all classes
created with C<<< Class::InsideOut >>>.  C<<< register >>> must be called on all newly
constructed inside-out objects to register them for use in
C<<< Class::InsideOut::CLONE >>>.

Users are strongly encouraged not to define their own C<<< CLONE >>> functions as
they may interfere with the operation of C<<< Class::InsideOut::CLONE >>> and leave
objects in an undefined state.  Future versions may support a user-defined
CLONE hook, depending on demand.

B<Limitations:> 

C<<< fork >>> on Perl for Win32 is emulated using threads since Perl
5.6. (See L<perlfork>.)  As Perl 5.6 did not support C<<< CLONE >>>, inside-out objects
that use memory addresses (e.g. C<<< Class::InsideOut >>>) are not fork-safe for Win32
on Perl 5.6.  Win32 Perl 5.8 C<<< fork >>> is supported.

The technique for thread-safety requires creating weak references using
C<<< Scalar::Util::weaken() >>>, which is implemented in XS.  If the XS-version of
L<Scalar::Util> is not installed or if run on an older version of Perl without
support for weak references, C<<< Class::InsideOut >>> will issue a warning and
continue without thread-safety.  Also, objects will leak memory unless manually
deregistered with a private function:

  # destroying an object when weaken() isn't availalbe
  Class::InsideOut::_deregister( $obj );
  undef $obj;

=head1 SEE ALSO

=over

=item *

L<Class::InsideOut>

=item *

L<Class::InsideOut::Manual::About>

=back

=head1 AUTHOR

David Golden <dagolden@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2006 by David A. Golden.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004

=cut