NAME

       Tangram::Complicity - How to make Tangram-friendly classes

SYNOPSIS

         package YourNastyXSClass;

         sub px_freeze {
             return [ (shift)->gimme_as_perl ];
         }

         sub px_thaw {
             my $class = shift;
             my $self = $class->new( @_ );
         }

         1;

DESCRIPTION

       Tangram::Complicity does not exist.  To make matters worse, it isn't even implemented.  This page is a
       big FIXME for the code it refers to.  This page merely documents the API that classes must implement to
       be safely stored by "Tangram::Type::Dump::flatten".

       Note that to avoid unnecessary copying of memory structures from A to B, this method operates "in-place".

       So, therefore it is necessary for the reference type used in the return value, to be the same as the one
       in the real object.  This is explained later under "reftype mismatch".

       So - for instance, for Set::Object objects, which have a "px_freeze" method of:

         sub px_freeze {
             my $self = shift;
             return $self->members;
         }

         sub px_thaw {
             my $class = shift;
             return $class->new(@_);
         }

       [ note: This differs from the Storable API ("STORABLE_freeze" and "STORABLE_thaw").  This interface is
       actually reasonably sane - the Storable API required custom XS magic for Set::Object, for instance.
       Which has been implemented, but we've learned the lesson now :) ]

       In essence, the "px_freeze" method means "marshall yourself to pure Perl data types".  Note that
       different serialisation tools will treat ties, overload and magic remaining on the structure in their own
       way - so, create your own type of magic (a la Pixie::Info) if you really want to hang out-of-band
       information off them.

   reftype mismatch
       If you get a "reftype mismatch" error, it is because your YourClass->px_thaw function returned a
       different type of reference than the one that was passed to store to YourClass->px_freeze.

       This restriction only applies to the return value of the constructor "px_thaw", so this is usually fine.
       The return value from "px_freeze" will be wrapped in a (blessed) container of the correct reference type,
       regardless of its return type.

       ie. your function is called as:

          %{ $object } = %{ YourClass->px_thaw(@icicle) };

          @{ $object } = @{ YourClass->px_thaw(@icicle) };

          ${ $object } = ${ YourClass->px_thaw(@icicle) };

          *{ $object } = *{ YourClass->px_thaw(@icicle) };

          my $tmp = YourClass->px_thaw(@icicle);
          $object = sub { goto $tmp };

       This is an analogy, no temporary object is actually used in the scalar case, for instance; due to the use
       of tie.

       The reason for this is to allow for circular and back-references in the data structure; those references
       that point back point to the real blessed object, so to avoid the overhead of a two-pass algorithm, this
       restriction is made.  This is why the value is passed into STORABLE_thaw as $_[0].  For most people, it
       won't make a difference.

       However, it does have the nasty side effect that serialisers that can't handle all types of pure Perl
       data structures (such as, all current versions of YAML) are unable to store blessed scalars (eg,
       Set::Object's).