GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  TANGRAM::COMPLICITY (3)

.ds Aq ’

NAME

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

CONTENTS

SYNOPSIS



  package YourNastyXSClass;

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

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

  1;



DESCRIPTION

<B>Tangram::ComplicityB> 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 <B>YourClass->px_thawB> function returned a different type of reference than the one that was passed to store to <B>YourClass->px_freezeB>.

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

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 TANGRAM::COMPLICITY (3) 2015-10-09

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.