NAME

POE::Filter::Reference - freeze data for sending; thaw data when it arrives

SYNOPSIS

  $filter = POE::Filter::Reference->new();
  $arrayref_of_perl_references =
    $filter->get($arrayref_of_raw_chunks_from_driver);
  $arrayref_of_serialized_perl_references =
     $filter->put($arrayref_of_perl_references);

DESCRIPTION

This filter packages referenced data for writing to a file or socket. Upon receipt of packaged data, it reconstitutes the original structure and returns a reference to it. This provides a handy way to ship data between processes and systems.

PUBLIC FILTER METHODS

new SERIALIZER, COMPRESSION

new SERIALIZER

new

new() creates and initializes a reference filter. It accepts two optional parameters: A serializer and a flag that determines whether Compress::Zlib will be used to compress serialized data.

Serializers are modelled after Storable. Storable has a nfreeze() function which translates referenced data into strings suitable for shipping across sockets. It also contains a freeze() method which is less desirable since it doesn't take network byte ordering into effect. Finally there's thaw() which translates frozen strings back into data.

SERIALIZER may be a package name or an object reference, or it may be omitted altogether.

If SERIALIZER is a package name, it is assumed that the package will have a thaw() function as well as etither an nfreeze() or a freeze() function.

  # Use Storable explicitly, specified by package name.
  my $filter = POE::Filter::Reference->new("Storable");

  # Use YAML, perhaps to pass data to programs not written with POE or
  # even in Perl at all.
  my $filter = POE::Filter::Reference->new("YAML");

If SERIALIZER is an object reference, it's assumed to have a thaw() method as well as either an nfreeze() or freeze() method.

  # Use an object.
  my $filter = POE::Filter::Reference->new($object);

If SERIALIZER is omitted or undef, the Reference filter will try to use Storable, FreezeThaw, and YAML. Filter::Reference will die if it cannot find one of these serializers.

  # Use the default filter (either Storable, FreezeThaw, or YAML).
  my $filter = POE::Filter::Reference->new();

Filter::Reference will try to compress frozen strings and uncompress them before thawing if COMPRESSION is true. It uses Compress::Zlib for this, but it works fine even without Zlib as long as COMPRESSION is false.

An object serializer must have a thaw() method. It also must have either a freeze() or nfreeze() method. If it has both freeze() and nfreeze(), then Filter::Reference will use nfreeze() for portability. The thaw() method accepts $self and a scalar; it should return a reference to the reconstituted data. The freeze() and nfreeze() methods receive $self and a reference; they should return a scalar with the reference's serialized representation.

If the serializer parameter is undef, a default one will be used. This lets programs specify compression without having to worry about naming a serializer.

For example:

  # Use the default filter (either Storable, FreezeThaw, or YAML).
  my $filter = POE::Filter::Reference->new();

  # Use an object, with compression.
  my $filter = POE::Filter::Reference->new($object, 1);

  # Use the default serializer, with compression.
  my $filter = POE::Filter::Reference->new(undef, 1);

The new() method will try to require any packages it needs.

The default behavior is to try Storable first, FreezeThaw second, YAML third, and finally fail.

get [ FROZEN_DATA ]

The get() method thaws a referenced list of FROZEN_DATA chunks back into references. References will be blessed, if necessary. If the references points to an object, be sure the receiving end has used the appropriate modules before calling their methods.

  $thingrefs = $filter_reference->get(\@stream_chunks);
  foreach (@$thingrefs) {
    ...;
  }

put [ REFERENCES ]

The put() method freezes one or more REFERENCES and returns their serialized, streamable representations as a list reference.

  $listref = $filter_reference->put([ \%thing_one, \@thing_two ]);
  foreach (@$listref) {
    ...;
  }

SEE ALSO

POE::Filter.

The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.

BUGS

Whatever is used to freeze and thaw data should be aware of potential differences in system byte orders. Also be careful that the same freeze/thaw code is used on both sides of a socket. That includes even the most minor version differences.

AUTHORS & COPYRIGHTS

The Reference filter was contributed by Arturn Bergman, with changes by Philip Gwyn.

Please see POE for more information about authors and contributors.