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