Levels of Serialization¶

There are three levels to the serialization, each of which builds upon the other and each of which can be customized to the specific needs of your class.

base

The first (base) level is "pack" and "unpack". In this level the class is serialized into a Perl HASH reference, it is tagged with the class name and each instance attribute is stored. Very simple.

This level is not optional, it is the bare minimum that MooseX::Storage provides and all other levels build on top of this.

See MooseX::Storage::Basic for the fundamental implementation and options to "pack" and "unpack"

format

The second (format) level is "freeze" and "thaw". In this level the output of "pack" is sent to "freeze" or the output of "thaw" is sent to "unpack". This levels primary role is to convert to and from the specific serialization format and Perl land.

This level is optional, if you don't want/need it, you don't have to have it. You can just use "pack"/"unpack" instead.

io

The third (io) level is "load" and "store". In this level we are reading and writing data to file/network/database/etc.

This level is also optional, in most cases it does require a "format" role to also be used, the exception being the "StorableFile" role.

Behaviour modifiers¶

The serialization behaviour can be changed by supplying "traits" to either the class or an individual attribute.

This can be done as follows:

  use MooseX::Storage;
  # adjust behaviour for the entire class
  with Storage( traits => [Trait1, Trait2,...] );
  # adjust behaviour for an attribute
  has my_attr => (
    traits => [Trait1, Trait2, ...],
    ...
  );

The following class traits are currently bundled with MooseX::Storage:

OnlyWhenBuilt

Only attributes that have been built (i.e., where the predicate returns 'true') will be serialized. This avoids any potentially expensive computations.

See MooseX::Storage::Traits::OnlyWhenBuilt for details.

DisableCycleDetection

Disables the default checks for circular references, which is necessary if you use such references in your serialisable objects.

See MooseX::Storage::Traits::DisableCycleDetection for details.

The following attribute traits are currently bundled with MooseX::Storage:

DoNotSerialize

Skip serialization entirely for this attribute.

See MooseX::Storage::Meta::Attribute::Trait::DoNotSerialize for details.

How we serialize¶

There are always limits to any serialization framework -- there are just some things which are really difficult to serialize properly and some things which cannot be serialized at all.

What can be serialized?¶

Currently only numbers, string, ARRAY refs, HASH refs and other MooseX::Storage-enabled objects are supported.

With Array and Hash references the first level down is inspected and any objects found are serialized/deserialized for you. We do not do this recursively by default, however this feature may become an option eventually.

The specific serialize/deserialize routine is determined by the Moose type constraint a specific attribute has. In most cases subtypes of the supported types are handled correctly, and there is a facility for adding handlers for custom types as well. This will get documented eventually, but it is currently still in development.

What can not be serialized?¶

We do not support CODE references yet, but this support might be added in using B::Deparse or some other deep magic.

Scalar refs are not supported, mostly because there is no way to know if the value being referenced will be there when the object is inflated. I highly doubt will be ever support this in a general sense, but it would be possible to add this yourself for a small specific case.

Circular references are specifically disallowed, however if you break the cycles yourself then re-assemble them later you can get around this. The reason we disallow circular refs is because they are not always supported in all formats we use, and they tend to be very tricky to do for all possible cases. It is almost always something you want to have tight control over anyway.

Introspection¶

meta