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.

   %{ $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 };